Transactions in MongoDB

This chapter follows Replica sets in MongoDB. Multi-document transactions require a replica set or sharded cluster—not a standalone mongod for production patterns.

Single-document atomicity

Updates to one document—including embedded arrays—are atomic at the document level. Many workflows never need a transaction if you model related data in one document (see Schema design).

Sessions and withTransaction

The driver manages retries for transient errors when you use withTransaction:

1
import { ClientSession, MongoClient } from 'mongodb';
2

3
export async function transferFunds(
4
  client: MongoClient,
5
  fromId: string,
6
  toId: string,
7
  amount: number,
8
) {
9
  const session = client.startSession();
10
  try {
11
    await session.withTransaction(async () => {
12
      const accounts = client.db('bank').collection('accounts');
13
      const from = await accounts.findOne({ _id: fromId }, { session });
14
      if (!from || from.balance < amount) {
15
        throw new Error('Insufficient funds');
16
      }
17
      await accounts.updateOne(
18
        { _id: fromId },
19
        { $inc: { balance: -amount } },
20
        { session },
21
      );
22
      await accounts.updateOne(
23
        { _id: toId },
24
        { $inc: { balance: amount } },
25
        { session },
26
      );
27
    });
28
  } finally {
29
    await session.endSession();
30
  }
31
}

Pass the same session to every operation inside the transaction.

Read and write concern in transactions

Use snapshot reads (readConcern: 'snapshot') inside transactions for consistent reads of committed data. Default write concern majority ensures durability across the replica set. Long-running transactions increase oplog pressure—keep them short.

Limits and when to avoid transactions

• Maximum transaction duration (60 seconds by default on server—lower in practice).
• Document size and lock contention still apply.
• Prefer idempotent updates and embedding when you can avoid coordinating two collections.

Transactions are a safety net, not a substitute for thoughtful schema design.

Next: Full-text search in MongoDB.