Multi-Document
Transactions

MongoDB has always had single-document atomicity — any write to a single document is atomic regardless of how many fields or embedded arrays change. Multi-document ACID transactions were added in v4.0 for replica sets and v4.2 for sharded clusters.

When Transactions Are Needed

• Bank transfer: debit account A AND credit account B — both must succeed or neither
• Create order AND decrement inventory in one atomic operation
• Update multiple collections that must stay consistent (order + cart + reservation)

When Transactions Are NOT Needed

• Updating a single document (always atomic — no transaction overhead)
• Data co-located in one document (order + embedded line items)
• Read-only operations

// Single-document write — ALWAYS atomic, no transaction needed
db.orders.updateOne(
  { _id: orderId },
  {
    $set:  { status: "confirmed" },
    $push: { lineItems: newItem },
    $inc:  { total: newItem.price }
  }
)
// All three changes guaranteed atomic — one of MongoDB's core guarantees

// Multi-document — transaction required for atomicity
// Without transaction: crash between step 1 and 2 → inconsistent state
db.accounts.updateOne({ _id: "A" }, { $inc: { balance: -100 } })  // step 1
db.accounts.updateOne({ _id: "B" }, { $inc: { balance: +100 } })  // step 2 — not atomic!

Transactions require a client session. Every operation inside the transaction must pass the same session object.

// Low-level API (Node.js driver)
const session = client.startSession()
try {
  session.startTransaction({
    readConcern:     { level: "snapshot" },
    writeConcern:    { w: "majority" },
    maxCommitTimeMS: 5000
  })

  await db.collection("accounts").updateOne(
    { _id: "A" },
    { $inc: { balance: -amount } },
    { session }           // ← session required on every operation
  )
  await db.collection("accounts").updateOne(
    { _id: "B" },
    { $inc: { balance: +amount } },
    { session }
  )

  await session.commitTransaction()
} catch (err) {
  await session.abortTransaction()
  throw err
} finally {
  await session.endSession()   // always release session
}

// ✅ Recommended: withTransaction handles retry automatically
const session = client.startSession()
try {
  await session.withTransaction(async () => {
    const accts = db.collection("accounts")

    const sender = await accts.findOne({ _id: "A" }, { session })
    if (sender.balance < amount) throw new Error("Insufficient funds")

    await accts.updateOne({ _id: "A" }, { $inc: { balance: -amount } }, { session })
    await accts.updateOne({ _id: "B" }, { $inc: { balance: +amount } }, { session })
    // Callback resolving → auto-commit
    // Callback throwing → auto-abort
    // TransientTransactionError → auto-retry entire callback
    // UnknownTransactionCommitResult → auto-retry commit only
  })
} finally {
  await session.endSession()
}

Retry Error Labels

Write Concern

Read Concern

// Manual retry loop pattern (when not using withTransaction)
async function runWithRetry(txnFn, client) {
  while (true) {
    const session = client.startSession()
    try {
      session.startTransaction()
      await txnFn(session)
      await commitWithRetry(session)
      return
    } catch (err) {
      await session.abortTransaction()
      if (err.hasErrorLabel("TransientTransactionError")) continue
      throw err
    } finally { await session.endSession() }
  }
}
async function commitWithRetry(session) {
  while (true) {
    try { await session.commitTransaction(); return }
    catch (err) {
      if (err.hasErrorLabel("UnknownTransactionCommitResult")) continue
      throw err
    }
  }
}

Transaction Overhead

• Lock contention: touched documents locked until commit/abort — concurrent writes on same document blocked
• Extra network round-trips: startTransaction → ops → commitTransaction → majority ack
• Snapshot overhead: WiredTiger maintains multiple versions of modified documents during transaction lifetime
• Large oplog entry: entire transaction written atomically to oplog at commit

Hard Limits

// ✅ Prefer atomic single-doc pattern over transactions
// Reserve inventory atomically; only create order if reservation succeeds
const reserved = await db.inventory.findOneAndUpdate(
  { sku: sku, qty: { $gte: 1 } },
  { $inc: { qty: -1 } },
  { returnDocument: "after" }
)
if (!reserved) throw new Error("Out of stock")
await db.orders.insertOne(newOrder)  // inventory already atomically decremented