Drivers API

Drivers API

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 thetransacdtion.
Does not incorporate error handling logic for"TransientTransactionError" and"UnknownTransactionCommitResult", and instead provides theflexibility to incorporate custom error handling for these errors.

Callback API

The new callback API incorporates logic:

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

Python
Java (Sync)
Node.js
PHP
C#

Important

For transactions on MongoDB 4.2 deployments (replicasets and sharded clusters), clients must useMongoDB drivers updated for MongoDB 4.2.
When using the drivers, each operation in thetransaction must be associated with the session (i.e.pass in the session to each operation).

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

# 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. CRUD operations in transactions must be on existing 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)

Important

For transactions on MongoDB 4.2 deployments (replicasets and sharded clusters), clients must useMongoDB drivers updated for MongoDB 4.2.
When using the drivers, each operation in thetransaction must be associated with the session (i.e.pass in the session to each operation).

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

Important

For transactions on MongoDB 4.2 deployments (replicasets and sharded clusters), clients must useMongoDB drivers updated for MongoDB 4.2.
When using the drivers, each operation in thetransaction must be associated with the session (i.e.pass in the session to each operation).

  // 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. CRUD operations in transactions must be on existing collections.
 
  await client
    .db('mydb1')
    .collection('foo')
    .insertOne({ abc: 0 }, { w: 'majority' });
 
  await client
    .db('mydb2')
    .collection('bar')
    .insertOne({ xyz: 0 }, { 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 withtransactions, which starts a transaction, executes thespecified operations, and commits (or aborts on error). Thenew callback API also incorporates retry logic forTransientTransactionError orUnknownTransactionCommitResult commit errors.

Important

For transactions on MongoDB 4.2 deployments (replicasets and sharded clusters), clients must useMongoDB drivers updated for MongoDB 4.2.
When using the drivers, each operation in thetransaction must be associated with the session (i.e.pass in the session to each operation).

/*
 * 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. CRUD operations in transactions must be on existing 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) {
    $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).
 
$transactionOptions = [
    'readConcern' => new \MongoDB\Driver\ReadConcern(\MongoDB\Driver\ReadConcern::LOCAL),
    'writeConcern' => new \MongoDB\Driver\WriteConcern(\MongoDB\Driver\WriteConcern::MAJORITY, 1000),
    'readPreference' => new \MongoDB\Driver\ReadPreference(\MongoDB\Driver\ReadPreference::RP_PRIMARY),
];
 
\MongoDB\with_transaction($session, $callback, $transactionOptions);

The example uses the new callback API for working withtransactions, which starts a transaction, executes thespecified operations, and commits (or aborts on error). Thenew callback API also incorporates retry logic forTransientTransactionError orUnknownTransactionCommitResult commit errors.

Important

For transactions on MongoDB 4.2 deployments (replicasets and sharded clusters), clients must useMongoDB drivers updated for MongoDB 4.2.
When using the drivers, each operation in thetransaction must be associated with the session (i.e.pass in the session to each operation).

// 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. CRUD operations in transactions must be on existing 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(
        readPreference: ReadPreference.Primary,
        readConcern: ReadConcern.Local,
        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);
}

Core API

The core transaction API does not incorporate retry logic for errorslabeled:

"TransientTransactionError". If an operation in a transactionreturns an error labeled "TransientTransactionError", thetransaction as a whole can be retried.

To handle "TransientTransactionError", applications shouldexplicitly incorporate retry logic for the error.

"UnknownTransactionCommitResult". If the commit returns anerror labeled "UnknownTransactionCommitResult", the commitcan be retried.

To handle "UnknownTransactionCommitResult",applications should explicitly incorporate retry logic for the error.

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

Python
Java (Sync)
Node.js
PHP
C
Other
- C++11
- C#
- Perl
- Ruby
- Scala
- Go

Important