db_connection v0.1.5 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 init/1 stores
the checkout options as the proxy’s state, checkout/4 and checkin/4 act
as no-ops 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 init/1 stores
the checkout options as the proxy’s state, checkout/4 and checkin/4 act
as no-ops 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.