Analyze the Ecto.Multi transaction logic—how do you compose multiple database operations…
- User
Analyze the
Ecto.Multitransaction logic—how do you compose multiple database operations that must succeed or fail together? Assistant
The user wants to know how to use
Ecto.Multito handle database transactions in Elixir. The core concept is composing multiple operations that must all succeed or all fail (atomicity).Key aspects to cover:
- What is
Ecto.Multi? It's a data structure for composing transactions, not the execution itself. It allows you to define a workflow. - Basic Composition: How to add operations (insert, update, delete) to a Multi struct.
- Naming/Keys: The importance of naming steps and accessing results from previous steps.
- Execution: How
Repo.transaction/1takes the Multi struct and runs it. - Handling Results: The
{:ok, results}vs{:error, failed_operation, failed_value, changes_so_far}pattern. - Advanced Composition:
Ecto.Multi.run/3: Dynamic logic based on previous results.Ecto.Multi.merge/2: Combining multis conditionally.
- Side Effects: Handling things like external API calls within the transaction (though usually discouraged, it's possible with
run). - Example: A concrete scenario (e.g., user signup + profile creation + audit log).
Drafting the content:
- Introduction: Define
Ecto.Multias an abstraction overRepo.transaction. - Step 1: Initialization:
Ecto.Multi.new(). - Step 2: Adding Operations:
Multi.insert(:user, changeset).- Self-Correction: Mention that keys matter. You can't have duplicate keys.
- Step 3: Dependency (The "Compose" part): How do I use the result of step A in step B?
- This is where functions (anonymous functions) come in.
Multi.insert(:profile, fn changes -> ... end).
- This is where functions (anonymous functions) come in.
- Step 4: Execution:
Repo.transaction(multi). - Step 5: Result Handling: Pattern matching on the result.
- Success: Map of results keyed by step name.
- Failure: Which step failed and why.
- Advanced techniques:
run: For non-Ecto checks or external calls (be careful).merge: For conditional logic that decides which Multi to run next.
Refining the Example: Let's use a "Money Transfer" or "Account Signup". Signup is cleaner for showing dependencies (create user, then create settings for that user).
- Scenario: Create a User, Create a Post for that User, Log the action.
-
Multi.new()
-
Multi.insert(:user, User.changeset(%User{}, params))
-
Multi.insert(:post, fn %{user: user} -> Post.changeset(%Post{user_id: user.id}, ...) end)
-
Multi.run(:audit, fn repo, %{user: user} -> ... end)-> Maybe just keep it to Ecto stuff for simplicity first, then addrun.
Structure of the Answer:
- High-Level Concept: It's a recipe, not the cooking.
- Basic Syntax: The
.insert,.updatesyntax. - The "Magic" (Dependencies): Passing functions to access previous results.
- Handling Failures: The error tuple structure.
- Dynamic Flows:
runandmerge. - Code Example: A complete, copy-pasteable module.
Self-Correction during drafting:
- Question: Should I mention
Ecto.Multi.oneor queries? - Answer: Yes,
Multi.oneorMulti.allcan be used inside transactions to lock rows or check data, though less common than writes. Let's stick to writes for the main example to keep it focused. - Clarification: Emphasize that
Ecto.Multirolls back automatically if any step fails. That's the core requirement.
Final Polish: Make sure to highlight the difference between passing a changeset directly vs passing a function that returns a changeset. This is the most common stumbling block for beginners.
- Direct:
Multi.insert(:step, changeset)-> executes immediately (well, it's a static definition). - Function:
Multi.insert(:step, fn data -> ... end)-> allows dynamic data.
Let's write it out.
Ecto.Multiis a data structure used to compose multiple repository operations (inserts, updates, deletes, and arbitrary code) into a single atomic transaction.The core philosophy is that
Ecto.Multiis not the execution itself, but a recipe for execution. It allows you to define a chain of operations where later steps can depend on the results of earlier steps, and if any step fails, the entire batch is rolled back.Here is an analysis of how to compose these operations, the dependency mechanism, and the execution flow.
1. The Anatomy of Composition
You start with
Ecto.Multi.new/0and append operations using functions likeinsert/3,update/3, orrun/3. Every operation must have a unique key (an atom) so it can be identified in the result or by subsequent steps.A. Static vs. Dynamic Dependencies
The most critical aspect of composition is how you pass changesets or data to the Multi.
1. Static Operations (Independent) If an operation does not depend on the result of a previous step, you pass the data directly.
Ecto.Multi.new() |> Ecto.Multi.insert(:user, User.changeset(%User{}, params))2. Dependent Operations (The "Magic") If step B requires the ID of the record created in step A, you pass a function (arity 0, 1, or 2) instead of a changeset. Ecto executes this function at runtime, passing in the results of all previous successful steps.
multi = Ecto.Multi.new() |> Ecto.Multi.insert(:user, User.changeset(%User{}, params)) # The function receives the changes map: %{user: %User{id: 1, ...}} |> Ecto.Multi.insert(:profile, fn %{user: user} -> Profile.changeset(%Profile{user_id: user.id}, %{bio: "Default bio"}) end)If the
:userinsert fails, the function for:profileis never executed.2. Handling Execution Flow
You execute the composed Multi using your Repo module.
result = Repo.transaction(multi)The return value handles the binary outcome (Success/Failure) explicitly:
-
Success:
{:ok, map}The map contains the results of every step, keyed by the names you assigned (:user,:profile).{:ok, %{user: %User{}, profile: %Profile{}}} -
Failure:
{:error, failed_operation, failed_value, changes_so_far}This tuple tells you exactly where and why the transaction failed.failed_operation: The key of the step that broke (e.g.,:profile).failed_value: The changeset errors or the reason for failure.changes_so_far: Data from steps that succeeded before this failure (useful for logging, though the DB transaction is rolled back).
3. Advanced Composition Patterns
Ecto.Multi.run/3(Side Effects & External Logic)Sometimes you need to perform logic that isn't a simple database insert (e.g., checking a permission service, calling a third-party API, or complex conditional logic).
runexpects a function that returns{:ok, value}or{:error, reason}.multi |> Ecto.Multi.run(:check_credit, fn repo, %{user: user} -> case PaymentService.check_balance(user.id) do true -> {:ok, :passed} false -> {:error, :insufficient_funds} end end) |> Ecto.Multi.insert(:order, fn %{user: user} -> # This only runs if :check_credit returns {:ok, _} Order.changeset(user, params) end)Note: If
:check_creditreturns{:error, :insufficient_funds}, the transaction aborts, and:orderis never attempted.Ecto.Multi.merge/2(Dynamic Branching)If you need to add a variable number of operations based on the results of previous steps (e.g., "If the user is an admin, insert 5 permission records, otherwise insert 1"), use
merge.multi |> Ecto.Multi.merge(fn %{user: user} -> if user.role == :admin do Ecto.Multi.new() |> Ecto.Multi.insert(:admin_log, ...) else Ecto.Multi.new() end end)4. Summary of Rules
- Keys are Unique: You cannot have two steps named
:user. - Atomicity:
Repo.transactionensures that if any step fails (DB constraint, changeset invalidity, orrunreturning error), all DB changes are rolled back. - Isolation: Steps run sequentially. Step 2 cannot see Step 1's data until Step 1 is successfully staged in the transaction.
Practical Example
Here is a robust "Money Transfer" implementation combining all concepts:
def transfer_money(from_id, to_id, amount) do Ecto.Multi.new() # Step 1: Withdraw |> Ecto.Multi.run(:withdraw, fn repo, _changes -> from(acc in Account, where: acc.id == ^from_id, lock: "FOR UPDATE") |> repo.one() |> case do nil -> {:error, :account_not_found} acc -> if acc.balance < amount do {:error, :insufficient_funds} else changeset = Account.changeset(acc, %{balance: acc.balance - amount}) {:ok, repo.update!(changeset)} # Using update! inside run requires manual handling or returning tuple # Ideally just return repo.update(changeset) which is {:ok, _} | {:error, _} end end end) # Step 2: Deposit (Only runs if withdraw succeeded) |> Ecto.Multi.update(:deposit, fn %{withdraw: _} -> # Logic to fetch and update the 'to' account # ... end) # Step 3: Log Transaction |> Ecto.Multi.insert(:log, fn %{withdraw: from, deposit: to} -> TransactionLog.changeset(%{ from_id: from.id, to_id: to.id, amount: amount }) end) |> Repo.transaction() end- What is