Ecto v0.13.0 → Overview → Ecto → Model → Callbacks

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:

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"]
Source

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_delete/2 but with arguments
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_insert/2 but with arguments
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_load/2 but with arguments
after_update(function, args \\ [])

Adds a callback that is invoked after the model is updated
after_update(module, function, args)

Same as after_update/2 but with arguments
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_delete/2 but with arguments
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_insert/2 but with arguments
before_update(function, args \\ [])

Adds a callback that is invoked before the model is updated
before_update(module, function, args)

Same as before_update/2 but with arguments

Functions

__apply__(module, callback, data)
(function) # ↑

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{...}
Source

Macros

after_delete(function, args \\ [])
(macro) # ↑

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
Source
after_delete(module, function, args)
(macro) # ↑

Same as after_delete/2 but with arguments.

Source
after_insert(function, args \\ [])
(macro) # ↑

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
Source
after_insert(module, function, args)
(macro) # ↑

Same as after_insert/2 but with arguments.

Source
after_load(function, args \\ [])
(macro) # ↑

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
Source
after_load(module, function, args)
(macro) # ↑

Same as after_load/2 but with arguments.

Source
after_update(function, args \\ [])
(macro) # ↑

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
Source
after_update(module, function, args)
(macro) # ↑

Same as after_update/2 but with arguments.

Source
before_delete(function, args \\ [])
(macro) # ↑

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
Source
before_delete(module, function, args)
(macro) # ↑

Same as before_delete/2 but with arguments.

Source
before_insert(function, args \\ [])
(macro) # ↑

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
Source
before_insert(module, function, args)
(macro) # ↑

Same as before_insert/2 but with arguments.

Source
before_update(function, args \\ [])
(macro) # ↑

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
Source
before_update(module, function, args)
(macro) # ↑

Same as before_update/2 but with arguments.

Source