Navigation
This version of the documentation is archived and no longer supported.

Transactions

In MongoDB, an operation on a single document is atomic. Because you can use embedded documents and arrays to capture relationships between data in a single document structure instead of normalizing across multiple documents and collections, this single-document atomicity obviates the need for multi-document transactions for many practical use cases.

For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports multi-document transactions. With distributed transactions, transactions can be used across multiple operations, collections, databases, documents, and shards.

Transactions API

The following example highlights the key components of the transactions API:

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

    
    # For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
    # uriString = 'mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl'
    # For a sharded cluster, connect to the mongos instances; e.g.
    # uriString = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'
    
    client = MongoClient(uriString)
    wc_majority = WriteConcern("majority", wtimeout=1000)
    
    # Prereq: Create collections.
    client.get_database("mydb1", write_concern=wc_majority).foo.insert_one({"abc": 0})
    client.get_database("mydb2", write_concern=wc_majority).bar.insert_one({"xyz": 0})
    
    # Step 1: Define the callback that specifies the sequence of operations to perform inside the transactions.
    def callback(session):
        collection_one = session.client.mydb1.foo
        collection_two = session.client.mydb2.bar
    
        # Important:: You must pass the session to the operations.
        collection_one.insert_one({"abc": 1}, session=session)
        collection_two.insert_one({"xyz": 999}, session=session)
    
    # Step 2: Start a client session.
    with client.start_session() as session:
        # Step 3: Use with_transaction to start a transaction, execute the callback, and commit (or abort on error).
        session.with_transaction(
            callback,
            read_concern=ReadConcern("local"),
            write_concern=wc_majority,
            read_preference=ReadPreference.PRIMARY,
        )
    
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

    /*
      For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
      String uri = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/admin?replicaSet=myRepl";
      For a sharded cluster, connect to the mongos instances; e.g.
      String uri = "mongodb://mongos0.example.com:27017,mongos1.example.com:27017:27017/admin";
     */
    
    final MongoClient client = MongoClients.create(uri);
    
    /*
        Prereq: Create collections. CRUD operations in transactions must be on existing collections.
     */
    
    client.getDatabase("mydb1").getCollection("foo")
            .withWriteConcern(WriteConcern.MAJORITY).insertOne(new Document("abc", 0));
    client.getDatabase("mydb2").getCollection("bar")
            .withWriteConcern(WriteConcern.MAJORITY).insertOne(new Document("xyz", 0));
    
    /* Step 1: Start a client session. */
    
    final ClientSession clientSession = client.startSession();
    
    /* Step 2: Optional. Define options to use for the transaction. */
    
    TransactionOptions txnOptions = TransactionOptions.builder()
            .readPreference(ReadPreference.primary())
            .readConcern(ReadConcern.LOCAL)
            .writeConcern(WriteConcern.MAJORITY)
            .build();
    
    /* Step 3: Define the sequence of operations to perform inside the transactions. */
    
    TransactionBody txnBody = new TransactionBody<String>() {
        public String execute() {
            MongoCollection<Document> coll1 = client.getDatabase("mydb1").getCollection("foo");
            MongoCollection<Document> coll2 = client.getDatabase("mydb2").getCollection("bar");
    
            /*
               Important:: You must pass the session to the operations.
             */
            coll1.insertOne(clientSession, new Document("abc", 1));
            coll2.insertOne(clientSession, new Document("xyz", 999));
            return "Inserted into collections in different databases";
        }
    };
    try {
        /*
           Step 4: Use .withTransaction() to start a transaction,
           execute the callback, and commit (or abort on error).
        */
    
        clientSession.withTransaction(txnBody, txnOptions);
    } catch (RuntimeException e) {
        // some error handling
    } finally {
        clientSession.close();
    }
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

      // For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
      // const uri = 'mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl'
      // For a sharded cluster, connect to the mongos instances; e.g.
      // const uri = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'
    
      const client = new MongoClient(uri);
      await client.connect();
    
      // Prereq: Create collections.
    
      await client
        .db('mydb1')
        .collection('foo')
        .insertOne({ abc: 0 }, { writeConcern: { w: 'majority' } });
    
      await client
        .db('mydb2')
        .collection('bar')
        .insertOne({ xyz: 0 }, { writeConcern: { w: 'majority' } });
    
      // Step 1: Start a Client Session
      const session = client.startSession();
    
      // Step 2: Optional. Define options to use for the transaction
      const transactionOptions = {
        readPreference: 'primary',
        readConcern: { level: 'local' },
        writeConcern: { w: 'majority' }
      };
    
      // Step 3: Use withTransaction to start a transaction, execute the callback, and commit (or abort on error)
      // Note: The callback for withTransaction MUST be async and/or return a Promise.
      try {
        await session.withTransaction(async () => {
          const coll1 = client.db('mydb1').collection('foo');
          const coll2 = client.db('mydb2').collection('bar');
    
          // Important:: You must pass the session to the operations
    
          await coll1.insertOne({ abc: 1 }, { session });
          await coll2.insertOne({ xyz: 999 }, { session });
        }, transactionOptions);
      } finally {
        await session.endSession();
        await client.close();
      }
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

    /*
     * For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
     * uriString = 'mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl'
     * For a sharded cluster, connect to the mongos instances; e.g.
     * uriString = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'
     */
    
    $client = new \MongoDB\Client($uriString);
    
    // Prerequisite: Create collections.
    $client->selectCollection(
        'mydb1',
        'foo',
        [
            'writeConcern' => new \MongoDB\Driver\WriteConcern(\MongoDB\Driver\WriteConcern::MAJORITY, 1000),
        ],
    )->insertOne(['abc' => 0]);
    
    $client->selectCollection(
        'mydb2',
        'bar',
        [
            'writeConcern' => new \MongoDB\Driver\WriteConcern(\MongoDB\Driver\WriteConcern::MAJORITY, 1000),
        ],
    )->insertOne(['xyz' => 0]);
    
    // Step 1: Define the callback that specifies the sequence of operations to perform inside the transactions.
    
    $callback = function (\MongoDB\Driver\Session $session) use ($client): void {
        $client
            ->selectCollection('mydb1', 'foo')
            ->insertOne(['abc' => 1], ['session' => $session]);
    
        $client
            ->selectCollection('mydb2', 'bar')
            ->insertOne(['xyz' => 999], ['session' => $session]);
    };
    
    // Step 2: Start a client session.
    
    $session = $client->startSession();
    
    // Step 3: Use with_transaction to start a transaction, execute the callback, and commit (or abort on error).
    
    \MongoDB\with_transaction($session, $callback);
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API incorporates retry logic for "TransientTransactionError" or "UnknownTransactionCommitResult" commit errors.

    Important

    
    # For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
    # uriString = 'mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl'
    # For a sharded cluster, connect to the mongos instances; e.g.
    # uriString = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'
    
    client = AsyncIOMotorClient(uriString)
    wc_majority = WriteConcern("majority", wtimeout=1000)
    
    # Prereq: Create collections.
    await client.get_database("mydb1", write_concern=wc_majority).foo.insert_one({"abc": 0})
    await client.get_database("mydb2", write_concern=wc_majority).bar.insert_one({"xyz": 0})
    
    # Step 1: Define the callback that specifies the sequence of operations to perform inside the transactions.
    async def callback(my_session):
        collection_one = my_session.client.mydb1.foo
        collection_two = my_session.client.mydb2.bar
    
        # Important:: You must pass the session to the operations.
        await collection_one.insert_one({"abc": 1}, session=my_session)
        await collection_two.insert_one({"xyz": 999}, session=my_session)
    
    # Step 2: Start a client session.
    async with await client.start_session() as session:
        # Step 3: Use with_transaction to start a transaction, execute the callback, and commit (or abort on error).
        await session.with_transaction(
            callback,
            read_concern=ReadConcern("local"),
            write_concern=wc_majority,
            read_preference=ReadPreference.PRIMARY,
        )
    
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

    static bool
    with_transaction_example (bson_error_t *error)
    {
       mongoc_client_t *client = NULL;
       mongoc_write_concern_t *wc = NULL;
       mongoc_read_concern_t *rc = NULL;
       mongoc_read_prefs_t *rp = NULL;
       mongoc_collection_t *coll = NULL;
       bool success = false;
       bool ret = false;
       bson_t *doc = NULL;
       bson_t *insert_opts = NULL;
       mongoc_client_session_t *session = NULL;
       mongoc_transaction_opt_t *txn_opts = NULL;
    
       /* For a replica set, include the replica set name and a seedlist of the
        * members in the URI string; e.g.
        * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
        *    "27017/?replicaSet=myRepl";
        * client = mongoc_client_new (uri_repl);
        * For a sharded cluster, connect to the mongos instances; e.g.
        * uri_sharded =
        * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
        * client = mongoc_client_new (uri_sharded);
        */
    
       client = get_client ();
    
       /* Prereq: Create collections. */
       wc = mongoc_write_concern_new ();
       mongoc_write_concern_set_wmajority (wc, 1000);
       insert_opts = bson_new ();
       mongoc_write_concern_append (wc, insert_opts);
       coll = mongoc_client_get_collection (client, "mydb1", "foo");
       doc = BCON_NEW ("abc", BCON_INT32 (0));
       ret = mongoc_collection_insert_one (
          coll, doc, insert_opts, NULL /* reply */, error);
       if (!ret) {
          goto fail;
       }
       bson_destroy (doc);
       mongoc_collection_destroy (coll);
       coll = mongoc_client_get_collection (client, "mydb2", "bar");
       doc = BCON_NEW ("xyz", BCON_INT32 (0));
       ret = mongoc_collection_insert_one (
          coll, doc, insert_opts, NULL /* reply */, error);
       if (!ret) {
          goto fail;
       }
    
       /* Step 1: Start a client session. */
       session = mongoc_client_start_session (client, NULL /* opts */, error);
       if (!session) {
          goto fail;
       }
    
       /* Step 2: Optional. Define options to use for the transaction. */
       txn_opts = mongoc_transaction_opts_new ();
       rp = mongoc_read_prefs_new (MONGOC_READ_PRIMARY);
       rc = mongoc_read_concern_new ();
       mongoc_read_concern_set_level (rc, MONGOC_READ_CONCERN_LEVEL_LOCAL);
       mongoc_transaction_opts_set_read_prefs (txn_opts, rp);
       mongoc_transaction_opts_set_read_concern (txn_opts, rc);
       mongoc_transaction_opts_set_write_concern (txn_opts, wc);
    
       /* Step 3: Use mongoc_client_session_with_transaction to start a transaction,
        * execute the callback, and commit (or abort on error). */
       ret = mongoc_client_session_with_transaction (
          session, callback, txn_opts, NULL /* ctx */, NULL /* reply */, error);
       if (!ret) {
          goto fail;
       }
    
       success = true;
    fail:
       bson_destroy (doc);
       mongoc_collection_destroy (coll);
       bson_destroy (insert_opts);
       mongoc_read_concern_destroy (rc);
       mongoc_read_prefs_destroy (rp);
       mongoc_write_concern_destroy (wc);
       mongoc_transaction_opts_destroy (txn_opts);
       mongoc_client_session_destroy (session);
       mongoc_client_destroy (client);
       return success;
    }
    
    /* Define the callback that specifies the sequence of operations to perform
     * inside the transactions. */
    static bool
    callback (mongoc_client_session_t *session,
              void *ctx,
              bson_t **reply,
              bson_error_t *error)
    {
       mongoc_client_t *client = NULL;
       mongoc_collection_t *coll = NULL;
       bson_t *doc = NULL;
       bool success = false;
       bool ret = false;
    
       BSON_UNUSED (ctx);
    
       client = mongoc_client_session_get_client (session);
       coll = mongoc_client_get_collection (client, "mydb1", "foo");
       doc = BCON_NEW ("abc", BCON_INT32 (1));
       ret =
          mongoc_collection_insert_one (coll, doc, NULL /* opts */, *reply, error);
       if (!ret) {
          goto fail;
       }
       bson_destroy (doc);
       mongoc_collection_destroy (coll);
       coll = mongoc_client_get_collection (client, "mydb2", "bar");
       doc = BCON_NEW ("xyz", BCON_INT32 (999));
       ret =
          mongoc_collection_insert_one (coll, doc, NULL /* opts */, *reply, error);
       if (!ret) {
          goto fail;
       }
    
       success = true;
    fail:
       mongoc_collection_destroy (coll);
       bson_destroy (doc);
       return success;
    }
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

    // The mongocxx::instance constructor and destructor initialize and shut down the driver,
    // respectively. Therefore, a mongocxx::instance must be created before using the driver and
    // must remain alive for as long as the driver is in use.
    mongocxx::instance inst{};
    
    // For a replica set, include the replica set name and a seedlist of the members in the URI
    // string; e.g.
    // uriString =
    // 'mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl'
    // For a sharded cluster, connect to the mongos instances; e.g.
    // uriString = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'
    mongocxx::client client{mongocxx::uri{"mongodb://localhost/?replicaSet=replset"}};
    
    write_concern wc_majority{};
    wc_majority.acknowledge_level(write_concern::level::k_majority);
    
    read_concern rc_local{};
    rc_local.acknowledge_level(read_concern::level::k_local);
    
    read_preference rp_primary{};
    rp_primary.mode(read_preference::read_mode::k_primary);
    
    // Prereq: Create collections.
    
    auto foo = client["mydb1"]["foo"];
    auto bar = client["mydb2"]["bar"];
    
    try {
        options::insert opts;
        opts.write_concern(wc_majority);
    
        foo.insert_one(make_document(kvp("abc", 0)), opts);
        bar.insert_one(make_document(kvp("xyz", 0)), opts);
    } catch (const mongocxx::exception& e) {
        std::cout << "An exception occurred while inserting: " << e.what() << std::endl;
        return EXIT_FAILURE;
    }
    
    // Step 1: Define the callback that specifies the sequence of operations to perform inside the
    // transactions.
    client_session::with_transaction_cb callback = [&](client_session* session) {
        // Important::  You must pass the session to the operations.
        foo.insert_one(*session, make_document(kvp("abc", 1)));
        bar.insert_one(*session, make_document(kvp("xyz", 999)));
    };
    
    // Step 2: Start a client session
    auto session = client.start_session();
    
    // Step 3: Use with_transaction to start a transaction, execute the callback,
    // and commit (or abort on error).
    try {
        options::transaction opts;
        opts.write_concern(wc_majority);
        opts.read_concern(rc_local);
        opts.read_preference(rp_primary);
    
        session.with_transaction(callback, opts);
    } catch (const mongocxx::exception& e) {
        std::cout << "An exception occurred: " << e.what() << std::endl;
        return EXIT_FAILURE;
    }
    
    return EXIT_SUCCESS;
    

    The example uses the new callback API for working with transactions, which starts a transaction, executes the specified operations, and commits (or aborts on error). The new callback API also incorporates retry logic for TransientTransactionError or UnknownTransactionCommitResult commit errors.

    Important

    // For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
    // string uri = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl";
    // For a sharded cluster, connect to the mongos instances; e.g.
    // string uri = "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
    var client = new MongoClient(connectionString);
    
    // Prereq: Create collections.
    var database1 = client.GetDatabase("mydb1");
    var collection1 = database1.GetCollection<BsonDocument>("foo").WithWriteConcern(WriteConcern.WMajority);
    collection1.InsertOne(new BsonDocument("abc", 0));
    
    var database2 = client.GetDatabase("mydb2");
    var collection2 = database2.GetCollection<BsonDocument>("bar").WithWriteConcern(WriteConcern.WMajority);
    collection2.InsertOne(new BsonDocument("xyz", 0));
    
    // Step 1: Start a client session.
    using (var session = client.StartSession())
    {
        // Step 2: Optional. Define options to use for the transaction.
        var transactionOptions = new TransactionOptions(
            writeConcern: WriteConcern.WMajority);
    
        // Step 3: Define the sequence of operations to perform inside the transactions
        var cancellationToken = CancellationToken.None; // normally a real token would be used
        result = session.WithTransaction(
            (s, ct) =>
            {
                collection1.InsertOne(s, new BsonDocument("abc", 1), cancellationToken: ct);
                collection2.InsertOne(s, new BsonDocument("xyz", 999), cancellationToken: ct);
                return "Inserted into collections in different databases";
            },
            transactionOptions,
            cancellationToken);
    }
    

    See also

    For an example in mongo shell, see mongo Shell Example.

    Transactions and Atomicity

    Distributed Transactions and Multi-Document Transactions

    Starting in MongoDB 4.2, the two terms are synonymous. Distributed transactions refer to multi-document transactions on sharded clusters and replica sets. Multi-document transactions (whether on sharded clusters or replica sets) are also known as distributed transactions starting in MongoDB 4.2.

    For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports multi-document transactions:

    • In version 4.0, MongoDB supports multi-document transactions on replica sets.

    • In version 4.2, MongoDB introduces distributed transactions, which adds support for multi-document transactions on sharded clusters and incorporates the existing support for multi-document transactions on replica sets.

      To use transactions on MongoDB 4.2 deployments (replica sets and sharded clusters), clients must use MongoDB drivers updated for MongoDB 4.2.

    Multi-document transactions are atomic (i.e. provide an “all-or-nothing” proposition):

    • When a transaction commits, all data changes made in the transaction are saved and visible outside the transaction. That is, a transaction will not commit some of its changes while rolling back others.

      Until a transaction commits, the data changes made in the transaction are not visible outside the transaction.

      However, when a transaction writes to multiple shards, not all outside read operations need to wait for the result of the committed transaction to be visible across the shards. For example, if a transaction is committed and write 1 is visible on shard A but write 2 is not yet visible on shard B, an outside read at read concern "local" can read the results of write 1 without seeing write 2.

    • When a transaction aborts, all data changes made in the transaction are discarded without ever becoming visible. For example, if any operation in the transaction fails, the transaction aborts and all data changes made in the transaction are discarded without ever becoming visible.

    Important

    In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.

    For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.

    Transactions and Operations

    Distributed transactions can be used across multiple operations, collections, databases, documents, and, starting in MongoDB 4.2, shards.

    For transactions:

    • You can specify read/write (CRUD) operations on existing collections. The collections can be in different databases. For a list of CRUD operations, see CRUD Operations.
    • You cannot write to capped collections. (Starting in MongoDB 4.2)
    • You cannot read/write to collections in the config, admin, or local databases.
    • You cannot write to system.* collections.
    • You cannot return the supported operation’s query plan (i.e. explain).
    • For cursors created outside of a transaction, you cannot call getMore inside the transaction.
    • For cursors created in a transaction, you cannot call getMore outside the transaction.
    • Starting in MongoDB 4.2, you cannot specify killCursors as the first operation in a transaction.

    Operations that affect the database catalog, such as creating or dropping a collection or an index, are not allowed in transactions. For example, a transaction cannot include an insert operation that would result in the creation of a new collection. See Restricted Operations.

    Tip

    When creating or dropping a collection immediately before starting a transaction, if the collection is accessed within the transaction, issue the create or drop operation with write concern "majority" to ensure that the transaction can acquire the required locks.

    Count Operation

    To perform a count operation within a transaction, use the $count aggregation stage or the $group (with a $sum expression) aggregation stage.

    MongoDB drivers compatible with the 4.0 features provide a collection-level API countDocuments(filter, options) as a helper method that uses the $group with a $sum expression to perform a count. The 4.0 drivers have deprecated the count() API.

    Starting in MongoDB 4.0.3, the mongo shell provides the db.collection.countDocuments() helper method that uses the $group with a $sum expression to perform a count.

    Distinct Operation

    To perform a distinct operation within a transaction:

    • For unsharded collections, you can use the db.collection.distinct() method/the distinct command as well as the aggregation pipeline with the $group stage.

    • For sharded collections, you cannot use the db.collection.distinct() method or the distinct command.

      To find the distinct values for a sharded collection, use the aggregation pipeline with the $group stage instead. For example:

      • Instead of db.coll.distinct("x"), use

        db.coll.aggregate([
           { $group: { _id: null, distinctValues: { $addToSet: "$x" } } },
           { $project: { _id: 0 } }
        ])
        
      • Instead of db.coll.distinct("x", { status: "A" }), use:

        db.coll.aggregate([
           { $match: { status: "A" } },
           { $group: { _id: null, distinctValues: { $addToSet: "$x" } } },
           { $project: { _id: 0 } }
        ])
        

      The pipeline returns a cursor to a document:

      { "distinctValues" : [ 2, 3, 1 ] }
      

      Iterate the cursor to access the results document.

    Informational Operations

    Informational commands, such as hello, buildInfo, connectionStatus (and their helper methods) are allowed in transactions; however, they cannot be the first operation in the transaction.

    Restricted Operations

    The following operations are not allowed in transactions:

    • Operations that affect the database catalog, such as creating or dropping a collection or an index. For example, a transaction cannot include an insert operation that would result in the creation of a new collection.

      The listCollections and listIndexes commands and their helper methods are also excluded.

    • Non-CRUD and non-informational operations, such as createUser, getParameter, count, etc. and their helpers.

    Transactions and Sessions

    • Transactions are associated with a session; i.e. you start a transaction for a session.
    • At any given time, you can have at most one open transaction for a session.
    • When using the drivers, each operation in the transaction must be associated with the session. Refer to your driver specific documentation for details.
    • If a session ends and it has an open transaction, the transaction aborts.

    Read Concern/Write Concern/Read Preference

    Transactions and Read Preference

    Operations in a transaction use the transaction-level read preference.

    Using the drivers, you can set the transaction-level read preference at the transaction start:

    • If the transaction-level read preference is unset, the transaction uses the session-level read preference.
    • If transaction-level and the session-level read preference are unset, the transaction uses the client-level read preference. By default, the client-level read preference is primary.

    Multi-document transactions that contain read operations must use read preference primary. All operations in a given transaction must route to the same member.

    Transactions and Read Concern

    Operations in a transaction use the transaction-level read concern. That is, any read concern set at the collection and database level is ignored inside the transaction.

    You can set the transaction-level read concern at the transaction start.

    • If the transaction-level read concern is unset, the transaction-level read concern defaults to the session-level read concern.
    • If transaction-level and the session-level read concern are unset, the transaction-level read concern defaults to the client-level read concern. By default, client-level read concern is "local" for reads against the primary. See also:

    Transactions support the following read concern levels:

    "local"

    • Read concern "local" returns the most recent data available from the node but can be rolled back.
    • For transactions on sharded cluster, "local" read concern cannot guarantee that the data is from the same snapshot view across the shards. If snapshot isolation is required, use "snapshot" read concern.

    "majority"

    • Read concern "majority" returns data that has been acknowledged by a majority of the replica set members (i.e. data cannot be rolled back) if the transaction commits with write concern “majority”.
    • If the transaction does not use write concern “majority” for the commit, the "majority" read concern provides no guarantees that read operations read majority-committed data.
    • For transactions on sharded cluster, "majority" read concern cannot guarantee that the data is from the same snapshot view across the shards. If snapshot isolation is required, use "snapshot" read concern.

    "snapshot"

    • Read concern "snapshot" returns data from a snapshot of majority committed data if the transaction commits with write concern “majority”.
    • If the transaction does not use write concern “majority” for the commit, the "snapshot" read concern provides no guarantee that read operations used a snapshot of majority-committed data.
    • For transactions on sharded clusters, the "snapshot" view of the data is synchronized across shards.

    Transactions and Write Concern

    Transactions use the transaction-level write concern to commit the write operations. Write operations inside transactions must be issued without explicit write concern specification and use the default write concern. At commit time, the writes are then commited using the transaction-level write concern.

    Tip

    Do not explicitly set the write concern for the individual write operations inside a transaction. Setting write concerns for the individual write operations inside a transaction results in an error.

    You can set the transaction-level write concern at the transaction start:

    • If the transaction-level write concern is unset, the transaction-level write concern defaults to the session-level write concern for the commit.
    • If the transaction-level write concern and the session-level write concern are unset, transaction-level write concern defaults to the client-level write concern. By default, client-level write concern is w: 1. See also Default MongoDB Read Concerns/Write Concerns.

    Transactions support all write concern w values, including:

    w: 1

    • Write concern w: 1 returns acknowledgement after the commit has been applied to the primary.

      Important

      When you commit with w: 1, your transaction can be rolled back if there is a failover.

    • When you commit with w: 1 write concern, transaction-level "majority" read concern provides no guarantees that read operations in the transaction read majority-committed data.

    • When you commit with w: 1 write concern, transaction-level "snapshot" read concern provides no guarantee that read operations in the transaction used a snapshot of majority-committed data.

    w: "majority"

    • Write concern w: "majority" returns acknowledgement after the commit has been applied to a majority (M) of voting members; i.e. the commit has been applied to the primary and (M-1) voting secondaries.
    • When you commit with w: "majority" write concern, transaction-level "majority" read concern guarantees that operations have read majority-committed data. For transactions on sharded clusters, this view of the majority-committed data is not synchronized across shards.
    • When you commit with w: "majority" write concern, transaction-level "snapshot" read concern guarantees that operations have from a synchronized snapshot of majority-committed data.

    Note

    Regardless of the write concern specified for the transaction, the commit operation for a sharded cluster transaction includes some parts that use {w: "majority", j: true} write concern.

    General Information

    Production Considerations

    For various production considerations with using transactions, see Production Considerations. In addition, or sharded clusters, see also Production Considerations (Sharded Clusters).

    Arbiters

    Transactions whose write operations span multiple shards will error and abort if any transaction operation reads from or writes to a shard that contains an arbiter.

    See also Disabled Read Concern Majority for transaction restrictions on shards that have disabled read concern majority.

    Disabled Read Concern Majority

    A 3-member PSA (Primary-Secondary-Arbiter) replica set or a sharded cluster with 3-member PSA shards may have disabled read concern majority (--enableMajorityReadConcern false or replication.enableMajorityReadConcern: false)

    On sharded clusters,
    • If a transaction involves a shard that has disabled read concern “majority”, you cannot use read concern "snapshot" for the transaction. You can only use read concern "local" or "majority" for the transaction. If you use read concern "snapshot", the transaction errors and aborts.

      readConcern level 'snapshot' is not supported in sharded clusters when enableMajorityReadConcern=false.
      
    • Transactions whose write operations span multiple shards will error and abort if any of the transaction’s read or write operations involves a shard that has disabled read concern "majority".

    On replica set,

    You can specify read concern "local" or "majority" or "snapshot" even in the replica set has disabled read concern “majority”.

    However, if you are planning to transition to a sharded cluster with disabled read concern majority shards, you may wish to avoid using read concern "snapshot".

    Tip

    To check if read concern “majority” is disabled, You can run db.serverStatus() on the mongod instances and check the storageEngine.supportsCommittedReads field. If false, read concern “majority” is disabled.

    For more information, see 3-Member Primary-Secondary-Arbiter Architecture and Three Member Primary-Secondary-Arbiter Shards.

    Shard Configuration Restriction

    You cannot run transactions on a sharded cluster that has a shard with writeConcernMajorityJournalDefault set to false (such as a shard with a voting member that uses the in-memory storage engine).

    Note

    Regardless of the write concern specified for the transaction, the commit operation for a sharded cluster transaction includes some parts that use {w: "majority", j: true} write concern.

    Diagnostics

    MongoDB provides various transactions metrics:

    Via  
    Returns transactions metrics.
    $currentOp aggregation pipeline

    Returns:

    currentOp command

    Returns:

    mongod and mongos log messages Includes information on slow transactions (i.e. transactions that exceed the operationProfiling.slowOpThresholdMs threshhold) under the TXN log component.

    Feature Compatibility Version (FCV)

    To use transactions, the featureCompatibilityVersion for all members of the deployment must be at least:

    Deployment Minimum featureCompatibilityVersion
    Replica Set 4.0
    Sharded Cluster 4.2

    To check the fCV for a member, connect to the member and run the following command:

    db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
    

    For more information, see the setFeatureCompatibilityVersion reference page.

    Storage Engines

    Starting in MongoDB 4.2, multi-document transactions are supported on replica sets and sharded clusters where:

    • the primary uses the WiredTiger storage engine, and
    • the secondary members use either the WiredTiger storage engine or the in-memory storage engines.

    In MongoDB 4.0, only replica sets using the WiredTiger storage engine supported transactions.

    Note

    You cannot run transactions on a sharded cluster that has a shard with writeConcernMajorityJournalDefault set to false, such as a shard with a voting member that uses the in-memory storage engine.

    Additional Transactions Topics