db_connection v0.1.4 DBConnection.Proxy behaviour
A behaviour module for implementing a proxy module during the check out of a connection.
DBConnection.Proxy callback modules can wrap a DBConnection callback
module and state while it is outside the pool.
Summary
Macros
Use DBConnection.Proxy to set the behaviour and include default
implementations. The default implementation of checkout/3 stores
the checkout options as the proxy’s state, checkin/4 acts a no-op
and the remaining callbacks call the internal connection module with
the given arguments and state
Callbacks
Checks in the connection state so it can be checked into the pool. Return
{:ok, conn} to allow the checkin and continue, {:error, exception, conn}
to allow the checkin but raise an exception or
{:disconnect, exception, conn} to disconnect the connection and raise an
exception
Checks out the connection state to the proxy module. Return
{:ok, conn, state} to allow the checkout and continue,
{:error, exception, conn} to disallow the checkout and to raise an exception
or {:disconnect, exception, conn} to disconnect the connection and raise an
exception
Handle the beginning of a transaction. Return {:ok, conn, state} to
continue, {:error, exception, conn, state} to abort the transaction and
continue or {:disconnect, exception, conn} to abort the transaction
and disconnect the connection
Close a query. Return {:ok, conn, state} on success and to continue,
{:error, exception, conn, state} to return an error and continue, or
{:disconnect, exception, conn} to return an error and disconnect
Handle commiting a transaction. Return {:ok, conn, state} on success and
to continue, {:error, exception, conn, state} to abort the transaction and
continue or {:disconnect, exception, conn} to abort the transaction
and disconnect the connection
Execute a query. Return {:ok, result, conn, state} to return the result
result and continue, {:prepare, conn, state} to retry execute after
preparing the query, {:error, exception, conn, state} to return an error and
continue or {:disconnect, exception, conn} to return an error and
disconnect the connection
Execute a query and close it. See handle_execute/6
Prepare a query with the database. Return {:ok, query, conn, state} where
query is a query to pass to execute/4 or close/3,
{:error, exception, conn, state} to return an error and continue or
{:disconnect, exception, conn} to return an error and disconnect the
connection
Handle rolling back a transaction. Return {:ok, conn, state} on success
and to continue, {:error, exception, conn, state} to abort the transaction
and continue or {:disconnect, exception, conn} to abort the
transaction and disconnect
Setup the initial state of the proxy. Return {:ok, state} to continue,
:ignore not to use the proxy or {:error, exception} to raise an exception
Macros
Use DBConnection.Proxy to set the behaviour and include default
implementations. The default implementation of checkout/3 stores
the checkout options as the proxy’s state, checkin/4 acts a no-op
and the remaining callbacks call the internal connection module with
the given arguments and state.
Callbacks
Specs
checkin(module, Keyword.t, conn :: any, state :: any) ::
{:ok, new_conn :: any} |
{:error | :disconnect, Exception.t, new_conn :: any}Checks in the connection state so it can be checked into the pool. Return
{:ok, conn} to allow the checkin and continue, {:error, exception, conn}
to allow the checkin but raise an exception or
{:disconnect, exception, conn} to disconnect the connection and raise an
exception.
This callback is called before the connections checkin/1 and should undo
any changes made to the connection in checkout/3.
Specs
checkout(module, Keyword.t, conn :: any, state :: any) ::
{:ok, new_conn :: any, new_state :: any} |
{:error | :disconnect, Exception.t, new_conn :: any}Checks out the connection state to the proxy module. Return
{:ok, conn, state} to allow the checkout and continue,
{:error, exception, conn} to disallow the checkout and to raise an exception
or {:disconnect, exception, conn} to disconnect the connection and raise an
exception.
This callback is called after the connections checkout/1 callback and should
setup the connection state for use by the proxy module.
Specs
handle_begin(module, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Handle the beginning of a transaction. Return {:ok, conn, state} to
continue, {:error, exception, conn, state} to abort the transaction and
continue or {:disconnect, exception, conn} to abort the transaction
and disconnect the connection.
Specs
handle_close(module, DBConnection.query, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Close a query. Return {:ok, conn, state} on success and to continue,
{:error, exception, conn, state} to return an error and continue, or
{:disconnect, exception, conn} to return an error and disconnect.
Specs
handle_commit(module, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Handle commiting a transaction. Return {:ok, conn, state} on success and
to continue, {:error, exception, conn, state} to abort the transaction and
continue or {:disconnect, exception, conn} to abort the transaction
and disconnect the connection.
Specs
handle_execute(module, DBConneciton.query, DBConnection.params, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, DBConnection.result, new_conn :: any, new_state :: any} |
{:prepare, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Execute a query. Return {:ok, result, conn, state} to return the result
result and continue, {:prepare, conn, state} to retry execute after
preparing the query, {:error, exception, conn, state} to return an error and
continue or {:disconnect, exception, conn} to return an error and
disconnect the connection.
Specs
handle_execute_close(module, DBConneciton.query, DBConnection.params, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, DBConnection.result, new_conn :: any, new_state :: any} |
{:prepare, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Execute a query and close it. See handle_execute/6.
Specs
handle_prepare(module, DBConnection.query, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, DBConnection.query, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Prepare a query with the database. Return {:ok, query, conn, state} where
query is a query to pass to execute/4 or close/3,
{:error, exception, conn, state} to return an error and continue or
{:disconnect, exception, conn} to return an error and disconnect the
connection.
Specs
handle_rollback(module, opts :: Keyword.t, conn :: any, state :: any) ::
{:ok, new_conn :: any, new_state :: any} |
{:error, Exception.t, new_conn :: any, new_state :: any} |
{:disconnect, Exception.t, new_conn :: any}Handle rolling back a transaction. Return {:ok, conn, state} on success
and to continue, {:error, exception, conn, state} to abort the transaction
and continue or {:disconnect, exception, conn} to abort the
transaction and disconnect.
Specs
init(Keyword.t) ::
{:ok, state :: any} |
:ignore |
{:error, Exception.t}Setup the initial state of the proxy. Return {:ok, state} to continue,
:ignore not to use the proxy or {:error, exception} to raise an exception.
This callback is called before checking out a connection from the pool.