Ecto

Ecto

Ecto v2.2.12 Ecto.Adapter behaviour View Source

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

Link to this section Summary

Types

cached()
constraints()
fields()
filters()
on_conflict()
prepared()
process()
query_meta()

Ecto.Query metadata fields (stored in cache)

returning()
schema_meta()

Ecto.Schema metadata fields

source()
t()

Callbacks

__before_compile__(env)

The callback invoked in case the adapter needs to inject code.

autogenerate(field_type)

Called to autogenerate a value for id/embed_id/binary_id.

child_spec(repo, options)

Returns the childspec that starts the adapter process.

delete(repo, schema_meta, filters, options)

Deletes a single struct with the given filters.

dumpers(primitive_type, ecto_type)

Returns the dumpers for a given type.

ensure_all_started(repo, type)

Ensure all applications necessary to run the adapter are started.

execute(repo, query_meta, query, params, arg5, options)

Executes a previously prepared query.

insert(repo, schema_meta, fields, on_conflict, returning, options)

Inserts a single new struct in the data store.

insert_all(repo, schema_meta, header, list, on_conflict, returning, options)

Inserts multiple entries into the data store.

loaders(primitive_type, ecto_type)

Returns the loaders for a given type.

prepare(atom, query)

Commands invoked to prepare a query for all, update_all and delete_all.

update(repo, schema_meta, fields, filters, returning, options)

Updates a single struct with the given filters.

Link to this section Types

Link to this type

cached() View Source 
cached() :: term()

Link to this type

constraints() View Source 
constraints() :: Keyword.t()

Link to this type

fields() View Source 
fields() :: Keyword.t()

Link to this type

filters() View Source 
filters() :: Keyword.t()

Link to this type

on_conflict() View Source 
on_conflict() ::
  {:raise, list(), []}
  | {:nothing, list(), [atom()]}
  | {Ecto.Query.t(), list(), [atom()]}

Link to this type

prepared() View Source 
prepared() :: term()

Link to this type

process() View Source 
process() :: (term() -> term())

Link to this type

query_meta() View Source 
query_meta() :: %{
  prefix: binary() | nil,
  sources: tuple(),
  preloads: term(),
  select: map()
}

Ecto.Query metadata fields (stored in cache)

Link to this type

returning() View Source 
returning() :: [atom()]

Link to this type

schema_meta() View Source 
schema_meta() :: %{
  source: source(),
  schema: atom(),
  context: term(),
  autogenerate_id: {atom(), :id | :binary_id}
}

Ecto.Schema metadata fields

Link to this type

source() View Source 
source() :: {prefix :: binary() | nil, table :: binary()}

Link to this type

t() View Source 
t() :: module()

Link to this section Callbacks

Link to this macrocallback

__before_compile__(env) View Source 
__before_compile__(term(), env :: Macro.Env.t()) :: Macro.t()

The callback invoked in case the adapter needs to inject code.

Link to this callback

autogenerate(field_type) View Source 
autogenerate(field_type :: :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.

Link to this callback

child_spec(repo, options) View Source 
child_spec(repo(), options()) :: :supervisor.child_spec()

Returns the childspec that starts the adapter process.

Link to this callback

delete(repo, schema_meta, filters, options) View Source 
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.

Link to this callback

dumpers(primitive_type, ecto_type) View Source 
dumpers(primitive_type :: Ecto.Type.primitive(), ecto_type :: Ecto.Type.t()) ::
  [(term() -> {:ok, term()} | :error) | Ecto.Type.t()]

Returns the dumpers 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]
Link to this callback

ensure_all_started(repo, type) View Source 
ensure_all_started(repo(), type :: :application.restart_type()) ::
  {:ok, [atom()]} | {:error, atom()}

Ensure all applications necessary to run the adapter are started.

Link to this callback

execute(repo, query_meta, query, params, arg5, options) View Source 
execute(
  repo(),
  query_meta(),
  query,
  params :: list(),
  process() | nil,
  options()
) :: result
when result: {integer(), [[term()]] | nil} | no_return(),
     query:
       {:nocache, prepared()}
       | {:cached, (prepared() -> :ok), cached()}
       | {:cache, (cached() -> :ok), prepared()}

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.

Link to this callback

insert(repo, schema_meta, fields, on_conflict, returning, options) View Source 
insert(repo(), schema_meta(), fields(), on_conflict(), 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.

Link to this callback

insert_all(repo, schema_meta, header, list, on_conflict, returning, options) View Source 
insert_all(
  repo(),
  schema_meta(),
  header :: [atom()],
  [fields()],
  on_conflict(),
  returning(),
  options()
) :: {integer(), [[term()]] | nil} | no_return()

Inserts multiple entries into the data store.

Link to this callback

loaders(primitive_type, ecto_type) View Source 
loaders(primitive_type :: Ecto.Type.primitive(), ecto_type :: 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]
Link to this callback

prepare(atom, query) View Source 
prepare(atom :: :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.

Link to this callback

update(repo, schema_meta, fields, filters, returning, options) View Source 
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.

Keyboard Shortcuts
×
c
Toggle sidebar
n
Toggle night mode
/ or s
Focus search bar
?
Bring up this help dialog