Ecto.Model.Callbacks
Define module-level callbacks in models.
Lifecycle callbacks
Ecto provides lifecycle callbacks around insert, update and delete commands.
A callback is invoked by your Ecto.Repo before (or after)
particular events. Lifecycle callbacks always receive a
changeset as argument and must always a modified changeset.
Such callbacks are useful for data consistency, like keeping counters, setting field values and so on. For this reason, callbacks cannot abort, always run inside the tranasction and are invoked only after the data is validated.
Therefore, don't use callbacks for validation, enforcing business rules or performing actions unrelated to the data itself, like sending e-mails.
Finally keep in mind callbacks are not invoked on bulk actions
such as Ecto.Repo.update_all/3 or Ecto.Repo.delete_all/2.
Other callbacks
Besides life-cycle callbacks, Ecto also supports an after_load
callback that is invoked everytime a model is loaded with the
model itself. See after_load/2 for more information.
Example
defmodule User do
use Ecto.Model.Callbacks
after_insert Stats, :increase_user_count
def increase_user_count(changeset)
# ...
end
end
When creating the user, the after_insert callbacks will be
invoked with a changeset as argument. Multiple callbacks
can be defined, they will be invoked in order of declaration.
A callback can be defined in the following formats:
# Invoke the local function increase_user_count
after_insert :increase_user_count
# Invoke the local function increase_user_count
# with the given arguments (changeset is prepended)
after_insert :increase_user_count, ["foo", "bar"]
# Invoke the remote function increase_user_count
after_insert Stats, :increase_user_count
# Invoke the remote function increase_user_count
# with the given arguments (changeset is prepended)
after_insert Stats, :increase_user_count, ["foo", "bar"]
Summary↑
| __apply__(module, callback, data) | Applies stored callbacks in model to given data |
| after_delete(function, args \\ []) | Adds a callback that is invoked before the model is deleted from the repository |
| after_delete(module, function, args) | Same as |
| after_insert(function, args \\ []) | Adds a callback that is invoked after the model is inserted into the repository |
| after_insert(module, function, args) | Same as |
| after_load(function, args \\ []) | Adds a callback that is invoked after the model is loaded from the repository |
| after_load(module, function, args) | Same as |
| after_update(function, args \\ []) | Adds a callback that is invoked after the model is updated |
| after_update(module, function, args) | Same as |
| before_delete(function, args \\ []) | Adds a callback that is invoked before the model is deleted from the repository |
| before_delete(module, function, args) | Same as |
| before_insert(function, args \\ []) | Adds a callback that is invoked before the model is inserted into the repository |
| before_insert(module, function, args) | Same as |
| before_update(function, args \\ []) | Adds a callback that is invoked before the model is updated |
| before_update(module, function, args) | Same as |
Functions
Applies stored callbacks in model to given data.
Checks wether the callback is defined on the model, returns the data unchanged if it isn't.
This function expects a changeset for all callbacks except after_load as input.
Examples
iex> changeset = Ecto.Changeset.cast(params, %User{}, ~w(name), ~w())
iex> Ecto.Model.Callbacks.__apply__ User, :before_delete, changeset
%Ecto.Changeset{...}
Macros
Adds a callback that is invoked before the model is deleted from the repository.
The callback receives an Ecto.Changeset with the model
stored in it.
The callback must return a changeset and always run inside a transaction.
Example
after_delete User, :notify_garbage_collectors
Same as after_delete/2 but with arguments.
Adds a callback that is invoked after the model is inserted into the repository.
The callback receives an Ecto.Changeset with both repository
values and changeset changes already applied to the model.
The callback must return a changeset and always run inside a transaction.
Example
after_insert Stats, :increase_user_count
Same as after_insert/2 but with arguments.
Adds a callback that is invoked after the model is loaded from the repository.
The callback receives the model being loaded and must return a model.
The callback can be useful, for example, to resolve the value of virtual fields. Since this will be invoked every time the model is loaded, the callback must execute very quickly to avoid drastic perfomance hits.
Example
after_load Post, :set_permalink
Same as after_load/2 but with arguments.
Adds a callback that is invoked after the model is updated.
The callback receives an Ecto.Changeset with both repository
values and changeset changes already applied to the model.
The callback must return a changeset and always run inside a transaction.
Example
after_update User, :notify_account_change
Same as after_update/2 but with arguments.
Adds a callback that is invoked before the model is deleted from the repository.
The callback receives an Ecto.Changeset. At this point, the
changeset was already validated and is always valid.
The callback must return a changeset and always run inside a transaction.
Example
before_delete User, :copy_to_archive
Same as before_delete/2 but with arguments.
Adds a callback that is invoked before the model is inserted into the repository.
Since on insert all the model fields plus changeset changes
are sent to the repository, the callback will receive an
Ecto.Changeset with all the model fields and changes in
the changeset.changes field. At this point, the changeset
was already validated and is always valid.
The callback must return a changeset and always run inside a transaction.
Example
before_insert User, :generate_permalink
Same as before_insert/2 but with arguments.
Adds a callback that is invoked before the model is updated.
The callback receives an Ecto.Changeset with the changes
to be sent to the database in the changeset.changes field.
At this point, the changeset was already validated and is
always valid.
The callback must return a changeset and always run inside a transaction.
Example
before_update User, :set_update_at_timestamp
Same as before_update/2 but with arguments.