Drivers API

This version of the documentation is archived and no longer supported. To upgrade your 6.0 deployment, see the MongoDB 7.0 upgrade procedures.

Callback API vs Core API

The Callback API:

Starts a transaction, executes the specified operations, and commits (or aborts on error).
Automatically incorporates error handling logic for TransientTransactionError and UnknownTransactionCommitResult.

The Core API:

Requires explicit call to start the transaction and commit the transaction.
Does not incorporate error handling logic for TransientTransactionError and UnknownTransactionCommitResult, and instead provides the flexibility to incorporate custom error handling for these errors.

Callback API

The callback API incorporates logic:

To retry the transaction as a whole if the transaction encounters a TransientTransactionError error.
To retry the commit operation if the commit encounters an UnknownTransactionCommitResult error.

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

Example

➤ Use the Select your language drop-down menu in the upper-right to set the language of the examples on this page.

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

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

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

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

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

# 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,
    )

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

  // 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();
  }

Note

For the Perl driver, see the Core API usage example instead.

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

/*
 * 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);

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

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

Important

Use the MongoDB driver for your MongoDB version.
When using drivers, each operation in the transaction must pass the session to each operation.
Operations in a transaction use transaction-level read concern, transaction-level write concern, and transaction-level read preference.
You can create collections in transactions implicitly or explicitly. See Create Collections and Indexes in a Transaction.

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

Note

For the Scala driver, see the Core API usage example instead.

Core API

The core transaction API does not incorporate retry logic for errors labeled:

TransientTransactionError. If an operation in a transaction returns an error labeled TransientTransactionError, the transaction as a whole can be retried.
To handle TransientTransactionError, applications should explicitly incorporate retry logic for the error.
UnknownTransactionCommitResult. If the commit returns an error labeled UnknownTransactionCommitResult, the commit can be retried.
To handle UnknownTransactionCommitResult, applications should explicitly incorporate retry logic for the error.

Example

➤ Use the Select your language drop-down menu in the upper-right to set the language of the examples on this page.

The following example incorporates logic to retry the transaction for transient errors and retry the commit for unknown commit error: