Ecto.Repo behaviour
Defines a repository.
A repository maps to a data store, for example an SQL database.
A repository must implement conf/0 and set an adapter (see Ecto.Adapter)
to be used for the repository.
When used, the following options are allowed:
:adapter- the adapter to be used for the repository:env- configures the repository to support environments
Example
defmodule MyRepo do
use Ecto.Repo, adapter: Ecto.Adapters.Postgres
def conf do
parse_url "ecto://postgres:postgres@localhost/postgres"
end
end
Most of the time, we want the repository to work with different
environments. In such cases, we can pass an :env option:
defmodule MyRepo do
use Ecto.Repo, adapter: Ecto.Adapters.Postgres, env: Mix.env
def conf(env), do: parse_url url(env)
defp url(:dev), do: "ecto://postgres:postgres@localhost/postgres_dev"
defp url(:test), do: "ecto://postgres:postgres@localhost/postgres_test?size=1"
defp url(:prod), do: "ecto://postgres:postgres@localhost/postgres_prod"
end
Notice that, when using the environment, developers should implement
conf/1 which automatically passes the environment instead of conf/0.
Note the environment is only used at compilation time. That said, make
sure the :build_per_environment option is set to true (the default)
in your Mix project configuration.
Types ↑
t :: module
Callbacks
Specs:
- __repo__ :: true
Simply returns true to mark this module as a repository.
Specs:
- adapter :: Ecto.Adapter.t
Returns the adapter tied to the repository.
Specs:
- all(Ecto.Query.t, Keyword.t) :: [Ecto.Model.t] | no_return
Fetches all results from the data store based on the given query. May raise
Ecto.QueryError if query validation fails. Ecto.AdapterError will be
raised if there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Example
# Fetch all post titles
query = from p in Post,
select: p.title
MyRepo.all(query)
Specs:
- conf :: Keyword.t
Should return the database options that will be given to the adapter. Often
used in conjunction with parse_url/1. This function must be implemented by
the user.
Specs:
- delete(Ecto.Model.t, Keyword.t) :: Ecto.Model.t | no_return
Deletes an model using the primary key as key. If the model has no primary
key Ecto.NoPrimaryKeyError will be raised. Ecto.AdapterError will be raised if
there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Example
[post] = MyRepo.all(from(p in Post, where: p.id == 42))
MyRepo.delete(post)
Specs:
- delete_all(Ecto.Queryable.t, Keyword.t) :: integer | no_return
Deletes all entities matching the given query with the given values.
Ecto.AdapterError will be raised if there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Examples
MyRepo.delete_all(Post)
from(p in Post, where: p.id < 10) |> MyRepo.delete_all
Specs:
- get(Ecto.Queryable.t, term, Keyword.t) :: Ecto.Model.t | nil | no_return
Fetches a single model from the data store where the primary key matches the given id.
Returns nil if no result was found. If the model in the queryable
has no primary key Ecto.NoPrimaryKeyError will be raised.
Ecto.AdapterError will be raised if there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Specs:
- get!(Ecto.Queryable.t, term, Keyword.t) :: Ecto.Model.t | nil | no_return
Similar to get/3 but raises Ecto.NotSingleResult if no record was found.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Specs:
- insert(Ecto.Model.t, Keyword.t) :: Ecto.Model.t | no_return
Stores a single new model in the data store and returns its stored
representation. May raise Ecto.AdapterError if there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Example
post = %Post{title: "Ecto is great", text: "really, it is"}
|> MyRepo.insert
Specs:
- log({:query, String.t} | :begin | :commit | :rollback, (() -> any)) :: any
Enables logging and debugging of adapter actions such as sending queries to the database. By default writes to Logger but can be overriden to customize behaviour.
You must return the result of calling the passed in function.
Examples
def log({:query, sql}, fun) do
{time, result} = :timer.tc(fun)
Logger.debug inspect{sql, time}
result
end
def log(_arg, fun), do: fun.()
Specs:
- one(Ecto.Queryable.t, Keyword.t) :: Ecto.Model.t | nil | no_return
Fetches a single result from the query.
Returns nil if no result was found.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Specs:
- one!(Ecto.Queryable.t, Keyword.t) :: Ecto.Model.t | nil | no_return
Similar to one/3 but raises Ecto.NotSingleResult if no record was found.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Specs:
- preload([Ecto.Model.t] | Ecto.Model.t, preloads :: term) :: [Ecto.Model.t] | Ecto.Model.t
Preloads all associations on the givne model or models.
preloads is a list of associations that can be nested in rose
tree structure:
node :: atom | {atom, node} | [node]
Specs:
- rollback(any) :: no_return
Rolls back the current transaction.
The transaction will return the value given as {:error, value}.
Specs:
- start_link :: {: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.
Specs:
- stop :: :ok
Stops any connection pooling or supervision started with start_link/1.
Specs:
- transaction(Keyword.t, (... -> any)) :: {:ok, any} | {:error, any}
Runs the given function inside a transaction. If an unhandled error occurs the
transaction will be rolled back. If no error occurred the transaction will be
commited when the function returns. A transaction can be explicitly rolled
back by calling rollback, this will immediately leave the function and
return the value given to rollback as {:error, value}. A successful
transaction returns the value returned by the function wrapped in a tuple as
{:ok, value}. Transactions can be nested.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Examples
MyRepo.transaction(fn ->
MyRepo.update(%{alice | balance: alice.balance - 10})
MyRepo.update(%{bob | balance: bob.balance + 10})
end)
# In the following example only the comment will be rolled back
MyRepo.transaction(fn ->
MyRepo.insert(%Post{})
MyRepo.transaction(fn ->
MyRepo.insert(%Comment{})
raise "error"
end)
end)
# Roll back a transaction explicitly
MyRepo.transaction(fn ->
p = MyRepo.insert(%Post{})
if not Editor.post_allowed?(p) do
MyRepo.rollback(:posting_not_allowed)
end
end)
Specs:
- update(Ecto.Model.t, Keyword.t) :: Ecto.Model.t | no_return
Updates an model using the primary key as key. If the model has no primary
key Ecto.NoPrimaryKeyError will be raised. Ecto.AdapterError will be raised if
there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Example
[post] = from p in Post, where: p.id == 42
post = %{post | title: "New title"}
MyRepo.update(post)
Updates all entities matching the given query with the given values.
Ecto.AdapterError will be raised if there is an adapter error.
Options
:timeout - The time in milliseconds to wait for the call to finish,
:infinity will wait indefinitely (default: 5000);
Examples
MyRepo.update_all(Post, title: "New title")
MyRepo.update_all(p in Post, visits: p.visits + 1)
from(p in Post, where: p.id < 10)
|> MyRepo.update_all(title: "New title")