Transactions

Overview

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.

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. We recommend you reuse your client for multiple sessions and transactions instead of instantiating a new client each time.

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:

• Transaction APIs

• Transaction Settings

• Core API Examples

Transaction APIs

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.

Transaction Settings

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

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
};
session.startTransaction(transactionOptions);

Examples

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:

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.

{ _id: 98765, orders: [] }

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

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 };

1
async function placeOrder(client, cart, payment) {
2
  const transactionOptions = {
3
    readConcern: { level: 'snapshot' },
4
    writeConcern: { w: 'majority' },
5
    readPreference: 'primary'
6
  };
7
8
  const session = client.startSession();
9
  try {
10
    session.startTransaction(transactionOptions);
11
12
    const ordersCollection = client.db('testdb').collection('orders');
13
    const orderResult = await ordersCollection.insertOne(
14
      {
15
        customer: payment.customer,
16
        items: cart,
17
        total: payment.total,
18
      },
19
      { session }
20
    );
21
22
    const inventoryCollection = client.db('testdb').collection('inventory');
23
    for (let i=0; i<cart.length; i++) {
24
      const item = cart[i];
25
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
      }
37
38
      await inventoryCollection.updateOne(
39
        { sku: item.sku },
40
        { $inc: { 'qty': -item.qty }},
41
        { session }
42
      );
43
    }
44
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.');
53
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
  }
67
}

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

{
  "_id": 98765,
  "orders": [
    "61dc..."
  ]
}

[
  {
    "_id": ...,
    "name": "sunblock",
    "sku": 5432,
    "qty": 84
  },
  {
    "_id": ...,
    "name": "beach towel",
    "sku": 7865,
    "qty": 39
  }
]

[
  {
    "_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
  }
]