Ecto.Adapter behaviour

This module specifies the adapter API that an adapter is required to implement.

Source

Types

t :: module

source :: {table :: binary, model :: atom}

returning :: [atom]

preprocess :: (Macro.t, term -> term)

autogenerate_id :: {field :: atom, type :: :id | :binary_id, value :: term} | nil

Callbacks

all/5

Specs:

Fetches all results from the data store based on the given query.

It receives a preprocess function responsible that should be invoked for each selected field in the query result in order to convert them to the expected Ecto type.

Source
delete/5

Specs:

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.

Source
delete_all/4

Specs:

  • delete_all(repo, query :: Ecto.Query.t, params :: list, options :: Keyword.t) :: {integer, nil} | no_return

Deletes all entities matching the given query.

The query shall only have where and join expressions and a single from expression. It returns a tuple containing the number of entries and any returned result as second element

Source
dump/2

Specs:

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)
Source
embed_id/1

Specs:

Called every time an id is needed for an embedded model.

It receives the Ecto.Embedded struct.

Source
insert/6

Specs:

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.

Source
load/2

Specs:

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)
Source
start_link/2

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.

Source
update/7

Specs:

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.

Source
update_all/4

Specs:

  • update_all(repo, query :: Ecto.Query.t, params :: list, options) :: {integer, nil} | no_return

Updates all entities matching the given query with the values given.

The query shall only have where and join expressions and a single from expression. It returns a tuple containing the number of entries and any returned result as second element

Source