API de drivers

Esta versão da documentação foi arquivada e não é mais suportada. Para atualizar seu sistema do 6.0, consulte osprocedimentos de atualização do MongoDB 7.0 .

API de retorno de chamada versus API central

A Callback API:

Inicia uma transação, executa as operações especificadas e commits (ou cancela por engano).
Incorpora automaticamente a lógica de tratamento de erros para TransientTransactionError e UnknownTransactionCommitResult.

A Core API:

Requer chamada explícita para iniciar a transação e confirmar a transação.
Não incorpora a lógica de tratamento de erros para TransientTransactionError e UnknownTransactionCommitResult e, em vez disso, oferece a flexibilidade de incorporar o tratamento de erros personalizado para esses erros.

API de retorno de chamada

A API de retorno de chamada incorpora lógica:

Para repetir a transação como um todo se a transação encontrar um erro TransientTransactionError.
Para tentar novamente a operação de confirmação se a confirmação encontrar um erro UnknownTransactionCommitResult.

Iniciando no MongoDB 6.0.5, o servidor não tenta novamente a transação se receber um erro TransactionTooLargeForCache .

Exemplo

➤ Use o menu suspenso Selecione a linguagem no canto superior direito para definir a linguagem dos exemplos nesta página.

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam preocupação de leitura em nível de transação, preocupação de gravação em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

O exemplo usa a nova Callback API para trabalhar com transações, que inicia uma transação, executa as operações especificadas e confirma (ou anula em caso de erro). A nova Callback API incorpora lógica de nova tentativa para erros de confirmação TransientTransactionError ou UnknownTransactionCommitResult.

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

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

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

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

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

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

Observação

Para o driver Perl , consulte o exemplo de uso da Core API .

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

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

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

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

Importante

Use o driver do MongoDB para sua versão do MongoDB.
Ao usar drivers, cada operação na transação deve passar a sessão para cada operação.
As operações em uma transação usam read concern em nível de transação, write concern em nível de transação e preferência de leitura em nível de transação.
Você pode criar collections em transações de forma implícita ou explícita. Consulte Como criar collections e índices em uma transação.

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

Observação

Para o driver Scala , consulte o exemplo de uso da Core API .

Core API

A API de transação principal não incorpora lógica de repetição para erros rotulados:

TransientTransactionError. Se uma operação em uma transação retornar um erro rotulado como TransientTransactionError, a transação como um todo poderá ser repetida.
Para lidar com TransientTransactionError, os aplicativos devem incorporar explicitamente a lógica de repetição para o erro.
UnknownTransactionCommitResult. Se a confirmação retornar um erro denominado UnknownTransactionCommitResult, a confirmação poderá ser repetida.
Para lidar com UnknownTransactionCommitResult, os aplicativos devem incorporar explicitamente a lógica de repetição para o erro.

Exemplo

➤ Use o menu suspenso Selecione a linguagem no canto superior direito para definir a linguagem dos exemplos nesta página.

O exemplo a seguir incorpora a lógica para tentar novamente a transação em caso de erros transitórios e tentar novamente o commit em caso de erro de commit desconhecido: