Week 6: Transactions & ACID Guarantees in MongoDB

1. Single-Document Atomicity

Every write to a single document in MongoDB — including one that touches several nested fields or array elements inside it — is atomic by default, with no extra syntax required. Another reader either sees the document entirely before the write or entirely after it; there's no in-between state to observe.

db.accounts.updateOne(
  { _id: ObjectId("a1") },
  {
    $inc: { balance: -50 },
    $push: { history: { type: "withdrawal", amount: 50, at: new Date() } }
  }
)

That single call decrements balance and appends a history entry as one indivisible operation — this is exactly the kind of update Week 3's embedding patterns are designed to enable, and it's the reason a well-modeled document often doesn't need a transaction at all. Where atomicity doesn't reach is across separate documents: updating one account's balance and a second account's balance as two separate calls leaves a window where only one of the two has happened.

2. When You Actually Need a Transaction

A multi-document transaction is for the case single-document atomicity can't cover: a change that must apply to two or more documents together, often in two or more different collections, where a reader must never see the change to one applied without the other.

// account 1 loses money, account 2 gains it -- both must succeed, or neither should
db.accounts.updateOne({ _id: fromId }, { $inc: { balance: -amount } });
db.accounts.updateOne({ _id: toId },   { $inc: { balance:  amount } });

Run as two independent calls, a crash between them leaves money that's left one account without ever arriving at the other. That's the specific failure mode a transaction closes: both updates commit together, or if anything fails, both roll back — the balances never end up in a partially-transferred state.

3. Sessions & the Transaction API

A transaction runs inside a client session, which groups a sequence of operations so the server can track and either commit or roll back all of them as a unit.

const session = client.startSession();

try {
  session.startTransaction();

  const accounts = client.db("bank").collection("accounts");
  await accounts.updateOne(
    { _id: fromId, balance: { $gte: amount } }, // guard against overdraft in the same call
    { $inc: { balance: -amount } },
    { session }
  );
  await accounts.updateOne(
    { _id: toId },
    { $inc: { balance: amount } },
    { session }
  );

  await session.commitTransaction();
} catch (err) {
  await session.abortTransaction();
  throw err;
} finally {
  await session.endSession();
}

Every operation that should be part of the transaction must explicitly pass { session } — an update that omits it runs entirely outside the transaction, committed immediately regardless of what happens afterward. That's the most common mistake when writing transaction code for the first time.

4. Handling Transient Errors

A transaction can fail for reasons outside your control — a replica set election mid-transaction, a brief network blip — and the driver surfaces these as errors labeled TransientTransactionError. The correct response isn't to treat it as a hard failure; it's to retry the whole transaction from the start.

async function runTransactionWithRetry(session, fn) {
  while (true) {
    try {
      session.startTransaction();
      await fn(session);
      await session.commitTransaction();
      return;
    } catch (err) {
      await session.abortTransaction();
      if (err.hasErrorLabel && err.hasErrorLabel("TransientTransactionError")) {
        continue; // safe to retry the entire transaction from scratch
      }
      throw err;
    }
  }
}

This is a MongoDB-specific detail worth internalizing: the driver's error labels (TransientTransactionError, UnknownTransactionCommitResult) exist precisely so application code can distinguish "retry me" from "this genuinely failed" without guessing from an error message.

5. Designing Transactions Away

Transactions carry real cost — extra round trips, held locks, more code to reason about — so the strongest tool in this module is often the one from Week 3: a schema that puts the data needing joint atomicity into one document in the first place.

// Two collections + a transaction to keep them in sync...
db.orders.updateOne({ _id: orderId }, { $set: { status: "shipped" } });
db.orderEvents.insertOne({ orderId, event: "shipped", at: new Date() });

// ...vs. one document, one atomic call, no transaction needed
db.orders.updateOne(
  { _id: orderId },
  {
    $set: { status: "shipped" },
    $push: { events: { event: "shipped", at: new Date() } }
  }
)

Not every case can be modeled this way — a funds transfer genuinely spans two account documents that must each remain independently queryable — but it's worth asking, before reaching for startTransaction(), whether the fields that need to change together actually belong in the same document.

6. Hands-on Exercise

7. Knowledge Check

Four quick questions. Expand each to check your answer.