Ecto v2.0.0-beta.2 Ecto.Adapter behaviour
This module specifies the adapter API that an adapter is required to implement.
Summary
Callbacks
The callback invoked in case the adapter needs to inject code
Defines the application that powers the adapter
Called to autogenerate a value for id/embed_id/binary_id
Returns the childspec that starts the adapter process
Deletes a single struct with the given filters
Returns the dumprs for a given type
Executes a previously prepared query
Inserts a single new struct in the data store
Inserts multiple entries into the data store
Returns the loaders for a given type
Commands invoked to prepare a query for all
, update_all
and delete_all
Updates a single struct with the given filters
Types
autogenerate_id ::
{field :: atom, type :: :id | :binary_id, value :: term} |
nil
cached :: term
prepared :: term
query_meta :: %{prefix: binary | nil, sources: tuple, assocs: term, preloads: term, select: term, fields: [term]}
Ecto.Query metadata fields (stored in cache)
returning :: [atom]
schema_meta :: %{source: source, schema: atom, context: term, autogenerate_id: {atom, :id | :binary_id}}
Ecto.Schema metadata fields
source :: {prefix :: binary | nil, table :: binary}
t :: module
Callbacks
Specs
__before_compile__(env :: Macro.Env.t, Macro.Env.t) :: Macro.t
The callback invoked in case the adapter needs to inject code.
Specs
autogenerate(:id | :binary_id | :embed_id) ::
term |
nil |
no_return
Called to autogenerate a value for id/embed_id/binary_id.
Returns the autogenerated value, or nil if it must be autogenerated inside the storage or raise if not supported.
Specs
child_spec(repo, options) :: Supervisor.Spec.spec
Returns the childspec that starts the adapter process.
Specs
delete(repo, schema_meta, filters, options) ::
{:ok, fields} |
{:invalid, constraints} |
{:error, :stale} |
no_return
Deletes a single struct with the given filters.
While filters
can be any record column, it is expected that
at least the primary key (or any other key that uniquely
identifies an existing record) be given as a filter. Therefore,
in case there is no record matching the given filters,
{:error, :stale}
is returned.
Specs
dumpers(Ecto.Type.primitive, Ecto.Type.t) :: [(term -> {:ok, term} | :error) | Ecto.Type.t]
Returns the dumprs for a given type.
It receives the primitive type and the Ecto type (which may be primitive as well). It returns a list of dumpers with the given type usually at the beginning.
This allows developers to properly translate values coming from the Ecto into adapter ones. For example, if the database does not support booleans but instead returns 0 and 1 for them, you could add:
def dumpers(:boolean, type), do: [type, &bool_encode/1]
def dumpers(_primitive, type), do: [type]
defp bool_encode(false), do: {:ok, 0}
defp bool_encode(true), do: {:ok, 1}
All adapters are required to implement a clause or :binary_id types, since they are adapter specific. If your adapter does not provide binary ids, you may simply use Ecto.UUID:
def dumpers(:binary_id, type), do: [type, Ecto.UUID]
def dumpers(_primitive, type), do: [type]
Specs
Executes a previously prepared query.
It must return a tuple containing the number of entries and
the result set as a list of lists. The result set may also be
nil
if a particular operation does not support them.
The meta
field is a map containing some of the fields found
in the Ecto.Query
struct.
It receives a process function that should be invoked for each
selected field in the query result in order to convert them to the
expected Ecto type. The process
function will be nil if no
result set is expected from the query.
Specs
insert(repo, schema_meta, fields, returning, options) ::
{:ok, fields} |
{:invalid, constraints} |
no_return
Inserts a single new struct in the data store.
Autogenerate
The primary key will be automatically included in returning
if the
field has type :id
or :binary_id
and no value was set by the
developer or none was autogenerated by the adapter.
Specs
insert_all(repo, schema_meta, header :: [atom], [fields], returning, options) ::
{integer, [[term]] | nil} |
no_return
Inserts multiple entries into the data store.
Specs
loaders(Ecto.Type.primitive, Ecto.Type.t) :: [(term -> {:ok, term} | :error) | Ecto.Type.t]
Returns the loaders for a given type.
It receives the primitive type and the Ecto type (which may be primitive as well). It returns a list of loaders with the given type usually at the end.
This allows developers to properly translate values coming from the adapters into Ecto ones. For example, if the database does not support booleans but instead returns 0 and 1 for them, you could add:
def loaders(:boolean, type), do: [&bool_decode/1, type]
def loaders(_primitive, type), do: [type]
defp bool_decode(0), do: {:ok, false}
defp bool_decode(1), do: {:ok, true}
All adapters are required to implement a clause for :binary_id
types,
since they are adapter specific. If your adapter does not provide binary
ids, you may simply use Ecto.UUID:
def loaders(:binary_id, type), do: [Ecto.UUID, type]
def loaders(_primitive, type), do: [type]
Specs
prepare(:all | :update_all | :delete_all, query :: Ecto.Query.t) ::
{:cache, prepared} |
{:nocache, prepared}
Commands invoked to prepare a query for all
, update_all
and delete_all
.
The returned result is given to execute/6
.
Specs
update(repo, schema_meta, fields, filters, returning, options) ::
{:ok, fields} |
{:invalid, constraints} |
{:error, :stale} |
no_return
Updates a single struct with the given filters.
While filters
can be any record column, it is expected that
at least the primary key (or any other key that uniquely
identifies an existing record) be given as a filter. Therefore,
in case there is no record matching the given filters,
{:error, :stale}
is returned.