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 an argument and must always return a modified changeset.
Such callbacks are useful for data consistency: keeping counters, setting field values and so on. For this reason, callbacks:
- cannot abort
- always run inside the transaction
- 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 lifecycle 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 informations.
Examples
defmodule User do
use Ecto.Model.Callbacks
after_insert :increase_user_count
def increase_user_count(changeset) do
# ...
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/1
after_insert :increase_user_count
# Invoke the local function increase_user_count/3
# with the given arguments (changeset is prepended)
after_insert :increase_user_count, ["foo", "bar"]
# Invoke the remote function Stats.increase_user_count/1
after_insert Stats, :increase_user_count
# Invoke the remote function Stats.increase_user_count/3
# 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 whether 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 runs 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 runs 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.
This callback can be useful to resolve the value of virtual fields in situations they must always be present in the model. Since this will be invoked every time the model is loaded, the callback must execute very quickly to avoid drastic perfomance hits.
Another common misuse of after_load callbacks is to use it
for loading fields which are not always required. For example,
imagine you need to generate an access token based on the User
id and password. One could use after_load and a virtual field
to precompute the access_token value but it is simpler and cleaner
to simply provide an access_token function in the model:
User.access_token(user)
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 runs 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 has already been validated and is always valid.
The callback must return a changeset and always runs 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 receives an
Ecto.Changeset with all the model fields and changes in
the changeset.changes field. At this point, the changeset
has already been validated and is always valid.
The callback must return a changeset and always runs 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 has already been validated and is
always valid.
The callback must return a changeset and always runs inside a transaction.
Example
before_update User, :set_update_at_timestamp
Same as before_update/2 but with arguments.