MongoDB Transactions — Single & Multi-Document ACID

If an order's line items are embedded directly inside the order document — including a denormalized snapshot of each item's price and name at the time of purchase (Chapter 04 §4 covers exactly this trade-off) — then marking the whole order "PAID" and recording which items were fulfilled is a single-document update: fully atomic by MongoDB's baseline guarantee, no session.startTransaction() call anywhere in sight.

db.orders.updateOne(
  { _id: orderId, status: "PENDING" },
  {
    $set: { status: "PAID", "items.$[].fulfillmentStatus": "CONFIRMED" },
    $push: { events: { type: "PAID", at: new Date() } }
  }
);
// three effects (status, every item's fulfillmentStatus, an event log entry) —
// all one document write, all guaranteed atomic, zero transaction machinery involved

This is also MongoDB's own stated modeling guidance, not just a performance shortcut: model data so information that changes together lives in one document wherever reasonably possible, and reserve multi-document transactions for the cases that genuinely can't be modeled any other way — covered next.

db.orders.updateOne(
  { _id: orderId, status: "PENDING" },
  {
    $set: { status: "PAID", "items.$[].fulfillmentStatus": "CONFIRMED" },
    $push: { events: { type: "PAID", at: new Date() } }
  }
);
// three effects (status, every item's fulfillmentStatus, an event log entry) —
// all one document write, all guaranteed atomic, zero transaction machinery involved

Some relationships can't be collapsed into one document no matter how you shape the schema — a shared inventory collection is the clearest case: stock for SKU-100 is referenced by many different orders, so it cannot live embedded inside any single order document (Chapter 04 §3's "one-to-squillions" pattern is the same underlying shape). Decrementing shared stock and creating an order record are genuinely two different documents in two different collections that must succeed or fail together — a real case for a multi-document transaction.

// withTransaction() is the MongoDB driver's higher-level alternative to the manual
// startTransaction()/commitTransaction()/abortTransaction() pattern shown in
// Transaction Mastery, Chapter 14 §4 — it wraps the callback and AUTOMATICALLY
// retries it on transient errors the replica-set-based transaction machinery can
// genuinely produce (a stepped-down primary, a brief network blip during commit)
session.withTransaction(() -> {
    MongoCollection<Document> inventory = database.getCollection("inventory");
    MongoCollection<Document> orders = database.getCollection("orders");

    UpdateResult result = inventory.updateOne(session,
        and(eq("sku", "SKU-100"), gte("stock", qty)),
        inc("stock", -qty));

    if (result.getModifiedCount() == 0) {
        // not enough stock — withTransaction() has no idea this is a business-rule
        // failure unless you tell it, by throwing
        throw new InsufficientStockException("SKU-100");
    }

    orders.insertOne(session, new Document("sku", "SKU-100").append("qty", qty));
    return null;
}, TransactionOptions.builder()
    .readConcern(ReadConcern.SNAPSHOT)
    .writeConcern(WriteConcern.MAJORITY)
    .build());

session.withTransaction(() -> {
    MongoCollection<Document> inventory = database.getCollection("inventory");
    MongoCollection<Document> orders = database.getCollection("orders");

    UpdateResult result = inventory.updateOne(session,
        and(eq("sku", "SKU-100"), gte("stock", qty)),
        inc("stock", -qty));

    if (result.getModifiedCount() == 0) {
        throw new InsufficientStockException("SKU-100");
    }

    orders.insertOne(session, new Document("sku", "SKU-100").append("qty", qty));
    return null;
}, TransactionOptions.builder()
    .readConcern(ReadConcern.SNAPSHOT)
    .writeConcern(WriteConcern.MAJORITY)
    .build());

Transaction Mastery, Chapter 14 §6 covered read concern defaults in the context of a write-side transfer. The same "snapshot" read concern matters for a read-only multi-step operation too: generating an invoice needs to read the order document, the customer document, and a pricing-rules document together, and have all three reflect the same consistent point in time — if another transaction commits a price change between reading the order and reading the pricing rules, the invoice could mix pre-change and post-change data without any single read being individually wrong.

try (ClientSession session = mongoClient.startSession()) {
    session.startTransaction(TransactionOptions.builder()
        .readConcern(ReadConcern.SNAPSHOT)
        .build());

    Document order = orders.find(session, eq("_id", orderId)).first();
    Document customer = customers.find(session, eq("_id", order.getString("customerId"))).first();
    Document pricingRules = pricingRules.find(session, eq("region", customer.getString("region"))).first();

    session.commitTransaction(); // a read-only transaction still needs a commit call —
                                  // it releases the snapshot; there's nothing to roll back
    return buildInvoice(order, customer, pricingRules);
}

try (ClientSession session = mongoClient.startSession()) {
    session.startTransaction(TransactionOptions.builder()
        .readConcern(ReadConcern.SNAPSHOT)
        .build());

    Document order = orders.find(session, eq("_id", orderId)).first();
    Document customer = customers.find(session, eq("_id", order.getString("customerId"))).first();
    Document pricingRules = pricingRules.find(session, eq("region", customer.getString("region"))).first();

    session.commitTransaction();
    return buildInvoice(order, customer, pricingRules);
}

Multi-document transactions in MongoDB are the escape hatch for the genuinely unavoidable cross-document cases (Chapter 03 §3) — not the default working tool the way BEGIN/COMMIT is for every multi-statement operation in SQL. The habit worth building: before reaching for startTransaction(), ask whether Chapter 04's embedding-vs-referencing framework would let the operation collapse into a single-document write instead.