W3cubDocs

/Phoenix

Ecto.Multi

Ecto.Multi is a data structure that allows grouping multiple Repo operations together.

Ecto.Multi makes it possible to pack operations that should be performed together (in a single database transaction) and gives a way to introspect the queued operations without actually performing them. Each operation is given a name that is unique and will identify its result or will help to identify the place of failure in case it occurs.

All operations will be executed in the order they were added.

The Ecto.Multi structure should be considered opaque. You can use %Ecto.Multi{} to pattern match the type, but accessing fields or directly modifying them is not advised. Ecto.Multi.to_list/1 returns a canonical representation of the structure that can be used for introspection.

Changesets

If Multi contains operations that accept changesets (like insert/4, update/4 or delete/4 they will be checked before starting the transaction. If any changeset has errors, the transaction won’t even be started and the error will be immediately returned.

Run

Multi allows you to run arbitrary functions as part of your transaction via the run/3 and run/5. Those functions will receive changes so far as the first argument and have to return {:ok, value} or {:error, value} as their result. Returning an error will abort any further operations and make the whole multi fail.

Example

Let’s look at an example definition and usage. The use case we’ll be looking into is resetting a password. We need to update the account with proper information, log the request and remove all current sessions. We define a function creating the Multi structure probably in some sort of service layer:

defmodule Service do
  alias Ecto.Multi
  import Ecto

  def password_reset(account, params) do
    Multi.new
    |> Multi.update(:account, Account.password_reset_changeset(account, params))
    |> Multi.insert(:log, Log.password_reset_changeset(account, params))
    |> Multi.delete_all(:sessions, assoc(account, :sessions))
  end
end

We can later execute it in the integration layer using Repo:

Repo.transaction(Service.password_reset(account, params))

By pattern matching on the result we can differentiate different conditions:

case result do
  {:ok, %{account: account, log: log, sessions: sessions}} ->
    # Operation was successful, we can access results (exactly the same
    # we would get from running corresponding Repo functions)
    # under keys we used for naming the operations.
  {:error, failed_operation, failed_value, changes_so_far} ->
    # One of the operations failed. We can access the operation's failure
    # value (like changeset for operations on changesets) to prepare a
    # proper response. We also get access to the results of any operations
    # that succeeded before the indicated operation failed. However, any
    # successful operations would have been rolled back.
end

We can also easily unit test our transaction without actually running it. Since changesets can use in-memory-data, we can use an account that is constructed in memory as well (without persisting it to the database):

test "dry run password_reset" do
  account = %Account{password: "letmein"}
  multi = Service.password_reset(account, params)

  assert [
    {:account, {:update, account_changeset, []}},
    {:log, {:insert, log_changeset, []}},
    {:sessions, {:delete_all, query, []}}
  ] = Ecto.Multi.to_list(multi)

  # We can introspect changesets and query to see if everything
  # is as expected, for example:
  assert account_changeset.valid?
  assert log_changeset.valid?
  assert inspect(query) == "#Ecto.Query<from a in Session>"
end

Summary

Types

merge()
name()
run()
t()

Functions

append(lhs, rhs)

Appends the second multi to the first one

delete(multi, name, changeset_or_struct, opts \\ [])

Adds a delete operation to the multi

delete_all(multi, name, queryable, opts \\ [])

Adds a delete_all operation to the multi

insert(multi, name, changeset_or_struct, opts \\ [])

Adds an insert operation to the multi

insert_all(multi, name, schema_or_source, entries, opts \\ [])

Adds an insert_all operation to the multi

merge(multi, merge)

Merges a dynamically created multi

merge(multi, mod, fun, args)

Merges a dynamically created multi

new()

Returns an empty Ecto.Multi struct

prepend(lhs, rhs)

Prepends the second multi to the first one

run(multi, name, run)

Adds a function to run as part of the multi

run(multi, name, mod, fun, args)

Adds a function to run as part of the multi

to_list(multi)

Transforms the Ecto.Multi into a list of operations to be performed. Inspecting the Ecto.Multi struct internals directly is discouraged

update(multi, name, changeset, opts \\ [])

Adds an update operation to the multi

update_all(multi, name, queryable, updates, opts \\ [])

Adds an update_all operation to the multi

Types

merge :: (map -> t) | {module, atom, [any]}
name :: any
run ::
  (t -> {:ok | :error, any}) |
  {module, atom, [any]}
t

Functions

append(lhs, rhs)

Specs

append(t, t) :: t

Appends the second multi to the first one.

All names must be unique between both structures.

Example

iex> lhs = Ecto.Multi.new |> Ecto.Multi.run(:left, &{:ok, &1})
iex> rhs = Ecto.Multi.new |> Ecto.Multi.run(:right, &{:error, &1})
iex> Ecto.Multi.append(lhs, rhs) |> Ecto.Multi.to_list |> Keyword.keys
[:left, :right]

delete(multi, name, changeset_or_struct, opts \\ [])

Specs

delete(t, name, Ecto.Changeset.t | Ecto.Schema.t, Keyword.t) :: t

Adds a delete operation to the multi.

Accepts the same arguments and options as Ecto.Repo.delete/3 does.

delete_all(multi, name, queryable, opts \\ [])

Specs

delete_all(t, name, Ecto.Queryable.t, Keyword.t) :: t

Adds a delete_all operation to the multi.

Accepts the same arguments and options as Ecto.Repo.delete_all/4 does.

insert(multi, name, changeset_or_struct, opts \\ [])

Specs

insert(t, name, Ecto.Changeset.t | Ecto.Schema.t, Keyword.t) :: t

Adds an insert operation to the multi.

Accepts the same arguments and options as Ecto.Repo.insert/3 does.

insert_all(multi, name, schema_or_source, entries, opts \\ [])

Specs

insert_all(t, name, schema_or_source, [entry], Keyword.t) :: t when schema_or_source: binary | {binary | nil, binary} | Ecto.Schema.t, entry: map | Keyword.t

Adds an insert_all operation to the multi.

Accepts the same arguments and options as Ecto.Repo.insert_all/4 does.

merge(multi, merge)

Specs

merge(t, merge) :: t

Merges a dynamically created multi

The function should return an Ecto.Multi, and receives changes so far as an argument.

Duplicated operations are not allowed.

merge(multi, mod, fun, args)

Specs

merge(t, module, function, args) :: t when function: atom, args: [any]

Merges a dynamically created multi

Similar to merge/2, but allows to pass module name, function and arguments. The function should return an Ecto.Multi, and receives changes so far as the first argument (prepened to those passed in the call to the function).

Duplicated operations are not allowed.

new()

Specs

new :: t

Returns an empty Ecto.Multi struct.

Example

iex> Ecto.Multi.new |> Ecto.Multi.to_list
[]

prepend(lhs, rhs)

Specs

prepend(t, t) :: t

Prepends the second multi to the first one.

All names must be unique between both structures.

Example

iex> lhs = Ecto.Multi.new |> Ecto.Multi.run(:left, &{:ok, &1})
iex> rhs = Ecto.Multi.new |> Ecto.Multi.run(:right, &{:error, &1})
iex> Ecto.Multi.prepend(lhs, rhs) |> Ecto.Multi.to_list |> Keyword.keys
[:right, :left]

run(multi, name, run)

Specs

run(t, name, run) :: t

Adds a function to run as part of the multi

The function should return either {:ok, value} or {:error, value}, and receives changes so far as an argument.

run(multi, name, mod, fun, args)

Specs

run(t, name, module, function, args) :: t when function: atom, args: [any]

Adds a function to run as part of the multi

Similar to run/3, but allows to pass module name, function and arguments. The function should return either {:ok, value} or {:error, value}, and will receive changes so far as the first argument (prepened to those passed in the call to the function).

to_list(multi)

Transforms the Ecto.Multi into a list of operations to be performed. Inspecting the Ecto.Multi struct internals directly is discouraged.

update(multi, name, changeset, opts \\ [])

Specs

update(t, name, Ecto.Changeset.t, Keyword.t) :: t

Adds an update operation to the multi.

Accepts the same arguments and options as Ecto.Repo.update/2 does.

update_all(multi, name, queryable, updates, opts \\ [])

Specs

update_all(t, name, Ecto.Queryable.t, Keyword.t, Keyword.t) :: t

Adds an update_all operation to the multi.

Accepts the same arguments and options as Ecto.Repo.update_all/4 does.

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/ecto/Ecto.Multi.html