Selecto.DB.Adapter behaviour (Selecto v0.4.5)

Copy Markdown

Behaviour contract for Selecto database adapters.

Adapter modules are responsible for:

  • establishing a connection handle from adapter-specific options,
  • executing SQL with bound params,
  • providing adapter placeholder strategy,
  • quoting identifiers when needed by adapter-specific tooling, and
  • declaring coarse feature support.

Streaming contract:

  • supports?(:stream) should return true only when stream/4 is implemented and can produce rows for the given connection context.
  • stream/4 is optional; adapters that do not support streaming should omit it and return false for supports?(:stream).

Summary

Types

connection()
connection_options()
execute_options()
introspection_options()
params()
query()
result()
schema_metadata()
server_version_result()
stream_result()

Callbacks

connect(connection_options)
connection_info(connection)
execute(connection, query, params, execute_options)
execute_pool(term, query, params, execute_options)
execute_raw(connection, query, params)
execute_repo_fallback(module, query, params)
format_datetime(iodata, t)
introspect_table(connection, t, introspection_options)
list_relations(connection, introspection_options)
list_tables(connection, introspection_options)
name()
placeholder(pos_integer)
quote_identifier(t)
refresh_materialized_view(connection, t, keyword)
rollup_literal_order(pos_integer)
rollup_sort_fix(connection)
rollup_sql(iodata)
server_version_major(connection)
start_pool(keyword, keyword, atom)
stream(connection, query, params, execute_options)
supports?(atom)
transaction(term, function, keyword)
validate_connection(connection)
with_connection(term, function)

Types

connection()

@type connection() :: term()

connection_options()

@type connection_options() :: keyword() | map() | term()

execute_options()

@type execute_options() :: keyword()

introspection_options()

@type introspection_options() :: keyword()

params()

@type params() :: [term()]

query()

@type query() :: String.t() | iodata()

result()

@type result() :: %{rows: list(), columns: [String.t()]}

schema_metadata()

@type schema_metadata() :: map()

server_version_result()

@type server_version_result() :: {:ok, pos_integer()} | {:error, term()}

stream_result()

@type stream_result() ::
  {:ok, Enumerable.t()} | {:ok, Enumerable.t(), [String.t()]} | {:error, term()}

Callbacks

connect(connection_options)

@callback connect(connection_options()) :: {:ok, connection()} | {:error, term()}

connection_info(connection)

(optional) 
@callback connection_info(connection()) :: map()

execute(connection, query, params, execute_options)

@callback execute(connection(), query(), params(), execute_options()) ::
  {:ok, result()} | {:error, term()}

execute_pool(term, query, params, execute_options)

(optional) 
@callback execute_pool(term(), query(), params(), execute_options()) ::
  {:ok, term()} | {:error, term()}

execute_raw(connection, query, params)

(optional) 
@callback execute_raw(connection(), query(), params()) ::
  {:ok, result()} | {:error, term()}

execute_repo_fallback(module, query, params)

(optional) 
@callback execute_repo_fallback(module(), query(), params()) ::
  {:ok, result()} | {:error, term()}

format_datetime(iodata, t)

(optional) 
@callback format_datetime(iodata(), String.t()) :: iodata()

introspect_table(connection, t, introspection_options)

(optional) 
@callback introspect_table(connection(), String.t(), introspection_options()) ::
  {:ok, schema_metadata()} | {:error, term()}

list_relations(connection, introspection_options)

(optional) 
@callback list_relations(connection(), introspection_options()) ::
  {:ok, [map()]} | {:error, term()}

list_tables(connection, introspection_options)

(optional) 
@callback list_tables(connection(), introspection_options()) ::
  {:ok, [String.t()]} | {:error, term()}

name()

@callback name() :: atom()

placeholder(pos_integer)

@callback placeholder(pos_integer()) :: iodata()

quote_identifier(t)

@callback quote_identifier(String.t()) :: String.t()

refresh_materialized_view(connection, t, keyword)

(optional) 
@callback refresh_materialized_view(connection(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

rollup_literal_order(pos_integer)

(optional) 
@callback rollup_literal_order(pos_integer()) :: iodata() | String.t()

rollup_sort_fix(connection)

(optional) 
@callback rollup_sort_fix(connection()) :: boolean()

rollup_sql(iodata)

(optional) 
@callback rollup_sql(iodata()) :: iodata()

server_version_major(connection)

(optional) 
@callback server_version_major(connection()) :: server_version_result()

start_pool(keyword, keyword, atom)

(optional) 
@callback start_pool(keyword(), keyword(), atom()) :: {:ok, term()} | {:error, term()}

stream(connection, query, params, execute_options)

(optional) 
@callback stream(connection(), query(), params(), execute_options()) :: stream_result()

supports?(atom)

@callback supports?(atom()) :: boolean()

transaction(term, function, keyword)

(optional) 
@callback transaction(term(), (term() -> term()), keyword()) ::
  {:ok, term()} | {:error, term()}

validate_connection(connection)

(optional) 
@callback validate_connection(connection()) :: :ok | {:error, term()}

with_connection(term, function)

(optional) 
@callback with_connection(term(), (term() -> term())) :: {:ok, term()} | {:error, term()}