db_connection

v0.1.6

db_connection v0.1.6 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

__using__()

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, checkin/4 and terminate/3 act as no-ops. The remaining callbacks call the internal connection module with the given arguments and state

Callbacks

checkin(module, arg1, conn, state)

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, state} to allow the checkin but raise an exception or {:disconnect, exception, conn, state} to disconnect the connection and raise an exception

checkout(module, arg1, conn, state)

Checks out the connection state to the proxy module. Return {:ok, conn, state} to allow the checkout and continue, {:error, exception, conn, state} to disallow the checkout and to raise an exception or {:disconnect, exception, conn, state} to disconnect the connection and raise an exception

handle_begin(module, opts, conn, state)

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, state} to abort the transaction and disconnect the connection

handle_close(module, arg1, opts, conn, state)

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, state} to return an error and disconnect

handle_commit(module, opts, conn, state)

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, state} to abort the transaction and disconnect the connection

handle_execute(module, arg1, arg2, opts, conn, state)

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, state} to return an error and disconnect the connection

handle_execute_close(module, arg1, arg2, opts, conn, state)

Execute a query and close it. See handle_execute/6

handle_prepare(module, arg1, opts, conn, state)

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, state} to return an error and disconnect the connection

handle_rollback(module, opts, conn, state)

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, state} to abort the transaction and disconnect

init(arg0)

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

terminate(arg0, opts, state)

Terminate the proxy. Should cleanup any side effects as process may not exit

Macros

__using__()

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, checkin/4 and terminate/3 act as no-ops. The remaining callbacks call the internal connection module with the given arguments and state.

Callbacks

checkin(module, arg1, conn, state)

Specs

checkin(module, Keyword.t, conn :: any, state :: any) ::
  {:ok, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to allow the checkin but raise an exception or {:disconnect, exception, conn, state} 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.

checkout(module, arg1, conn, state)

Specs

checkout(module, Keyword.t, conn :: any, state :: any) ::
  {:ok, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: any}

Checks out the connection state to the proxy module. Return {:ok, conn, state} to allow the checkout and continue, {:error, exception, conn, state} to disallow the checkout and to raise an exception or {:disconnect, exception, conn, state} 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.

handle_begin(module, opts, conn, state)

Specs

handle_begin(module, opts :: Keyword.t, conn :: any, state :: any) ::
  {:ok, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to abort the transaction and disconnect the connection.

handle_close(module, arg1, opts, conn, state)

Specs

handle_close(module, DBConnection.query, opts :: Keyword.t, conn :: any, state :: any) ::
  {:ok, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to return an error and disconnect.

handle_commit(module, opts, conn, state)

Specs

handle_commit(module, opts :: Keyword.t, conn :: any, state :: any) ::
  {:ok, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to abort the transaction and disconnect the connection.

handle_execute(module, arg1, arg2, opts, conn, state)

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 | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to return an error and disconnect the connection.

handle_execute_close(module, arg1, arg2, opts, conn, state)

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 | :disconnect, Exception.t, new_conn :: any, new_state :: any}

Execute a query and close it. See handle_execute/6.

handle_prepare(module, arg1, opts, conn, state)

Specs

handle_prepare(module, DBConnection.query, opts :: Keyword.t, conn :: any, state :: any) ::
  {:ok, DBConnection.query, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to return an error and disconnect the connection.

handle_rollback(module, opts, conn, state)

Specs

handle_rollback(module, opts :: Keyword.t, conn :: any, state :: any) ::
  {:ok, new_conn :: any, new_state :: any} |
  {:error | :disconnect, Exception.t, new_conn :: any, new_state :: 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, state} to abort the transaction and disconnect.

init(arg0)

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.

terminate(arg0, opts, state)

Specs

terminate(:normal | {:disconnect, Exception.t} | {:stop, any}, opts :: Keyword.t, state :: any) :: any

Terminate the proxy. Should cleanup any side effects as process may not exit.

This callback is called after checking in a connection to the pool.