Ecto.Adapter behaviour
This module specifies the adapter API that an adapter is required to implement.
Types ↑
t :: module
source :: {prefix :: binary, table :: binary, model :: atom}
returning :: [atom]
prepared :: term
preprocess :: (Macro.t, term -> term)
autogenerate_id :: {field :: atom, type :: :id | :binary_id, value :: term} | nil
Callbacks
Specs:
- delete(repo, source, filters, autogenerate_id, options) :: {:ok, Keyword.t} | {:error, :stale} | no_return
Deletes a sigle model 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) to be given as filter. Therefore,
in case there is no record matching the given filters,
{:error, :stale} is returned.
Autogenerate
The autogenerate_id tells if there is an autogenerated primary key and
if so, its name type and value. The type is :id or :binary_id and
the adapter should raise if it cannot handle those types.
If the value is nil, it means there is no autogenerate primary key.
Specs:
- dump(Ecto.Type.t, term) :: {:ok, term} | :error
Called for every known Ecto type when dumping data to the adapter.
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 dump(:boolean, false), do: {:ok, 0}
def dump(:boolean, true), do: {:ok, 1}
def dump(type, value), do: Ecto.Type.dump(type, value, &dump/2)Notice the Ecte.Type.dump/3 provides a default implementation
which also expects the current dump/2 for handling recursive
types like arrays and embeds.
Finally, notice 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 dump(:binary_id, value), do: dump(Ecto.UUID, value)
def dump(type, value), do: Ecto.Type.dump(type, value, &dump/2)Specs:
- embed_id(Ecto.Embedded.t) :: String.t
Called every time an id is needed for an embedded model.
It receives the Ecto.Embedded struct.
Specs:
- execute(repo, meta :: map, prepared, params :: list, preprocess | nil, options) :: {integer, [[term]] | nil} | no_return
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 preprocess function that should be invoked for each
selected field in the query result in order to convert them to the
expected Ecto type. The preprocess function will be nil if no
result set is expected from the query.
Specs:
- insert(repo, source, fields, autogenerate_id, returning, options) :: {:ok, Keyword.t} | no_return
Inserts a single new model in the data store.
Autogenerate
The autogenerate_id tells if there is a primary key to be autogenerated
and, if so, its name, type and value. The type is :id or :binary_id and
the adapter should raise if it cannot handle those types.
If the value is nil, it means no value was supplied by the user and
the database MUST return a new one.
autogenerate_id also allows drivers to detect if a value was assigned
to a primary key that does not support assignment. In this case, value
will be a non nil value.
Specs:
- load(Ecto.Type.t, term) :: {:ok, term} | :error
Called for every known Ecto type when loading data from the adapter.
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 load(:boolean, 0), do: {:ok, false}
def load(:boolean, 1), do: {:ok, true}
def load(type, value), do: Ecto.Type.load(type, value, &load/2)Notice the Ecte.Type.load/3 provides a default implementation
which also expects the current load/2 for handling recursive
types like arrays and embeds.
Finally, notice 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 load(:binary_id, value), do: load(Ecto.UUID, value)
def load(type, value), do: Ecto.Type.load(type, value, &load/2)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:
- start_link(repo, options) :: {:ok, pid} | :ok | {:error, {:already_started, pid}} | {:error, term}
Starts any connection pooling or supervision and return {:ok, pid}
or just :ok if nothing needs to be done.
Returns {:error, {:already_started, pid}} if the repo already
started or {:error, term} in case anything else goes wrong.
Adapter start
Because some Ecto tasks like migration may run without starting
the parent application, it is recommended that start_link in
adapters make sure the adapter application is started by calling
Application.ensure_all_started/1.
Specs:
- update(repo, source, fields, filters, autogenerate_id, returning, options) :: {:ok, Keyword.t} | {:error, :stale} | no_return
Updates a single model 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) to be given as filter. Therefore,
in case there is no record matching the given filters,
{:error, :stale} is returned.
Autogenerate
The autogenerate_id tells if there is an autogenerated primary key and
if so, its name type and value. The type is :id or :binary_id and
the adapter should raise if it cannot handle those types.
If the value is nil, it means there is no autogenerate primary key.
autogenerate_id also allows drivers to detect if a value was assigned
to a primary key that does not support assignment. In this case, value
will be a non nil value.