Database Manual

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 distributed transactions for many practical use cases.在MongoDB中，对单个文档的操作是原子性的。因为您可以使用嵌入式文档和数组来捕获单个文档结构中数据之间的关系，而不是跨多个文档和集合进行规范化，所以这种单一文档原子性消除了许多实际用例对分布式事务的需求。

For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports distributed transactions. With distributed transactions, transactions can be used across multiple operations, collections, databases, documents, and shards.对于需要对多个文档（在单个或多个集合中）进行读写原子性的情况，MongoDB支持分布式事务。通过分布式事务，事务可以跨多个操作、集合、数据库、文档和分片使用。

The information on this page applies to deployments hosted in the following environments:此页面上的信息适用于在以下环境中托管的部署：

Transactions 事务API

➤ Use the Select your language drop-down menu in the upper-right to set the language of the following example.使用右上角的“选择语言”下拉菜单设置以下示例的语言。

C

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:本示例重点介绍了事务API的关键组件。特别是，它使用回调API。回调API：

  • starts a transaction启动事务
  • executes the specified operations执行指定的操作
  • commits the result or ends the transaction on error提交结果或在出现错误时结束事务

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. 服务器端操作中的错误，如DuplicateKeyError，可能会结束事务，并导致命令错误，提醒用户事务已结束。This behavior is expected and occurs even if the client never calls Session.abortTransaction(). 即使客户端从未调用Session.abortTransaction()，也会发生这种行为。To incorporate custom error handling, use the Core API on your transaction.若要合并自定义错误处理，请在事务中使用Core API。

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

Important

static bool
with_transaction_example(bson_error_t *error)
{
   mongoc_client_t *client = NULL;
   mongoc_write_concern_t *wc = 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;对于副本集，在URI字符串中包含副本集名称和成员的种子列表；
    *  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;对于分片集群，连接到mongos实例； 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. Note Atlas connection strings include a majority write
    * concern by default.
    */
   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.第1步：启动客户端会话。 */
   session = mongoc_client_start_session(client, NULL /* opts */, error);
   if (!session) {
      goto fail;
   }

   /* Step 2: Optional. Define options to use for the transaction.第2步：可选。定义用于事务的选项。 */
   txn_opts = mongoc_transaction_opts_new();
   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_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;
}
C++

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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

// Prepare to set majority write explicitly. Note: on Atlas deployments this won't always be
// needed. The suggested Atlas connection string includes majority write concern by default.
write_concern wc_majority{};
wc_majority.acknowledge_level(write_concern::level::k_majority);

// 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 (mongocxx::exception const& 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);

    session.with_transaction(callback, opts);
} catch (mongocxx::exception const& e) {
    std::cout << "An exception occurred: " << e.what() << std::endl;
    return EXIT_FAILURE;
}

return EXIT_SUCCESS;
C#

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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) =>
        {
            try
            {
                collection1.InsertOne(s, new BsonDocument("abc", 1), cancellationToken: ct);
                collection2.InsertOne(s, new BsonDocument("xyz", 999), cancellationToken: ct);
            }
            catch (MongoWriteException)
            {
                // Do something in response to the exception
                throw; // NOTE: You must rethrow the exception otherwise an infinite loop can occur.
            }
            return "Inserted into collections in different databases";
        },
        transactionOptions,
        cancellationToken);
}
Go

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

Important

// WithTransactionExample is an example of using the Session.WithTransaction function.
func WithTransactionExample(ctx context.Context) error {
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()

	clientOpts := options.Client().ApplyURI(uri)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		return err
	}
	defer func() { _ = client.Disconnect(ctx) }()

	// Prereq: Create collections.
	wcMajority := writeconcern.Majority()
	wcMajorityCollectionOpts := options.Collection().SetWriteConcern(wcMajority)
	fooColl := client.Database("mydb1").Collection("foo", wcMajorityCollectionOpts)
	barColl := client.Database("mydb1").Collection("bar", wcMajorityCollectionOpts)

	// Step 1: Define the callback that specifies the sequence of operations to perform inside the transaction.
	callback := func(sesctx context.Context) (any, error) {
		// Important: You must pass sesctx as the Context parameter to the operations for them to be executed in the
		// transaction.
		if _, err := fooColl.InsertOne(sesctx, bson.D{{"abc", 1}}); err != nil {
			return nil, err
		}
		if _, err := barColl.InsertOne(sesctx, bson.D{{"xyz", 999}}); err != nil {
			return nil, err
		}

		return nil, nil
	}

	// Step 2: Start a session and run the callback using WithTransaction.
	session, err := client.StartSession()
	if err != nil {
		return err
	}
	defer session.EndSession(ctx)

	result, err := session.WithTransaction(ctx, callback)
	if err != nil {
		return err
	}
	log.Printf("result: %v\n", result)
	return nil
}
Java(Sync)

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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.
  For example:
  String uri = "mongodb://mongos0.example.com:27017,mongos1.example.com:27017:27017/admin";
 */

final MongoClient client = MongoClients.create(uri);

/*
    Create 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()
        .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();
}
Motor

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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,
    )
Node.js

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:本示例重点介绍了事务API的关键组件。特别是，它使用回调API。回调API：

  • starts a transaction启动事务
  • executes the specified operations执行指定的操作
  • commits the result or ends the transaction on error提交结果或在出现错误时结束事务

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). 服务器端操作中的错误，如DuplicateKeyError，可能会结束事务，并导致命令错误，提醒用户事务已结束。即使客户端从未调用Session.abortTransaction()，也会发生这种行为。To incorporate custom error handling, use the Core API on your transaction.若要合并自定义错误处理，请在事务中使用Core API。

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.回调API包含了针对某些错误的重试逻辑。驱动程序在TransientTransactionError或UnknownTransactionCommitResult提交错误后尝试重新运行事务。

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.从MongoDB 6.2开始，如果服务器收到TransactionTooLargeForCache错误，则不会重试事务。

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.从MongoDB 8.1开始，如果在多文档事务中运行upsert操作，则当遇到重复键错误时，upsert不会重试。

Important

  // For a replica set, include the replica set name and a seedlist of the members in the URI string;对于副本集，在URI字符串中包含副本集名称和成员的种子列表； e.g.
  // const uri = 'mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl'
  // For a sharded cluster, connect to the mongos instances;对于分片集群，连接到mongos实例； e.g.
  // const uri = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'

  const client = new MongoClient(uri);
  await client.connect();

  // Prereq: Create collections.Prereq：创建集合。

  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)步骤3：使用withTransaction启动事务，执行回调，并提交（或在出错时中止）
  // Note: The callback for withTransaction MUST be async and/or return a Promise.注意：withTransaction的回调必须是异步的和/或返回一个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();
  }
Perl

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

Important

sub runTransactionWithRetry {
    my ( $txnFunc, $session ) = @_;

    LOOP: {
        eval {
            $txnFunc->($session); # performs transaction
        };
        if ( my $error = $@ ) {
            print("Transaction aborted-> Caught exception during transaction.\n");
            # If transient error, retry the whole transaction
            if ( $error->has_error_label("TransientTransactionError") ) {
                print("TransientTransactionError, retrying transaction ->..\n");
                redo LOOP;
            }
            else {
                die $error;
            }
        }
    }

    return;
}

sub commitWithRetry {
    my ($session) = @_;

    LOOP: {
        eval {
            $session->commit_transaction(); # Uses write concern set at transaction start.
            print("Transaction committed->\n");
        };
        if ( my $error = $@ ) {
            # Can retry commit
            if ( $error->has_error_label("UnknownTransactionCommitResult") ) {
                print("UnknownTransactionCommitResult, retrying commit operation ->..\n");
                redo LOOP;
            }
            else {
                print("Error during commit ->..\n");
                die $error;
            }
        }
    }

    return;
}

# Updates two collections in a transactions

sub updateEmployeeInfo {
    my ($session) = @_;
    my $employeesCollection = $session->client->ns("hr.employees");
    my $eventsCollection    = $session->client->ns("reporting.events");

    $session->start_transaction(
        {
            readConcern  => { level => "snapshot" },
            writeConcern => { w     => "majority" },
            readPreference => 'primary',
        }
    );

    eval {
        $employeesCollection->update_one(
            { employee => 3 }, { '$set' => { status => "Inactive" } },
            { session => $session},
        );
        $eventsCollection->insert_one(
            { employee => 3, status => { new => "Inactive", old => "Active" } },
            { session => $session},
        );
    };
    if ( my $error = $@ ) {
        print("Caught exception during transaction, aborting->\n");
        $session->abort_transaction();
        die $error;
    }

    commitWithRetry($session);
}

# Start a session
my $session = $client->start_session();

eval {
    runTransactionWithRetry(\&updateEmployeeInfo, $session);
};
if ( my $error = $@ ) {
    # Do something with error
}

$session->end_session();
PHP

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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);
Python

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction启动事务
  • executes the specified operations执行指定的操作
  • commits the result or ends the transaction on error提交结果或在出现错误时结束事务

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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)
Ruby

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

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.
# uri_string = 'mongodb://mongos0.example.com:27017,mongos1.example.com:27017/'

client = Mongo::Client.new(uri_string, write_concern: {w: :majority, wtimeout: 1000})

# Prereq: Create collections.

client.use('mydb1')['foo'].insert_one(abc: 0)
client.use('mydb2')['bar'].insert_one(xyz: 0)

# Step 1: Define the callback that specifies the sequence of operations to perform inside the transactions.

callback = Proc.new do |my_session|
  collection_one = client.use('mydb1')['foo']
  collection_two = client.use('mydb2')['bar']

  # Important: You must pass the session to the operations.

  collection_one.insert_one({'abc': 1}, session: my_session)
  collection_two.insert_one({'xyz': 999}, session: my_session)
end

#. Step 2: Start a client session.

session = client.start_session

# Step 3: Use with_transaction to start a transaction, execute the callback, and commit (or abort on error).

session.with_transaction(
  read_concern: {level: :local},
  write_concern: {w: :majority, wtimeout: 1000},
  read: {mode: :primary},
  &callback)
Rust

This example highlights the key components of the transactions API. In particular, it uses the callback API. The callback API:

  • starts a transaction
  • executes the specified operations
  • commits the result or ends the transaction on error

Errors in server-side operations, such as the DuplicateKeyError, can end the transaction and result in a command error to alert the user that the transaction has ended. This behavior is expected and occurs even if the client never calls Session.abortTransaction(). To incorporate custom error handling, use the Core API on your transaction.

The callback API incorporates retry logic for certain errors. The driver tries to rerun the transaction after a TransientTransactionError or UnknownTransactionCommitResult commit error.

Starting in MongoDB 6.2, the server does not retry the transaction if it receives a TransactionTooLargeForCache error.

Starting in MongoDB 8.1, if an upsert operation runs in a multidocument transaction, then the upsert does not retry when it encounters a duplicate key error.

Important

// Prereq: Create collections. CRUD operations in transactions must be on existing collections.

client
    .database("mydb1")
    .collection::<Document>("foo")
    .insert_one(doc! { "abc": 0})
    .await?;
client
    .database("mydb2")
    .collection::<Document>("bar")
    .insert_one(doc! { "xyz": 0})
    .await?;

// Step 1: Define the callback that specifies the sequence of operations to perform inside the
// transaction.
async fn callback(session: &mut ClientSession) -> Result<()> {
    let collection_one = session
        .client()
        .database("mydb1")
        .collection::<Document>("foo");
    let collection_two = session
        .client()
        .database("mydb2")
        .collection::<Document>("bar");

    // Important: You must pass the session to the operations.
    collection_one
        .insert_one(doc! { "abc": 1 })
        .session(&mut *session)
        .await?;
    collection_two
        .insert_one(doc! { "xyz": 999 })
        .session(session)
        .await?;

    Ok(())
}

// Step 2: Start a client session.
let mut session = client.start_session().await?;

// Step 3: Use and_run2 to start a transaction, execute the callback, and commit (or
// abort on error).
session.start_transaction().and_run2(callback).await?;
Scala

This example uses the core API. Because the core API does not incorporate retry logic for the TransientTransactionError or UnknownTransactionCommitResult commit errors, the example includes explicit logic to retry the transaction for these errors:

Important

/*
 * Copyright 2008-present MongoDB, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.mongodb.scala

import org.mongodb.scala.model.{Filters, Updates}
import org.mongodb.scala.result.UpdateResult

import scala.concurrent.Await
import scala.concurrent.duration.Duration


//scalastyle:off magic.number
class DocumentationTransactionsExampleSpec extends RequiresMongoDBISpec {

  // Implicit functions that execute the Observable and return the results
  val waitDuration = Duration(5, "seconds")
  implicit class ObservableExecutor[T](observable: Observable[T]) {
    def execute(): Seq[T] = Await.result(observable.toFuture(), waitDuration)
  }

  implicit class SingleObservableExecutor[T](observable: SingleObservable[T]) {
    def execute(): T = Await.result(observable.toFuture(), waitDuration)
  }
  // end implicit functions

  "The Scala driver" should "be able to commit a transaction" in withClient { client =>
    assume(serverVersionAtLeast(List(4, 0, 0)) && !hasSingleHost())
    client.getDatabase("hr").drop().execute()
    client.getDatabase("hr").createCollection("employees").execute()
    client.getDatabase("hr").createCollection("events").execute()

    updateEmployeeInfoWithRetry(client).execute() should equal(Completed())
    client.getDatabase("hr").drop().execute() should equal(Completed())
  }

  def updateEmployeeInfo(database: MongoDatabase, observable: SingleObservable[ClientSession]): SingleObservable[ClientSession] = {
    observable.map(clientSession => {
      val employeesCollection = database.getCollection("employees")
      val eventsCollection = database.getCollection("events")

      val transactionOptions = TransactionOptions.builder()
        .readPreference(ReadPreference.primary())
        .readConcern(ReadConcern.SNAPSHOT)
        .writeConcern(WriteConcern.MAJORITY)
        .build()
      clientSession.startTransaction(transactionOptions)
      employeesCollection.updateOne(clientSession, Filters.eq("employee", 3), Updates.set("status", "Inactive"))
        .subscribe((res: UpdateResult) => println(res))
      eventsCollection.insertOne(clientSession, Document("employee" -> 3, "status" -> Document("new" -> "Inactive", "old" -> "Active")))
        .subscribe((res: Completed) => println(res))

      clientSession
    })
  }

  def commitAndRetry(observable: SingleObservable[Completed]): SingleObservable[Completed] = {
    observable.recoverWith({
      case e: MongoException if e.hasErrorLabel(MongoException.UNKNOWN_TRANSACTION_COMMIT_RESULT_LABEL) => {
        println("UnknownTransactionCommitResult, retrying commit operation ...")
        commitAndRetry(observable)
      }
      case e: Exception => {
        println(s"Exception during commit ...: $e")
        throw e
      }
    })
  }

  def runTransactionAndRetry(observable: SingleObservable[Completed]): SingleObservable[Completed] = {
    observable.recoverWith({
      case e: MongoException if e.hasErrorLabel(MongoException.TRANSIENT_TRANSACTION_ERROR_LABEL) => {
        println("TransientTransactionError, aborting transaction and retrying ...")
        runTransactionAndRetry(observable)
      }
    })
  }

  def updateEmployeeInfoWithRetry(client: MongoClient): SingleObservable[Completed] = {

    val database = client.getDatabase("hr")
    val updateEmployeeInfoObservable: Observable[ClientSession] = updateEmployeeInfo(database, client.startSession())
    val commitTransactionObservable: SingleObservable[Completed] =
      updateEmployeeInfoObservable.flatMap(clientSession => clientSession.commitTransaction())
    val commitAndRetryObservable: SingleObservable[Completed] = commitAndRetry(commitTransactionObservable)

    runTransactionAndRetry(commitAndRetryObservable)
  }
}

Tip

For an example in mongosh, see mongosh Example.有关mongosh的示例，请参阅mongosh示例。

Transactions and Atomicity事务和原子性

For situations that require atomicity of reads and writes to multiple documents (in a single or multiple collections), MongoDB supports distributed transactions, including transactions on replica sets and sharded clusters.对于需要对多个文档（在单个或多个集合中）进行读写原子性的情况，MongoDB支持分布式事务，包括副本集和分片集群上的事务。

Distributed transactions are atomic:分布式事务是原子性的：

  • Transactions either apply all data changes or roll back the changes.事务要么应用所有数据更改，要么回滚更改。

  • If a transaction commits, all data changes made in the transaction are saved and are visible outside of the transaction.如果事务提交，则事务中所做的所有数据更改都将被保存，并在事务外部可见。

    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.例如，如果一个事务已提交，并且写1在分片a上可见，但写2在分片B上尚不可见，则外部读取关注"local"可以读取写1的结果，而看不到写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, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed 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 distributed transactions.对于许多场景，非规范化数据模型（嵌入式文档和数组）将继续是您的数据和用例的最佳选择。也就是说，对于许多场景，适当地对数据进行建模将最大限度地减少对分布式事务的需求。

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.有关其他事务使用注意事项（如运行时限制和oplog大小限制），另请参阅生产注意事项。

Tip

Outside Reads During Commit提交过程中的外部阅读

Transactions and Operations事务和运营

Distributed transactions can be used across multiple operations, collections, databases, documents, and shards.分布式事务可以跨多个操作、集合、数据库、文档和分片使用。

For transactions:对于事务：

  • You can create collections and indexes in transactions. For details, see Create Collections and Indexes in a Transaction您可以在事务中创建集合和索引。有关详细信息，请参阅在事务中创建集合和索引

  • The collections used in a transaction can be in different databases.事务中使用的集合可以在不同的数据库中。

    Note

    You cannot create new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.您无法在跨分片写入事务中创建新集合。例如，如果你在一个分片中写入一个现有的集合，并在另一个分片中隐式创建一个集合，MongoDB无法在同一事务中执行这两个操作。

  • You cannot write to capped collections.您不能写入封顶集合。
  • You cannot use read concern "snapshot" when reading from a capped collection. (Starting in MongoDB 5.0)从封顶集合中读取时，不能使用读取关注"snapshot"。（从MongoDB 5.0开始）
  • You cannot read/write to collections in the config, admin, or local databases.您无法对config、admin或local数据库中的集合进行读写操作。
  • You cannot write to system.* collections.您无法写入system.*集合。
  • You cannot return the supported operation's query plan using explain or similar commands.您无法使用explain或类似命令返回受支持操作的查询计划。
  • For cursors created outside of a transaction, you cannot call getMore inside the transaction.对于在事务外部创建的游标，您不能在事务内部调用getMore。
  • For cursors created in a transaction, you cannot call getMore outside the transaction.对于在事务中创建的游标，您不能在事务外部调用getMore。

  • You cannot specify the killCursors command as the first operation in a transaction.

    Additionally, if you run the killCursors command within a transaction, the server immediately stops the specified cursors. It does not wait for the transaction to commit.此外，如果在事务中运行killCursors命令，服务器会立即停止指定的游标。它不会等待事务提交。

For a list of operations not supported in transactions, 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.在启动事务之前立即创建或删除集合时，如果在事务中访问了该集合，则发出带有写关注"majority"的创建或删除操作，以确保事务能够获取所需的锁。

Tip

Transactions and Operations Reference事务和运营参考

Create Collections and Indexes in a Transaction在事务中创建集合和索引

You can perform the following operations in a distributed transaction if the transaction is not a cross-shard write transaction:如果分布式事务不是跨分片写入事务，则可以在该事务中执行以下操作：

  • Create collections.创建集合。
  • Create indexes on new empty collections created earlier in the same transaction.在同一事务中较早创建的新空集合上创建索引。

When creating a collection inside a transaction:在事务中创建集合时：

When creating an index inside a transaction [1], the index to create must be on either:

  • a non-existent collection. The collection is created as part of the operation.一个不存在的集合。该集合是作为操作的一部分创建的。
  • a new empty collection created earlier in the same transaction.在同一事务中较早创建的新空集合。
[1] You can also run db.collection.createIndex() and db.collection.createIndexes() on existing indexes to check for existence. These operations return successfully without creating the index.

Restrictions限制

  • You cannot create new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.
  • You cannot use the $graphLookup stage within a transaction while targeting a sharded collection.在针对分片集合时，您不能在事务中使用$graphLookup阶段。

  • For explicit creation of a collection or an index inside a transaction, the transaction read concern level must be "local".为了在事务中显式创建集合或索引，事务读取关注级别必须是"local"的。

    To explicitly create collections and indexes, use the following commands and methods:要显式创建集合和索引，请使用以下命令和方法：

    CommandMethod
    createdb.createCollection()
    createIndexesdb.collection.createIndex()
    db.collection.createIndexes()

Tip

Restricted Operations

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 provide a collection-level API countDocuments(filter, options) as a helper method that uses the $group with a $sum expression to perform a count.

mongosh 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:

Tip

Transactions and Sessions

  • Transactions are associated with a session.
  • You can have at most one open transaction at a time 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.

Distributed 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. This means a 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, the client-level read concern is "local" for reads on 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.
  • On a replica set, even if a transaction uses read concern local, you might observe stronger read isolation where the operation reads from a snapshot at the point in time that the transaction was opened.
  • 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.
  • You can create collections and indexes inside a transaction. If explicitly creating a collection or an index, the transaction must use read concern "local". If you implicitly create a collection, you can use any of the read concerns available for transactions.

"majority"

  • If the transaction commits with write concern "majority", read concern "majority" returns data that has been acknowledged by a majority of the replica set members and can't be rolled back. Otherwise, read concern "majority" provides no guarantees that read operations read majority-committed data.
  • For transactions on sharded cluster, read concern "majority" can't guarantee that the data is from the same snapshot view across the shards. If snapshot isolation is required, use read concern "snapshot".

"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 run without an explicit write concern specification and use the default write concern. At commit time, the writes committed using the transaction-level write concern.

Tip

Don't explicitly set the write concern for the individual write operations inside a transaction. Setting write concerns for the individual write operations inside a transaction returns 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, the transaction-level write concern defaults to the client-level write concern of:

Tip

Default MongoDB Read Concerns/Write Concerns

Transactions support all write concern w values, including:

w: 1

  • Write concern w: 1 returns acknowledgment 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 acknowledgment after the commit has been applied to a majority of voting members.
  • 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 read 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.

The server parameter coordinateCommitReturnImmediatelyAfterPersistingDecision controls when transaction commit decisions are returned to the client.

The parameter was introduced in MongDB 5.0 with a default value of true. In MongoDB 6.1 the default value changes to false.

When coordinateCommitReturnImmediatelyAfterPersistingDecision is false, the shard transaction coordinator waits for all members to acknowledge a multi-document transaction commit before returning the commit decision to the client.

If you specify a "majority" write concern for single-document and multi-document writes and the operation does not replicate to the calculated majority of replica set members before it returns a response, then the data eventually replicates or rolls back. See wtimeout.

Regardless of the write concern specified for the transaction, the driver applies w: "majority" as the write concern when retrying commitTransaction.

General Information

The following sections describe more considerations for transactions.

Production Considerations

For transactions in production environments, see Production Considerations. In addition, for sharded clusters, see Production Considerations (Sharded Clusters).

Arbiters

You cannot change a shard key using a transaction if the replica set has an arbiter. Arbiters cannot participate in the data operations required for multi-shard transactions.

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.

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

To obtain transaction status and metrics, use the following methods:

SourceReturns
db.serverStatus() method
serverStatus command

Returns transactions metrics.

Some serverStatus response fields are not returned on MongoDB Atlas M0 clusters or Flex clusters. For more information, see Limited Commands in the MongoDB Atlas documentation.

$currentOp aggregation pipeline

Returns:

db.currentOp() method
currentOp command

Returns:

mongod and mongos log messagesIncludes information on slow transactions (which are transactions that exceed the operationProfiling.slowOpThresholdMs threshold) in the TXN log component.

Feature Compatibility Version (FCV)

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

DeploymentMinimum featureCompatibilityVersion
Replica Set4.0
Sharded Cluster4.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

distributed 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.

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.

Limit Critical Section Wait Time

Starting in MongoDB 5.2 (and 5.0.4):

  • When a query accesses a shard, a chunk migration or DDL operation may hold the critical section for the collection.

  • To limit the time a shard waits for a critical section within a transaction, use the metadataRefreshInTransactionMaxWaitMS parameter.

    Note

    Starting in MongoDB 8.1, the old metadataRefreshInTransactionMaxWaitBehindCritSecMS parameter is renamed metadataRefreshInTransactionMaxWaitMS. You can continue to use metadataRefreshInTransactionMaxWaitBehindCritSecMS as the parameter name, but it is deprecated and will be removed in a future MongoDB release.

Learn More了解更多