MongoDB Multi-Document Transactions

Picture this: you're moving $500 between two bank accounts. The debit succeeds, but the credit fails halfway through—and now the money has vanished into a database limbo. In a relational database, you'd wrap that in a transaction. But MongoDB? For years, multi-document operations were atomic at the document level, leaving you to stitch together compensating logic. That changes with multi-document transactions: a way to handle transactions in MongoDB for multi-document updates just like you would in SQL, without sacrificing MongoDB's document flexibility.

In this lesson, you'll learn what multi-document transactions are, why they matter, and how to implement them in both the MongoDB shell and Node.js. You'll also explore the trade-offs, edge cases, and practical pitfalls so you can confidently use transactions where they're actually needed.

The problem this lesson solves

By default, MongoDB guarantees atomicity for a single document—an update to one document either fully succeeds or fully fails. But modern applications routinely need to modify multiple documents atomically: transferring funds, processing an order that touches inventory, stock, and customer records, or synchronizing a user profile across collections. Without a transaction, a partial failure leaves your data in an inconsistent state.

Before transactions were introduced (MongoDB 4.0 for replica sets, 4.2 for sharded clusters), developers had to manually roll back changes with "compensating" operations—a fragile, error-prone approach that introduced race conditions and made code logic hard to follow.

The core pain: how do you guarantee that a sequence of updates across multiple collections either all succeed or all roll back? The answer is multi-document transactions, which give you ACID guarantees across collections and even across shards.

Core concept / mental model

Think of a transaction as a locking room where you can stage all your changes before committing. While a transaction is open, no other operation sees your partial updates—they only see the committed result. If anything fails, the entire room is cleaned up, and the database returns to its pre-transaction state.

In MongoDB, a transaction is a sequence of operations (inserts, updates, deletes) that are executed with withTransaction or by manually managing the session. The key building blocks:

• Session: a logical connection context that ties all operations for a transaction together.
• Transaction options: e.g., read concern, write concern, read preference.
• Commit: makes all changes permanent.
• Abort: rolls back all changes.

MongoDB implements transactions at the storage engine level (WiredTiger), and you must be using a replica set (or a sharded cluster for distributed transactions). Standalone servers are not supported.

How it works step by step

Multi-document transactions follow a predictable flow:

1. Start a session — create a client session using startSession().
2. Begin the transaction — call session.startTransaction().
3. Run your operations — every insert, update, or delete must include the session in its options so it's part of the transaction.
4. Commit — call session.commitTransaction() if all operations succeeded.
5. Abort — call session.abortTransaction() if any operation throws an error; MongoDB automatically aborts on some failures.

The critical detail: every operation must be associated with the same session. If you forget to pass { session }, that operation runs outside the transaction and can't be rolled back.

In practice, you'll wrap the flow in a try/catch and rely on withTransaction (from the Node.js driver) which automatically handles retries and commit/abort logic.

Hands-on walkthrough

Let's implement a bank transfer to see transactions in action. We'll use the MongoDB Shell for clarity, then the Node.js driver.

Prerequisites

• MongoDB 4.0+ running as a replica set (see troubleshooting if you're on a standalone).
• For the Node.js example, install the mongodb driver: npm install mongodb.

Example 1: MongoDB Shell

// Start a session and begin a transaction
const session = db.getMongo().startSession();
session.startTransaction({
  readConcern: { level: "snapshot" },
  writeConcern: { w: "majority" }
});

try {
  // Debit sender's account (operation is tied to the session)
  db.accounts.updateOne(
    { accountId: "A-101" },
    { $inc: { balance: -500 } },
    { session }
  );

  // Credit recipient's account
  db.accounts.updateOne(
    { accountId: "A-102" },
    { $inc: { balance: 500 } },
    { session }
  );

  // Both updates succeeded → commit
  session.commitTransaction();
  print("Transfer committed");
} catch (e) {
  // Something failed → abort and roll back everything
  session.abortTransaction();
  print("Transfer aborted: " + e);
} finally {
  session.endSession();
}

Expected output (if the transfer succeeds):

Transfer committed

If the second update throws (e.g., because the recipient account doesn't exist), the output becomes:

Transfer aborted: MongoServerError: ...

Pro tip: Always end the session in a finally block to avoid memory leaks.

Example 2: Node.js with withTransaction

The Node.js driver offers a cleaner withTransaction helper that handles retries and error handling:

const { MongoClient } = require("mongodb");

async function transfer() {
  const uri = "mongodb://localhost:27017";
  const client = new MongoClient(uri);

  try {
    await client.connect();
    const db = client.db("bank");
    const accounts = db.collection("accounts");

    const session = client.startSession();

    try {
      await session.withTransaction(async () => {
        await accounts.updateOne(
          { accountId: "A-101" },
          { $inc: { balance: -500 } },
          { session }
        );
        await accounts.updateOne(
          { accountId: "A-102" },
          { $inc: { balance: 500 } },
          { session }
        );
      });
      console.log("Transfer committed");
    } finally {
      session.endSession();
    }
  } finally {
    await client.close();
  }
}

transfer().catch(console.error);

Example 3: Order processing across collections

In e-commerce, you might need to update inventory, create an order, and update the customer's purchase history atomically:

await session.withTransaction(async () => {
  // Decrement stock
  await products.updateOne(
    { sku: "SHOE-123" },
    { $inc: { stock: -1 } },
    { session }
  );

  // Insert order
  await orders.insertOne(
    { orderId: 1001, sku: "SHOE-123", qty: 1, total: 89.99 },
    { session }
  );

  // Update customer history
  await customers.updateOne(
    { customerId: "C-42" },
    { $push: { orders: 1001 } },
    { session }
  );
});

Compare options / when to choose what

When to use transactions

• Financial operations: transfers, payments, ledger updates.
• Multi-step workflows that must be all-or-nothing: order processing, booking systems.
• Data synchronization across collections: e.g., user profiles and their activity logs.

When to avoid

• High-throughput, low-latency systems where slight inconsistency is acceptable.
• Simple writes that only touch one document—use a single updateOne.
• Sharded clusters: transactions work but add coordination overhead—test carefully.

Troubleshooting & edge cases

1. Transaction numbers are only allowed on replica sets — if you get Transaction numbers are only allowed on a replica set member or mongos, your server isn't running as a replica set. Start it with --replSet rs0 and initiate the set.

2. withTransaction timeout errors — transactions have a default 60-second maxTransactionLockRequestTimeoutMillis. If you hit lock timeouts, reduce the transaction scope or increase the timeout.

3. Write conflicts — concurrent transactions may abort with a WriteConflict error. The driver's withTransaction retries; in the shell, you must manually retry or implement a retry loop.

4. Forgetting to pass the session — an operation outside the session is not part of the transaction. Double-check every call includes { session }.

5. Snapshot isolation — by default, transactions use snapshot read concern, which may fail if a document is modified by a non-transactional write mid-transaction. Set snapshot: false if you need linearizable reads.

6. Large transactions — keep them short; long-running transactions can block other writes and expire after transactionLifetimeLimitSeconds (default 60s).

Pro tip: Use withTransaction in the Node.js driver—it automatically retries on transient errors like WriteConflict and TransientTransactionError, saving you from writing boilerplate retry logic.

What you learned & what's next

You've mastered how to handle transactions in MongoDB for multi-document updates. You now understand the problem they solve, the mental model of sessions and atomic commits, the step-by-step flow, and how to implement it in both the shell and Node.js. You've also seen how to choose the right consistency approach based on your use case and how to troubleshoot common transactions failures.

In the next lesson, you'll explore optimistic concurrency control—how to manage concurrent updates without locks using versioning or timestamps. That pairs beautifully with transactions to build robust, high-concurrency systems.