Skip to content

Tweak formatting and language in Multi #4645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 7, 2025
Merged

Tweak formatting and language in Multi #4645

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 78 additions & 78 deletions lib/ecto/multi.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@ defmodule Ecto.Multi do
`Ecto.Multi` is a data structure for grouping multiple Repo operations.

`Ecto.Multi` makes it possible to pack operations that should be
performed in a single database transaction and gives a way to introspect
performed in a single database transaction and provides 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 in case of
success or failure.
either success or failure.

If a multi is valid (i.e. all the changesets in it are valid),
If a Multi is valid (i.e. all the changesets in it are valid),
all operations will be executed in the order they were added.

The `Ecto.Multi` structure should be considered opaque. You can use
Expand All @@ -19,41 +19,41 @@ defmodule Ecto.Multi do
structure that can be used for introspection.

> #### When to use Ecto.Multi? {: .info}

>
> `Ecto.Multi` is particularly useful when the set of operations to perform
> is dynamic. For most use cases, however, using regular control flow within
> is dynamic. For most other use cases, using regular control flow within
> [`Repo.transact(fun)`](`c:Ecto.Repo.transact/2`) and returning
> `{:ok, result}` or `{:error, reason}` is more straightforward.

## 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.
If a 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 will not be
started and the error will immediately be returned.

Note: `insert/4`, `update/4`, `insert_or_update/4`, and `delete/4`
Note: `insert/4`, `update/4`, `insert_or_update/4` and `delete/4`
variants that accept a function do not perform these checks since
the functions are executed after the transaction has started.

## Run

Multi allows you to run arbitrary functions as part of your transaction
`Multi` allows you to run arbitrary functions as part of your transaction
via `run/3` and `run/5`. This is especially useful when an operation
depends on the value of a previous operation. For this reason, the
function given as a callback to `run/3` and `run/5` will receive the repo
as the first argument, and all changes performed by the multi so far as a
map for the second argument.
as the first argument, and all changes performed by the Multi so far as a
map as the second argument.

The function given to `run` must return `{:ok, value}` or `{:error, value}`
as its result. Returning an error will abort any further operations
and make the whole multi fail.
and make the 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:
Let's look at an example definition and usage: resetting a password. We need
to update the account with proper information, log the request and remove
all current sessions:

defmodule PasswordManager do
alias Ecto.Multi
Expand All @@ -70,24 +70,24 @@ defmodule Ecto.Multi do

Repo.transact(PasswordManager.reset(account, params))

By pattern matching on the result we can differentiate different conditions:
By pattern matching on the result we can differentiate various 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.
# The Multi was successful. We can access results , which are as
# we would get from running the 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
# value (such as a 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.
# that succeeded before the indicated operation failed. (However,
# successful operations were 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):
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"}
Expand Down Expand Up @@ -180,9 +180,9 @@ defmodule Ecto.Multi do
end

@doc """
Appends the second multi to the first one.
Appends the second Multi to the first.

All names must be unique between both structures.
All names must be unique within both structures.

## Example

Expand All @@ -198,9 +198,9 @@ defmodule Ecto.Multi do
end

@doc """
Prepends the second multi to the first one.
Prepends the second Multi to the first.

All names must be unique between both structures.
All names must be unique within both structures.

## Example

Expand Down Expand Up @@ -237,14 +237,14 @@ defmodule Ecto.Multi do
end

@doc """
Merges a multi returned dynamically by an anonymous function.
Merges a Multi returned dynamically by an anonymous function.

This function is useful when the multi to be merged requires information
from the original multi. Hence the second argument is an anonymous function
that receives the multi changes so far. The anonymous function must return
another multi.
This function is useful when the Multi to be merged requires information
from the original Multi. The second argument is an anonymous function
that receives the Multi changes so far. The anonymous function must return
another Multi.

If you would prefer to simply merge two multis together, see `append/2` or
If you would prefer to simply merge two Multis together, see `append/2` or
`prepend/2`.

Duplicated operations are not allowed.
Expand All @@ -268,10 +268,10 @@ defmodule Ecto.Multi do
end

@doc """
Merges a multi returned dynamically by calling `module` and `function` with `args`.
Merges a Multi returned dynamically by calling `module` and `function` with `args`.

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
Similar to `merge/2` but allows passing of module name, function and
arguments. The function should return an `Ecto.Multi`, and receives changes so far
as the first argument (prepended to those passed in the call to the function).

Duplicated operations are not allowed.
Expand All @@ -283,9 +283,9 @@ defmodule Ecto.Multi do
end

@doc """
Adds an insert operation to the multi.
Adds an insert operation to the Multi.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.insert/2`.

Expand Down Expand Up @@ -324,9 +324,9 @@ defmodule Ecto.Multi do
end

@doc """
Adds an update operation to the multi.
Adds an update operation to the Multi.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.update/2`.

Expand Down Expand Up @@ -358,9 +358,9 @@ defmodule Ecto.Multi do
end

@doc """
Inserts or updates a changeset depending on whether the changeset was persisted or not.
Inserts or updates a changeset depending on whether or not the changeset was persisted.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.insert_or_update/2`.

Expand Down Expand Up @@ -402,9 +402,9 @@ defmodule Ecto.Multi do
end

@doc """
Adds a delete operation to the multi.
Adds a delete operation to the Multi.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.delete/2`.

Expand Down Expand Up @@ -450,9 +450,9 @@ defmodule Ecto.Multi do
end

@doc """
Runs a query expecting one result and stores it in the multi.
Runs a query expecting one result and stores the result in the Multi.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.one/2`.

Expand Down Expand Up @@ -482,11 +482,11 @@ defmodule Ecto.Multi do
end

@doc """
Runs a query and stores all entries in the multi.
Runs a query and stores all results in the Multi.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.all/2` does.
The remaining arguments and options are the same as in `c:Ecto.Repo.all/2`.

## Example

Expand Down Expand Up @@ -515,9 +515,9 @@ defmodule Ecto.Multi do
end

@doc """
Checks if there exists an entry matching the given query and stores a boolean in the multi.
Checks if an entry matching the given query exists and stores a boolean in the Multi.

The `name` must be unique from other statements in the multi.
The `name` must be unique within the Multi.

The remaining arguments and options are the same as in `c:Ecto.Repo.exists?/2`.

Expand Down Expand Up @@ -566,10 +566,10 @@ defmodule Ecto.Multi do
end

@doc """
Causes the multi to fail with the given value.
Causes the Multi to fail with the given value.

Running the multi in a transaction will execute
no previous steps and returns the value of the first
Running the Multi in a transaction will execute
no previous steps and return the value of the first
error added.
"""
@spec error(t, name, error :: term) :: t
Expand All @@ -578,10 +578,10 @@ defmodule Ecto.Multi do
end

@doc """
Adds a function to run as part of the multi.
Adds a function to run as part of the Multi.

The function should return either `{:ok, value}` or `{:error, value}`,
and receives the repo as the first argument, and the changes so far
and receives the repo as the first argument and the changes so far
as the second argument.

## Example
Expand All @@ -598,11 +598,11 @@ defmodule Ecto.Multi do
end

@doc """
Adds a function to run as part of the multi.
Adds a function to run as part of the Multi.

Similar to `run/3`, but allows to pass module name, function and arguments.
Similar to `run/3`, but allows passing of module name, function and arguments.
The function should return either `{:ok, value}` or `{:error, value}`, and
receives the repo as the first argument, and the changes so far as the
receives the repo as the first argument and the changes so far as the
second argument (prepended to those passed in the call to the function).
"""
@spec run(t, name, module, function, args) :: t when function: atom, args: [any]
Expand All @@ -612,9 +612,9 @@ defmodule Ecto.Multi do
end

@doc """
Adds an insert_all operation to the multi.
Adds an `insert_all` operation to the Multi.

Accepts the same arguments and options as `c:Ecto.Repo.insert_all/3` does.
Accepts the same arguments and options as `c:Ecto.Repo.insert_all/3`.

## Example

Expand Down Expand Up @@ -661,9 +661,9 @@ defmodule Ecto.Multi do
end

@doc """
Adds an update_all operation to the multi.
Adds an `update_all` operation to the Multi.

Accepts the same arguments and options as `c:Ecto.Repo.update_all/3` does.
Accepts the same arguments and options as `c:Ecto.Repo.update_all/3`.

## Example

Expand Down Expand Up @@ -705,9 +705,9 @@ defmodule Ecto.Multi do
end

@doc """
Adds a delete_all operation to the multi.
Adds a `delete_all` operation to the Multi.

Accepts the same arguments and options as `c:Ecto.Repo.delete_all/2` does.
Accepts the same arguments and options as `c:Ecto.Repo.delete_all/2`.

## Example

Expand Down Expand Up @@ -754,7 +754,7 @@ defmodule Ecto.Multi do
end

@doc """
Returns the list of operations stored in `multi`.
Returns the list of operations stored in the Multi.

Always use this function when you need to access the operations you
have defined in `Ecto.Multi`. Inspecting the `Ecto.Multi` struct internals
Expand All @@ -776,26 +776,26 @@ defmodule Ecto.Multi do
@doc """
Adds a value to the changes so far under the given name.

The given `value` is added to the multi before the transaction starts.
The given `value` is added to the Multi before the transaction starts.
If you would like to run arbitrary functions as part of your transaction,
see `run/3` or `run/5`.

## Example

Imagine there is an existing company schema that you retrieved from
the database. You can insert it as a change in the multi using `put/3`:
the database. You can insert it as a change in the Multi using `put/3`:

Ecto.Multi.new()
|> Ecto.Multi.put(:company, company)
|> Ecto.Multi.insert(:user, fn changes -> User.changeset(changes.company) end)
|> Ecto.Multi.insert(:person, fn changes -> Person.changeset(changes.user, changes.company) end)
|> MyApp.Repo.transact()

In the example above there isn't a large benefit in putting the
`company` in the multi, because you could also access the
In the example above, there isn't a significant benefit in putting
the `company` in the Multi because you could also access the
`company` variable directly inside the anonymous function.

However, the benefit of `put/3` is when composing `Ecto.Multi`s.
However, the benefit of `put/3` is seen when composing `Ecto.Multi`s.
If the insert operations above were defined in another module,
you could use `put(:company, company)` to inject changes that
will be accessed by other functions down the chain, removing
Expand All @@ -807,14 +807,14 @@ defmodule Ecto.Multi do
end

@doc """
Inspects results from a Multi
Inspects results from a Multi.

By default, the name is shown as a label to the inspect, custom labels are
By default, the name is shown as a label to the inspect. Custom labels are
supported through the `IO.inspect/2` `label` option.

## Options

All options for IO.inspect/2 are supported, it also support the following ones:
All options for IO.inspect/2 are supported, as well as:

* `:only` - A field or a list of fields to inspect, will print the entire
map by default.
Expand Down Expand Up @@ -949,7 +949,7 @@ defmodule Ecto.Multi do
{Map.merge(changes, new_changes), MapSet.union(names, new_names)}

common ->
raise "cannot merge multi, the following operations were found in " <>
raise "cannot merge Multi; the following operations were found in " <>
"both Ecto.Multi: #{Kernel.inspect(common)}"
end
end
Expand Down