Docs Menu

Docs HomeNode.js


On this page

  • Overview
  • Transaction APIs
  • Core API
  • Transaction Settings
  • Examples
  • Sample Data
  • Core API Implementation
  • Payment Transaction Result

Read this guide to learn how to perform transactions in MongoDB using the Node.js driver. A transaction is a unit of work, composed of a series of operations that you want either to succeed together, or fail together when one or more of the operations fail. This behavior is called atomicity. Atomicity is a property in which transactions composed of one or more operations occur all at once, such that no other client can observe them as separate operations, and that it leaves no changes if one of the operations fails.

Since all write operations on a single document in MongoDB are atomic, you may benefit most from transactions when you must make an atomic change that modifies multiple documents, which is called a multi-document transaction. Similar to write operations on a single document, multi-document transactions are ACID compliant, which means MongoDB guarantees the data involved in your transaction operations remains consistent, even if it encounters unexpected errors. Learn more from this MongoDB article on ACID transactions.

You can use the driver to perform multi-document transactions.


To run multi-document transactions, you must use MongoDB version 4.0 or later.

For a detailed list of limitations, see the Transactions and Operations section in the server manual.

In MongoDB, multi-document transactions run within a client session. A client session is a grouping of related read or write operations that you want to ensure run sequentially. When combined with majority read and write concerns, the driver can guarantee causal consistency between the operations. See the server manual guide on Client Sessions and Causal Consistency Guarantees for more information.

Learn more about how to use the driver to run multi-document transactions on MongoDB in the following sections of this guide:

Use the Core API to implement a transaction with the driver. To use the Core API, you declare the start and commit points of the transaction.

The Core API features methods to start, cancel, or commit a transaction. When you commit the transaction, you send a request to the server to make the changes from your operations atomically. When using this API, you must handle certain transaction errors returned by the server manually.

See TransientTransactionError and UnknownTransactionCommitResult for more information on these errors.

To start, cancel, or commit your transaction, you can call the corresponding method on the Session object:

  • startTransaction()

  • commitTransaction()

  • abortTransaction()

See the Core API example for a sample transaction implementation.

When you instantiate a transaction, you can specify the following options to set the default behavior for that transaction:


Specifies how to check for the consistency of the data that the read operations retrieve from replica sets.

See Read Concern in the server manual for more information.

Specifies conditions in which to acknowledge the write. See Write Concern in the server manual for more information.
See Read Preference in the server manual for more information.
Specifies the maximum amount of time to allow a commit action on a transaction to run in milliseconds.

If you do not provide values, the driver uses the client settings.

You can specify the transaction options in the Core API using code that resembles the following:

const transactionOptions = {
readPreference: 'primary',
readConcern: { level: 'local' },
writeConcern: { w: 'majority' },
maxCommitTimeMS: 1000

Consider a scenario in which a customer purchases items from your online store. To record the purchase, your application needs to update information related to inventory, the customer's orders, and register the order details. Suppose you organize the data updates as follows:

Description of the Change
Record the purchase information
Append the order id to associate it with the customer
Subtract quantity of ordered items

A purchase can fail several ways such as if there's insufficient quantity of the item in inventory, if the order couldn't be completed, or if your payment system is offline.

If the payment fails, you can use a transaction to make sure that you avoid exposing any partial updates that might cause data consistency issues for other operations that depend on that data.

The code examples require the following sample data in the testdb database to run the multi-document payment transaction:

  • A document in the customers collection that describes a customer and their orders.

  • Documents in the inventory collection that each track quantity and description of an item.

The document in the customers collection in this example contains the following:

{ _id: 98765, orders: [] }

The documents in the inventory collection in this example contain the following:

{ name: "sunblock", sku: 5432, qty: 85 },
{ name: "beach towel", sku: 7865, qty: 41 }

The code examples also perform operations on the orders collection, but do not require any prior sample documents.

The code examples use the cart and payment variables to represent a sample list of items purchased and the order payment details as follows:

const cart = [
{ name: 'sunblock', sku: 5432, qty: 1, price: 5.19 },
{ name: 'beach towel', sku: 7865, qty: 2, price: 15.99 }
const payment = { customer: 98765, total: 37.17 };


The examples in the following sections require that you create the collections outside of the transaction or that you are using MongoDB 4.4 or later. For more information on creating collections inside a transaction, see the Create Collections and Indexes in a Transaction server guide.

The code example in this section demonstrates how you can use the Core API to run the multi-document payment transaction in a session. This function shows how you can perform the following:

  1. Start a session

  2. Start a transaction, specifying transaction options

  3. Perform data operations in the same session

  4. Commit a transaction, or cancel it if the driver encounters an error

  5. End a session

1async function placeOrder(client, cart, payment) {
2 const transactionOptions = {
3 readConcern: { level: 'snapshot' },
4 writeConcern: { w: 'majority' },
5 readPreference: 'primary'
6 };
8 const session = client.startSession();
9 try {
10 session.startTransaction(transactionOptions);
12 const ordersCollection = client.db('testdb').collection('orders');
13 const orderResult = await ordersCollection.insertOne(
14 {
15 customer: payment.customer,
16 items: cart,
17 total:,
18 },
19 { session }
20 );
22 const inventoryCollection = client.db('testdb').collection('inventory');
23 for (let i=0; i<cart.length; i++) {
24 const item = cart[i];
26 // Cancel the transaction when you have insufficient inventory
27 const checkInventory = await inventoryCollection.findOne(
28 {
29 sku: item.sku,
30 qty: { $gte: item.qty }
31 },
32 { session }
33 )
34 if (checkInventory === null) {
35 throw new Error('Insufficient quantity or SKU not found.');
36 }
38 await inventoryCollection.updateOne(
39 { sku: item.sku },
40 { $inc: { 'qty': -item.qty }},
41 { session }
42 );
43 }
45 const customerCollection = client.db('testdb').collection('customers');
46 await customerCollection.updateOne(
47 { _id: payment.customer },
48 { $push: { orders: orderResult.insertedId }},
49 { session }
50 );
51 await session.commitTransaction();
52 console.log('Transaction successfully committed.');
54 } catch (error) {
55 if (error instanceof MongoError && error.hasErrorLabel('UnknownTransactionCommitResult')) {
56 // add your logic to retry or handle the error
57 }
58 else if (error instanceof MongoError && error.hasErrorLabel('TransientTransactionError')) {
59 // add your logic to retry or handle the error
60 } else {
61 console.log('An error occured in the transaction, performing a data rollback:' + error);
62 }
63 await session.abortTransaction();
64 } finally {
65 await session.endSession();
66 }

Note that you must pass the session object to each CRUD operation that you want to run on that session.

The code and comments in the catch block demonstrate how you can identify the server transaction errors and where you can place your logic to handle them. Make sure to include the MongoError type from the driver in your code as shown in the following sample import statement:

const { MongoError, MongoClient } = require('mongodb');

See the Payment Transaction Result section to see what your collections should contain after you run the transaction.

If your application completes the payment transaction, your database should contain all the updates, and if an exception interrupted your transaction, none of the changes should exist in your database.

The customers collection should contain the customer document with an order id appended to the orders field:

"_id": 98765,
"orders": [

The inventory collection should contain updated quantities for the items "sunblock" and "beach towel":

"_id": ...,
"name": "sunblock",
"sku": 5432,
"qty": 84
"_id": ...,
"name": "beach towel",
"sku": 7865,
"qty": 39

The orders collection should contain the order and payment information:

"_id": "...",
"customer": 98765,
"items": [
"name": "sunblock",
"sku": 5432,
"qty": 1,
"price": 5.19
"name": "beach towel",
"sku": 7865,
"qty": 2,
"price": 15.99
"total": 37.17
←  AggregationIndexes →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.