Mssqlex v0.0.7 Mssqlex.Protocol

Implementation of DBConnection behaviour for Mssqlex.ODBC.

Handles translation of concepts to what ODBC expects and holds state for a connection.

This module is not called directly, but rather through other Mssqlex modules or DBConnection functions.

Summary

Functions

Checks in the state to the connection process. Return {:ok, state} to allow the checkin or {:disconnect, exception, state} to disconnect

Checkouts the state from the connection process. Return {:ok, state} to allow the checkout or {:disconnect, exception, state} to disconnect

Connect to the database. Return {:ok, state} on success or {:error, exception} on failure

Disconnect from the database. Return :ok

Handle the beginning of a transaction. Return {:ok, result, state} to continue, {:error, exception, state} to abort the transaction and continue or {:disconnect, exception, state} to abort the transaction and disconnect

Close a query prepared by handle_prepare/3 with the database. Return {:ok, result, state} on success and to continue, {:error, exception, state} to return an error and continue, or {:disconnect, exception, state} to return an error and disconnect

Handle committing a transaction. Return {:ok, result, state} on success and to continue, {:error, exception, state} to abort the transaction and continue or {:disconnect, exception, state} to abort the transaction and disconnect

Deallocate a cursor declared by handle_declare/4' with the database. Return{:ok, result, state}on success and to continue,{:error, exception, state}to return an error and continue, or{:disconnect, exception, state}` to return an error and disconnect

Declare a cursor using a query prepared by handle_prepare/3. Return {:ok, cursor, state} to start a cursor for a stream and continue, {:error, exception, state} to return an error and continue or {:disconnect, exception, state} to return an error and disconnect

Execute a query prepared by handle_prepare/3. Return {:ok, result, state} to return the result result and continue, {:error, exception, state} to return an error and continue or {:disconnect, exception, state} to return an error and disconnect

Fetch the first result from a cursor declared by handle_declare/4. Return {:ok, result, state} to return the result result and continue, {:deallocate, result, state} to return the result result and deallocate, {:error, exception, state} to return an error and close the cursor, {:disconnect, exception, state} to return an error and disconnect

Handle a message received by the connection process when checked in. Return {:ok, state} to continue or {:disconnect, exception, state} to disconnect

Fetch the next result from a cursor declared by handle_declare/4. Return {:ok, result, state} to return the result result and continue, {:deallocate, result, state} to return the result result and deallocate, {:error, exception, state} to return an error and close the cursor, {:disconnect, exception, state} to return an error and disconnect

Prepare a query with the database. Return {:ok, query, state} where query is a query to pass to execute/4 or close/3, {:error, exception, state} to return an error and continue or {:disconnect, exception, state} to return an error and disconnect

Handle rolling back a transaction. Return {:ok, result, state} on success and to continue, {:error, exception, state} to abort the transaction and continue or {:disconnect, exception, state} to abort the transaction and disconnect

Called when the connection has been idle for a period of time. Return {:ok, state} to continue or {:disconnect, exception, state} to disconnect

Types

cursor()
cursor() :: any
params()
params() :: any
query()
query() :: Mssqlex.Query.t
result()
result() :: Mssqlex.Result.t
state()
state() :: %Mssqlex.Protocol{conn_opts: Keyword.t, mssql: :idle | :transaction, pid: pid}

Functions

checkin(state)
checkin(state) ::
  {:ok, state} |
  {:disconnect, Exception.t, state}

Checks in the state to the connection process. Return {:ok, state} to allow the checkin or {:disconnect, exception, state} to disconnect.

This callback is called when the control of the state is passed back to the connection process. It should reverse any changes made in checkout/2.

This callback is called in the connection process.

Callback implementation for DBConnection.checkin/1.

checkout(state)
checkout(state) ::
  {:ok, state} |
  {:disconnect, Exception.t, state}

Checkouts the state from the connection process. Return {:ok, state} to allow the checkout or {:disconnect, exception, state} to disconnect.

This callback is called when the control of the state is passed to another process. checkin/1 is called with the new state when control is returned to the connection process.

Messages are discarded, instead of being passed to handle_info/2, when the state is checked out.

This callback is called in the connection process.

Callback implementation for DBConnection.checkout/1.

connect(opts)
connect(opts :: Keyword.t) ::
  {:ok, state} |
  {:error, Exception.t}

Connect to the database. Return {:ok, state} on success or {:error, exception} on failure.

If an error is returned it will be logged and another connection attempt will be made after a backoff interval.

This callback is called in the connection process.

Callback implementation for DBConnection.connect/1.

disconnect(arg1, arg2)
disconnect(err :: Exception.t, state) :: :ok

Disconnect from the database. Return :ok.

The exception as first argument is the exception from a :disconnect 3-tuple returned by a previous callback.

If the state is controlled by a client and it exits or takes too long to process a request the state will be last known state. In these cases the exception will be a DBConnection.ConnectionError.

This callback is called in the connection process.

Callback implementation for DBConnection.disconnect/2.

handle_begin(arg1, state)
handle_begin(opts :: Keyword.t, state) ::
  {:ok, result, state} |
  {:error | :disconnect, Exception.t, state}

Handle the beginning of a transaction. Return {:ok, result, state} to continue, {:error, exception, state} to abort the transaction and continue or {:disconnect, exception, state} to abort the transaction and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_begin/2.

handle_close(arg1, arg2, state)
handle_close(query, opts :: Keyword.t, state) ::
  {:ok, result, state} |
  {:error | :disconnect, Exception.t, state}

Close a query prepared by handle_prepare/3 with the database. Return {:ok, result, state} on success and to continue, {:error, exception, state} to return an error and continue, or {:disconnect, exception, state} to return an error and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_close/3.

handle_commit(arg1, state)
handle_commit(opts :: Keyword.t, state) ::
  {:ok, result, state} |
  {:error | :disconnect, Exception.t, state}

Handle committing a transaction. Return {:ok, result, state} on success and to continue, {:error, exception, state} to abort the transaction and continue or {:disconnect, exception, state} to abort the transaction and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_commit/2.

handle_deallocate(, , , state)

Deallocate a cursor declared by handle_declare/4' with the database. Return{:ok, result, state}on success and to continue,{:error, exception, state}to return an error and continue, or{:disconnect, exception, state}to return an error and disconnect. This callback is called in the client process. Callback implementation for [DBConnection.handle_deallocate/4`](https://hexdocs.pm/db_connection/1.1.1/DBConnection.html#c:handle_deallocate/4).

handle_declare(, , , state)

Declare a cursor using a query prepared by handle_prepare/3. Return {:ok, cursor, state} to start a cursor for a stream and continue, {:error, exception, state} to return an error and continue or {:disconnect, exception, state} to return an error and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_declare/4.

handle_execute(query, params, opts, state)
handle_execute(query, params, opts :: Keyword.t, state) ::
  {:ok, result, state} |
  {:error | :disconnect, Exception.t, state}

Execute a query prepared by handle_prepare/3. Return {:ok, result, state} to return the result result and continue, {:error, exception, state} to return an error and continue or {:disconnect, exception, state} to return an error and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_execute/4.

handle_first(, , , state)

Fetch the first result from a cursor declared by handle_declare/4. Return {:ok, result, state} to return the result result and continue, {:deallocate, result, state} to return the result result and deallocate, {:error, exception, state} to return an error and close the cursor, {:disconnect, exception, state} to return an error and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_first/4.

handle_info(, state)

Handle a message received by the connection process when checked in. Return {:ok, state} to continue or {:disconnect, exception, state} to disconnect.

Messages received by the connection process when checked out will be logged and discared.

This callback is called in the connection process.

Callback implementation for DBConnection.handle_info/2.

handle_next(, , , state)

Fetch the next result from a cursor declared by handle_declare/4. Return {:ok, result, state} to return the result result and continue, {:deallocate, result, state} to return the result result and deallocate, {:error, exception, state} to return an error and close the cursor, {:disconnect, exception, state} to return an error and disconnect.

This callback is called in the client process.

Callback implementation for DBConnection.handle_next/4.

handle_prepare(query, arg2, state)
handle_prepare(query, opts :: Keyword.t, state) ::
  {:ok, query, state} |
  {:error | :disconnect, Exception.t, state}

Prepare a query with the database. Return {:ok, query, state} where query is a query to pass to execute/4 or close/3, {:error, exception, state} to return an error and continue or {:disconnect, exception, state} to return an error and disconnect.

This callback is intended for cases where the state of a connection is needed to prepare a query and/or the query can be saved in the database to call later.

This callback is called in the client process.

Callback implementation for DBConnection.handle_prepare/3.

handle_rollback(arg1, state)
handle_rollback(opts :: Keyword.t, state) ::
  {:ok, result, state} |
  {:error | :disconnect, Exception.t, state}

Handle rolling back a transaction. Return {:ok, result, state} on success and to continue, {:error, exception, state} to abort the transaction and continue or {:disconnect, exception, state} to abort the transaction and disconnect.

A transaction will be rolled back if an exception occurs or rollback/2 is called.

This callback is called in the client process.

Callback implementation for DBConnection.handle_rollback/2.

ping(state)

Called when the connection has been idle for a period of time. Return {:ok, state} to continue or {:disconnect, exception, state} to disconnect.

This callback is called if no callbacks have been called after the idle timeout and a client process is not using the state. The idle timeout can be configured by the :idle_timeout option. This function can be called whether the connection is checked in or checked out.

This callback is called in the connection process.

Callback implementation for DBConnection.ping/1.