Atomic writes across Mongoose models with ClientSession

The problem: partial failure across multiple writes

A typical order flow writes to more than one collection: an order document, an inventory decrement, and a payment record. Mongoose model operations are independent by default. If the payment write fails after inventory has already been decremented, the database is left in an inconsistent state with no automatic rollback across models.

Mongoose ClientSession scopes multiple model writes to a single MongoDB multi-document transaction. Pass the same session object to every operation, commit on success, abort on failure, and always end the session. This is useful when several documents must succeed or fail together, but it is not available on every MongoDB deployment.

Requirements

Requirement	Why it matters
MongoDB 4.0 or later	Multi-document transactions were introduced in 4.0.
Replica set or sharded cluster	Standalone MongoDB instances do not support transactions.
Mongoose v6 or later	Assumed version for the startSession API used here.

Smallest suitable design

The following function creates an order, reserves inventory, and records a payment as one atomic unit. Every write receives { session }; without that option, the operation runs outside the transaction and will not roll back.

async function createOrder({ customerId, productId, quantity }) {
  const session = await mongoose.startSession();
  session.startTransaction();

  try {
    const [order] = await Order.create(
      [{ customer: customerId, status: 'pending' }],
      { session }
    );

    await Inventory.updateOne(
      { _id: productId, stock: { $gte: quantity } },
      { $inc: { stock: -quantity } },
      { session }
    );

    await Payment.create(
      [{ order: order._id, amount: 1000 }],
      { session }
    );

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

session.abortTransaction() is the rollback path. It only applies when the transaction has changed state and the function exits through the catch block. Schema middleware such as pre('save') runs inside the transaction when the session is passed, so hooks participate in the same unit of work.

Trust and data boundaries

• The session is the trust boundary. Any model call that omits { session } commits immediately and is invisible to the transaction.
• Application code decides which writes belong together. Transactions do not fix poor schema design; embedding related data often removes the need for cross-document atomicity.
• Do not place network calls, email sending, or external API requests inside the transaction. They cannot be undone by abortTransaction() and extend lock duration.

Operational checks

Run these in mongosh connected to the target database. You need read access to run hello() and version().

db.hello()
db.version()

Expected checks: hello().topology should return replSet or sharded, and version() should be 4.0 or higher. A standalone server returns single and cannot run multi-document transactions. The query risk is low, but avoid running diagnostic loops against a production primary during peak traffic.

Failure modes

• Transient commit errors. Commit can fail due to write conflicts or temporary replication issues. The caller should retry the whole transaction from startTransaction() rather than retrying only commitTransaction().
• Session leaks. Forgetting endSession() leaves server-side sessions open and can exhaust available session slots. The finally block above is the minimum safeguard.
• Long-running transactions. Holding a transaction open across slow writes increases lock duration, replication lag, and abort rates. Keep transactions short and small.

When this design should change

• You are developing locally on a standalone MongoDB instance. Transaction code paths will not execute; test against a replica set instead.
• Related data can be embedded in a single document. Single-document writes are already atomic in MongoDB and avoid transaction overhead.
• One of the writes is slow or depends on an external service. Move that work out of the transaction and use a compensating action if it fails.

Practical verification

Write a test that starts a session, performs two writes with { session }, forces an error before commit, and asserts that abortTransaction() rolled back both writes. Query the collections after the abort to confirm neither write persisted. Confirm every code path calls endSession() and monitor session counts under load.

Limitations

Transactions are not a replacement for schema design. They add latency and hold locks, so use them only when multiple documents truly require atomicity. This note assumes Mongoose v6 or later with the official MongoDB Node.js driver; earlier versions may have different session APIs or limited transaction support.