Packages
ecto
1.0.5
3.14.1
3.14.0
3.13.6
3.13.5
3.13.4
3.13.3
3.13.2
3.13.1
3.13.0
3.12.6
3.12.5
3.12.4
3.12.3
3.12.2
3.12.1
3.12.0
3.11.2
3.11.1
3.11.0
3.10.3
3.10.2
3.10.1
3.10.0
3.9.6
3.9.5
3.9.4
3.9.3
3.9.2
3.9.1
3.9.0
3.8.4
3.8.3
3.8.2
3.8.1
3.8.0
3.7.2
3.7.1
3.7.0
3.6.2
3.6.1
3.6.0
3.5.8
3.5.7
3.5.6
3.5.5
3.5.4
3.5.3
3.5.2
3.5.1
3.5.0
3.5.0-rc.1
3.5.0-rc.0
3.4.6
3.4.5
3.4.4
3.4.3
3.4.2
3.4.1
3.4.0
3.3.4
3.3.3
3.3.2
3.3.1
3.3.0
3.2.5
3.2.4
3.2.3
3.2.2
3.2.1
3.2.0
3.1.7
3.1.6
3.1.5
3.1.4
3.1.3
3.1.2
3.1.1
3.1.0
3.0.9
3.0.8
3.0.7
3.0.6
3.0.5
3.0.4
3.0.3
3.0.2
3.0.1
3.0.0
3.0.0-rc.1
3.0.0-rc.0
2.2.12
2.2.11
2.2.10
2.2.9
2.2.8
2.2.7
2.2.6
2.2.5
2.2.4
2.2.3
2.2.2
2.2.1
2.2.0
2.2.0-rc.1
2.2.0-rc.0
2.1.6
2.1.5
2.1.4
2.1.3
2.1.2
2.1.1
2.1.0
2.1.0-rc.5
2.1.0-rc.4
2.1.0-rc.3
2.1.0-rc.2
2.1.0-rc.1
2.1.0-rc.0
2.0.6
2.0.5
2.0.4
2.0.3
2.0.2
2.0.1
2.0.0
2.0.0-rc.6
2.0.0-rc.5
2.0.0-rc.4
2.0.0-rc.3
2.0.0-rc.2
2.0.0-rc.1
2.0.0-rc.0
2.0.0-beta.2
2.0.0-beta.1
2.0.0-beta.0
1.1.9
1.1.8
1.1.7
1.1.6
1.1.5
1.1.4
1.1.3
1.1.2
1.1.1
1.1.0
1.0.7
1.0.6
1.0.5
1.0.4
1.0.3
1.0.2
1.0.1
1.0.0
0.16.0
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.13.1
0.13.0
0.12.1
0.12.0
0.12.0-rc
0.11.3
0.11.2
0.11.1
0.11.0
0.10.3
0.10.2
0.10.1
0.10.0
0.9.0
0.8.1
0.8.0
0.7.2
0.7.1
0.7.0
0.6.0
0.5.1
0.5.0
0.4.0
0.3.0
0.2.8
0.2.7
0.2.6
0.2.5
0.2.4
0.2.3
0.2.2
0.2.1
0.2.0
0.1.0
A toolkit for data mapping and language integrated query for Elixir
Current section
Files
Jump to
Current section
Files
lib/ecto/adapter.ex
defmodule Ecto.Adapter do
@moduledoc """
This module specifies the adapter API that an adapter is required to
implement.
"""
use Behaviour
@type t :: module
@type query_meta :: map
@type model_meta :: %{source: {prefix :: binary, table :: binary}, model: atom, context: term}
@type fields :: Keyword.t
@type filters :: Keyword.t
@type constraints :: Keyword.t
@type returning :: [atom]
@type prepared :: term
@type preprocess :: (field :: Macro.t, value :: term, context :: term -> term)
@type autogenerate_id :: {field :: atom, type :: :id | :binary_id, value :: term} | nil
@typep repo :: Ecto.Repo.t
@typep options :: Keyword.t
@doc """
The callback invoked in case the adapter needs to inject code.
"""
defmacrocallback __before_compile__(Macro.Env.t) :: Macro.t
## Types
@doc """
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)
"""
defcallback load(Ecto.Type.t, term) :: {:ok, term} | :error
@doc """
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)
"""
defcallback dump(Ecto.Type.t, term) :: {:ok, term} | :error
@doc """
Called every time an id is needed for an embedded model.
It receives the `Ecto.Embedded` struct.
"""
defcallback embed_id(Ecto.Embedded.t) :: String.t
@doc """
Starts any connection pooling or supervision and return `{:ok, pid}`.
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`.
"""
defcallback start_link(repo, options) ::
{:ok, pid} | {:error, {:already_started, pid}} | {:error, term}
@doc """
Shuts down the repository represented by the given pid.
This callback must be called by the process that called
`start_link/2`. Therefore, it is useful for scripts.
"""
defcallback stop(pid, timeout) :: :ok
@doc """
Commands invoked to prepare a query for `all`, `update_all` and `delete_all`.
The returned result is given to `execute/6`.
"""
defcallback prepare(:all | :update_all | :delete_all, query :: Ecto.Query.t) ::
{:cache, prepared} | {:nocache, prepared}
@doc """
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.
"""
defcallback execute(repo, query_meta :: map, prepared, params :: list(), preprocess | nil, options) ::
{integer, [[term]] | nil} | no_return
@doc """
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.
"""
defcallback insert(repo, model_meta, fields, autogenerate_id, returning, options) ::
{:ok, Keyword.t} | {:invalid, constraints} | no_return
@doc """
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.
"""
defcallback update(repo, model_meta, fields, filters, autogenerate_id, returning, options) ::
{:ok, Keyword.t} | {:invalid, constraints} |
{:error, :stale} | no_return
@doc """
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.
"""
defcallback delete(repo, model_meta, filters, autogenerate_id, options) ::
{:ok, Keyword.t} | {:invalid, constraints} |
{:error, :stale} | no_return
end