0Pricing
MongoDB Academy · Lesson

Starting a Session and Multi-Document Transaction

Learners will open a ClientSession, execute multiple operations inside startTransaction(), and commit or abort the transaction.

Starting a Session and Multi-Document Transaction is a free MongoDB Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Sessions Are the Foundation

MongoDB multi-document transactions require a session. A session is a server-side context that tracks your causally consistent reads and transaction state. You create a session from the MongoClient, pass it to every operation inside the transaction, and then end the session when you are done. Forgetting to pass the session object means operations run outside the transaction and are not rolled back on abort.

Creating a Session With startSession()

Call client.startSession() to obtain a ClientSession object. This does not start a transaction yet—it only establishes the server-side context. Sessions can optionally be configured for causal consistency so that reads within the session always reflect all prior writes in the same session, even on secondaries. Always end the session in a finally block to release server resources.

const { MongoClient } = require('mongodb');
const client = new MongoClient(process.env.MONGODB_URI);

async function run() {
  const session = client.startSession();
  try {
    // ... use session here
  } finally {
    await session.endSession();
    await client.close();
  }
}

Starting a Transaction

Call session.startTransaction() with optional transaction options to begin a multi-document transaction. Common options include readConcern (typically 'snapshot' for full isolation) and writeConcern (typically { w: 'majority' } for durable commits). Once started, all operations that pass this session are part of the transaction and will be rolled back if the transaction aborts.

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

Passing the Session to Operations

Every operation you want to include in the transaction must receive the session object as an option. If you forget to pass the session to an operation, it runs outside the transaction with its own independent write that will not be rolled back on abort. This is a common source of bugs in transaction code—always double-check that every insert, update, and delete inside the try block receives the session.

const db = client.db('bank');
const accounts = db.collection('accounts');

// Both operations must receive { session } to be part of the transaction
await accounts.updateOne(
  { _id: fromAccountId },
  { $inc: { balance: -transferAmount } },
  { session }  // <-- REQUIRED
);

await accounts.updateOne(
  { _id: toAccountId },
  { $inc: { balance: transferAmount } },
  { session }  // <-- REQUIRED
);

Committing With commitTransaction()

After all operations complete successfully, call session.commitTransaction() to atomically apply all changes to the database. Until commit is called, none of the transaction's writes are visible to other operations. On commit, MongoDB applies all writes and acknowledges according to the write concern. A successful commit means all operations in the transaction are durably saved.

session.startTransaction();
try {
  await accounts.updateOne({ _id: fromId }, { $inc: { balance: -100 } }, { session });
  await accounts.updateOne({ _id: toId }, { $inc: { balance: 100 } }, { session });
  await session.commitTransaction();
  console.log('Transfer committed successfully');
} catch (error) {
  await session.abortTransaction();
  throw error;
}

Aborting With abortTransaction()

If any operation in the transaction fails or if your application logic determines the transaction should not proceed, call session.abortTransaction(). This rolls back all writes made in the transaction as if none of them happened. MongoDB guarantees that no partial state will be left—other readers will never see any of the aborted transaction's writes.

session.startTransaction();
try {
  const inventory = await db.collection('inventory').findOne({ _id: itemId }, { session });
  
  if (inventory.stock < requestedQty) {
    // Business logic: not enough stock — abort
    await session.abortTransaction();
    return { success: false, reason: 'Insufficient stock' };
  }
  
  await db.collection('inventory').updateOne(
    { _id: itemId }, { $inc: { stock: -requestedQty } }, { session }
  );
  await db.collection('orders').insertOne({ itemId, qty: requestedQty, status: 'confirmed' }, { session });
  await session.commitTransaction();
  return { success: true };
} catch (error) {
  await session.abortTransaction();
  throw error;
}

The withTransaction() Helper

The Node.js driver provides a convenient session.withTransaction(fn) helper that automatically handles starting, committing, and aborting the transaction, including automatic retries for transient errors. The callback function receives the session and should contain all your transaction operations. Using withTransaction is recommended over manual start/commit/abort because it correctly handles the retry logic MongoDB requires.

const session = client.startSession();
try {
  await session.withTransaction(async () => {
    await accounts.updateOne({ _id: fromId }, { $inc: { balance: -100 } }, { session });
    await accounts.updateOne({ _id: toId }, { $inc: { balance: 100 } }, { session });
    // withTransaction auto-commits on success, auto-aborts on error, and retries transient errors
  }, {
    readConcern: { level: 'snapshot' },
    writeConcern: { w: 'majority' }
  });
} finally {
  await session.endSession();
}

Transaction Scope and Collections

A MongoDB transaction can span multiple collections and databases within the same cluster (MongoDB 4.2+ for sharded clusters). You can read from one collection, update another, and insert into a third—all within a single atomic transaction. The only restriction is that you cannot create new collections or indexes inside a multi-document transaction; those DDL operations must happen outside transactions.

await session.withTransaction(async () => {
  const db = client.db('ecommerce');
  
  // Span multiple collections in one transaction
  await db.collection('inventory').updateOne(
    { productId: 'P1' }, { $inc: { stock: -qty } }, { session }
  );
  await db.collection('orders').insertOne(
    { productId: 'P1', qty, status: 'new', createdAt: new Date() }, { session }
  );
  await db.collection('customers').updateOne(
    { _id: customerId }, { $push: { orderHistory: orderId } }, { session }
  );
});

Transactions Require Replica Sets

Multi-document transactions require a replica set or sharded cluster—they do not work on a standalone MongoDB instance. On a standalone, the transaction API exists but calling startTransaction() throws an error. This means your local development setup should use a local replica set (e.g., via mongod --replSet rs0 or via Atlas free tier) if your application code uses transactions.

// Starting a local replica set for development:
// 1. Start mongod with replica set name
// mongod --replSet rs0 --port 27017 --dbpath /data/db

// 2. In mongosh, initiate the replica set:
// rs.initiate()

// Now transactions will work on localhost

Transaction Timeout and Limits

MongoDB enforces a 60-second maximum transaction lifetime by default (configurable via transactionLifetimeLimitSeconds). Transactions that run longer are automatically aborted. Additionally, transactions are capped to 16 MB of oplog space for write operations. Long-running transactions also hold locks and can degrade performance for concurrent operations, so keep transactions short and focused.

Full Transfer Example With Validation

Putting it all together: a complete, production-ready bank transfer function using withTransaction. It validates sufficient balance inside the transaction (ensuring no other writer could have drained the account between the check and the debit) and records an audit entry atomically. This pattern demonstrates all key transaction concepts.

async function transferFunds(client, fromId, toId, amount) {
  const session = client.startSession();
  try {
    await session.withTransaction(async () => {
      const accounts = client.db('bank').collection('accounts');
      const from = await accounts.findOne({ _id: fromId }, { session });
      
      if (!from || from.balance < amount) {
        throw new Error('Insufficient funds');
      }
      
      await accounts.updateOne({ _id: fromId }, { $inc: { balance: -amount } }, { session });
      await accounts.updateOne({ _id: toId }, { $inc: { balance: amount } }, { session });
      await client.db('bank').collection('auditLog').insertOne(
        { from: fromId, to: toId, amount, date: new Date(), type: 'transfer' }, { session }
      );
    });
    return { success: true };
  } finally {
    await session.endSession();
  }
}

Quick Check

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

Lesson Recap

In this lesson you learned: transactions require a ClientSession created with client.startSession(), every operation in the transaction must receive { session } to be included, and withTransaction() is the recommended helper because it handles retry logic and cleanup automatically. Next up we explore error handling and retry logic for transient transaction failures.

Frequently asked questions

Is the “Starting a Session and Multi-Document Transaction” lesson free?

Yes — the full text of “Starting a Session and Multi-Document Transaction” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.

What will I learn in “Starting a Session and Multi-Document Transaction”?

Learners will open a ClientSession, execute multiple operations inside startTransaction(), and commit or abort the transaction. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start MongoDB Academy?

No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Starting a Session and Multi-Document Transaction” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this MongoDB Academy lesson?

Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. ACID Guarantees in a Distributed Document Store
  2. Starting a Session and Multi-Document Transaction
  3. Error Handling and Retry Logic
  4. Transaction Performance Considerations
← Back to MongoDB Academy