Session and transaction syntax in MongoDB - Deep Dive

Overview - Session and transaction syntax

What is it?

In MongoDB, sessions are a way to group operations together, and transactions allow multiple operations to be executed as a single unit. This means either all operations succeed or none do, keeping data consistent. Sessions track the context of these operations, and transactions use sessions to ensure atomicity across multiple documents or collections.

Why it matters

Without sessions and transactions, changes to data could be partially applied, causing errors or inconsistent states. For example, transferring money between accounts requires both debit and credit steps to succeed together. MongoDB sessions and transactions solve this by making sure all related operations complete fully or not at all, preventing data mistakes and improving reliability.

Where it fits

Before learning sessions and transactions, you should understand basic MongoDB operations like inserts, updates, and deletes. After mastering this topic, you can explore advanced topics like distributed transactions, retryable writes, and performance tuning for transactions.

Mental Model

Core Idea

A session groups operations, and a transaction makes those operations act like one indivisible action that either all happen or none do.

Think of it like...

Think of a session as a shopping cart and a transaction as the checkout process. You add items (operations) to the cart (session), and when you pay (commit transaction), either all items are bought or none are, so you never lose money or items.

┌─────────────┐       ┌───────────────┐
│  Session    │──────▶│  Operations   │
│ (context)   │       │ (insert, etc) │
└─────────────┘       └───────────────┘
        │                     │
        │                     ▼
        │             ┌───────────────┐
        └────────────▶│ Transaction   │
                      │ (all or none) │
                      └───────────────┘

Build-Up - 6 Steps

1

Foundation

What is a MongoDB session?

Concept: Sessions provide a context to group multiple operations together in MongoDB.

A session in MongoDB is like a container that tracks a series of operations you perform. You start a session, do some database actions, and then end the session. This helps MongoDB know which operations belong together, especially for transactions.

Result

You can start a session and perform operations that MongoDB recognizes as related.

Understanding sessions is key because they are the foundation for transactions and help MongoDB manage operation groups.

2

Foundation

Basic syntax to start a session

Concept: How to begin a session in MongoDB using the driver syntax.

In MongoDB, you start a session by calling startSession() on the client object. For example, in Node.js: const session = client.startSession(); This session object is then used to run operations or transactions.

Result

A session object is created, ready to track operations.

Knowing how to start a session is the first practical step to grouping operations and later using transactions.

3

Intermediate

Starting and committing a transaction

🤔Before reading on: do you think transactions automatically start with a session, or do you need to explicitly start them? Commit to your answer.

Concept: Transactions must be explicitly started and committed within a session to group operations atomically.

Within a session, you start a transaction by calling session.startTransaction(). Then you perform your operations passing the session as an option. Finally, you commit the transaction with session.commitTransaction(). Example in Node.js: const session = client.startSession(); session.startTransaction(); await collection.insertOne(doc, { session }); await session.commitTransaction(); session.endSession();

Result

All operations inside the transaction either succeed together or fail together.

Explicitly starting and committing transactions gives you control over atomic operation groups, preventing partial updates.

4

Intermediate

Using transactions with multiple operations

🤔Before reading on: do you think transactions can span multiple collections or databases? Commit to your answer.

Concept: Transactions can include multiple operations across collections and databases within the same session.

You can perform inserts, updates, or deletes on different collections or even databases inside one transaction. All these operations are linked by the session and transaction. If any operation fails, the entire transaction can be aborted to keep data consistent.

Result

Multiple operations across collections/databases are treated as one atomic unit.

Knowing transactions span multiple operations and collections helps you design complex, reliable workflows.

5

Advanced

Handling transaction errors and retries

🤔Before reading on: do you think transactions automatically retry on transient errors, or must you handle retries manually? Commit to your answer.

Concept: Transactions can fail due to conflicts or transient errors, and applications should handle retries explicitly.

MongoDB transactions may abort due to conflicts or network issues. Your code should catch these errors and retry the transaction if appropriate. Example pattern: while (true) { try { session.startTransaction(); // operations await session.commitTransaction(); break; } catch (error) { await session.abortTransaction(); if (error is retryable) continue; throw error; } }

Result

Transactions are retried safely, improving reliability under contention.

Understanding error handling and retries prevents data loss and ensures robust transaction use in production.

6

Expert

Transactions internals and limitations

🤔Before reading on: do you think MongoDB transactions lock the entire database or just affected documents? Commit to your answer.

Concept: MongoDB transactions use document-level locking and have limits on duration and size to balance performance and consistency.

Internally, MongoDB transactions lock only the documents they modify, not the whole database. Transactions have a maximum duration (usually 60 seconds) and size limits to avoid long-running locks. Also, transactions require replica sets or sharded clusters with specific configurations.

Result

Transactions provide atomicity with minimal locking but have practical limits to avoid performance issues.

Knowing internal locking and limits helps design efficient transactions and avoid common pitfalls in large-scale systems.

Under the Hood

MongoDB sessions track operation context using session IDs and transaction numbers. When a transaction starts, MongoDB records all changes in a temporary state. On commit, it applies all changes atomically to the database. If aborted, changes are discarded. This uses a two-phase commit protocol internally for distributed setups.

Why designed this way?

Sessions and transactions were introduced to provide atomic multi-document operations in a distributed NoSQL database. The design balances consistency and performance by using document-level locking and limiting transaction scope, avoiding heavy global locks common in relational databases.

┌───────────────┐
│ Client starts │
│ session       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ startTransaction │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Operations    │
│ (tracked)     │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ commitTransaction │
│ (apply atomically) │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Changes saved │
│ or discarded  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think MongoDB transactions lock the entire database? Commit yes or no.

Common Belief: Transactions lock the whole database to ensure atomicity.

Reality: MongoDB uses document-level locking inside transactions, not whole database locks.

Why it matters: Believing in full database locks leads to overestimating transaction impact and poor design decisions.

Quick: Do you think you can run transactions without starting a session? Commit yes or no.

Common Belief: Transactions can run without explicitly starting a session.

Reality: Transactions require an active session; you must start a session first.

Why it matters: Skipping session start causes errors and confusion when trying to use transactions.

Quick: Do you think MongoDB automatically retries failed transactions? Commit yes or no.

Common Belief: MongoDB automatically retries transactions on transient errors.

Reality: Applications must handle retries explicitly; MongoDB does not retry transactions automatically.

Why it matters: Assuming automatic retries can cause unhandled failures and data inconsistency.

Quick: Can transactions span multiple databases in MongoDB? Commit yes or no.

Common Belief: Transactions are limited to a single database.

Reality: MongoDB supports multi-database transactions within the same cluster and session.

Why it matters: Knowing this enables more flexible and powerful transaction designs.

Expert Zone

1

Transactions in sharded clusters require a config server and have additional latency due to coordination.

2

Retryable writes and transactions share session concepts but differ in scope and guarantees.

3

Long-running transactions can cause oplog bloat and impact replication performance.

When NOT to use

Avoid transactions for simple single-document operations where atomicity is guaranteed by default. Use retryable writes for idempotent operations. For very high throughput or low latency needs, consider eventual consistency patterns instead.

Production Patterns

In production, transactions are used for critical multi-document updates like financial transfers or inventory adjustments. Patterns include explicit retry loops, short transaction durations, and monitoring transaction abort rates to optimize performance.

Connections

Distributed Systems Consensus

Transactions implement atomic commit protocols similar to consensus algorithms.

Understanding consensus helps grasp how MongoDB ensures all-or-nothing commits across distributed nodes.

Banking Ledger Systems

Transactions in databases mirror ledger entries that must balance debits and credits atomically.

Knowing ledger principles clarifies why atomic transactions prevent inconsistent financial states.

Software Version Control

Sessions and transactions resemble staging and committing changes in version control systems.

This connection shows how grouping changes before finalizing them ensures consistency and rollback capability.

Common Pitfalls

#1 Trying to run a transaction without starting a session.

Wrong approach:

await collection.insertOne(doc);
await session.commitTransaction();

Correct approach:

const session = client.startSession();
session.startTransaction();
await collection.insertOne(doc, { session });
await session.commitTransaction();
session.endSession();

Root cause:

Misunderstanding that transactions require an active session context.

#2 Not passing the session object to operations inside a transaction.

Wrong approach:

session.startTransaction();
await collection.insertOne(doc);
await session.commitTransaction();

Correct approach:

session.startTransaction();
await collection.insertOne(doc, { session });
await session.commitTransaction();

Root cause:

Forgetting that operations must be linked to the session to be part of the transaction.

#3 Ignoring transaction errors and not retrying on transient failures.

Wrong approach:

try {
session.startTransaction();
// operations
await session.commitTransaction();
} catch (e) {
throw e;
}

Correct approach:

while (true) {
try {
session.startTransaction();
// operations
await session.commitTransaction();
break;
} catch (e) {
await session.abortTransaction();
if (e is retryable) continue;
throw e;
}
}

Root cause:

Not handling transient errors leads to failed transactions and inconsistent data.

Key Takeaways

MongoDB sessions provide the context needed to group operations and enable transactions.

Transactions ensure multiple operations succeed or fail together, keeping data consistent.

You must explicitly start a session and transaction, and pass the session to all operations inside the transaction.

Handling errors and retrying transactions is essential for reliable applications.

Understanding transaction internals and limits helps design efficient and robust database operations.