MongoDB guarantees atomicity at the single-document level automatically, but many real-world operations span multiple documents or even multiple collections. Multi-document transactions extend ACID guarantees across these boundaries, while concurrency controls determine how simultaneous operations interact safely. This tutorial covers both — from basic session usage to retryable writes and performance tuning.

📖 1. Introduction

Consider transferring money between two bank accounts: the debit and credit must either both succeed or both fail. Without transactions, a crash between the two writes could leave the data in an inconsistent state. This is exactly the problem multi-document transactions solve.

❓ 2. What are Transactions?

A transaction groups multiple operations so they execute with ACID guarantees: Atomicity, Consistency, Isolation, and Durability. Either every operation in the transaction succeeds, or none of them take effect.

⚛️ 3. Single Document Atomicity

Every write to a single document — even one that modifies nested arrays or sub-documents — is already atomic in MongoDB, without needing an explicit transaction.

// Atomic without a transaction: both fields update together, or neither does
await collection.updateOne(
  { _id: accountId },
  { $inc: { balance: -100 }, $push: { history: { type: "debit", amount: 100 } } }
);

🔀 4. Multi-Document Transactions

When an operation must atomically span multiple documents or collections, wrap it in an explicit transaction using a session.

const session = client.startSession();

try {
  session.startTransaction();

  await accounts.updateOne(
    { _id: fromId },
    { $inc: { balance: -100 } },
    { session }
  );
  await accounts.updateOne(
    { _id: toId },
    { $inc: { balance: 100 } },
    { session }
  );

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

▶️ 5. Starting Transactions

A transaction begins with startTransaction() on a session object, optionally configured with specific read and write concerns.

session.startTransaction({
  readConcern: { level: "snapshot" },
  writeConcern: { w: "majority" }
});

✅ 6. Committing Transactions

commitTransaction() makes all changes within the transaction permanent and visible to other operations, atomically.

await session.commitTransaction();

⏹️ 7. Aborting Transactions

abortTransaction() discards all operations performed within the transaction, leaving the database exactly as it was before the transaction started.

try {
  // transaction operations
} catch (error) {
  await session.abortTransaction();
}

🗂️ 8. Session Management

Every transaction runs within a client session, which must be passed explicitly to every operation that's part of the transaction.

const session = client.startSession();
// ...use session in every operation...
await session.endSession(); // always release the session

👁️ 9. Read Concerns

Read concern controls the consistency and isolation guarantees of data read within a transaction. The "snapshot" level is most common for transactions, ensuring reads see a consistent point-in-time view.

✍️ 10. Write Concerns

Write concern controls how many replica set members must acknowledge a write before it's considered successful.

// Require acknowledgment from a majority of replica set members
{ writeConcern: { w: "majority" } }

📖 11. Read Preference

Read preference determines which replica set member (primary or secondary) serves read operations. Transactions that include writes must use the primary read preference.

{ readPreference: "primary" }

🧱 12. Isolation

MongoDB transactions provide snapshot isolation — all reads within the transaction see a consistent view of data as of the transaction's start, unaffected by concurrent writes from other operations.

🚦 13. Concurrency Control

When multiple operations attempt to modify the same document concurrently, MongoDB must decide how to resolve the conflict — either by locking or by detecting the conflict after the fact.

🔒 14. Locking

MongoDB uses fine-grained, document-level locking internally (with intent locks at higher levels), allowing high concurrency across unrelated documents while still preventing conflicting writes to the same one.

🎯 15. Optimistic Concurrency

A common application-level pattern: include a version field in the filter so an update only succeeds if the document hasn't changed since it was read.

const doc = await collection.findOne({ _id: docId });

const result = await collection.updateOne(
  { _id: docId, version: doc.version },
  { $set: { status: "shipped" }, $inc: { version: 1 } }
);

if (result.matchedCount === 0) {
  console.log("Document changed concurrently — retry needed");
}

🔁 16. Retryable Writes

Retryable writes automatically retry a write operation once if it fails due to a transient network error or replica set failover, without risk of duplicate execution.

const client = new MongoClient(uri, { retryWrites: true });

🔁 17. Retryable Reads

Similarly, retryable reads automatically retry read operations that fail due to transient network issues, improving resilience during failovers.

const client = new MongoClient(uri, { retryReads: true });

🌐 18. Distributed Transactions

On a sharded cluster, a transaction may span documents located on different shards. MongoDB coordinates this transparently using a two-phase commit protocol internally.

⚡ 19. Transaction Performance

🚨 20. Error Handling

Transaction errors may carry special labels like TransientTransactionError or UnknownTransactionCommitResult, indicating the operation is safe to retry.

async function runTransactionWithRetry(txnFn, session) {
  while (true) {
    try {
      await txnFn(session);
      break;
    } catch (error) {
      if (error.hasErrorLabel("TransientTransactionError")) {
        continue; // retry the whole transaction
      }
      throw error;
    }
  }
}

🌟 21. Best Practices

⚠️ 22. Common Mistakes

❓ 23. Frequently Asked Questions

📌 24. Summary