Transações

Visão geral

Neste guia, você pode aprender a usar o driver Node.js para executar transações. As transações permitem que você execute uma série de operações que não alteram nenhum dado até que toda a transação seja confirmada. Se qualquer operação na transação falhar, o driver encerra a transação e descarta todas as alterações de dados antes que elas se tornem visíveis. Esse recurso é chamado de atomicidade.

Como todas as operações de gravação em um único documento no MongoDB são atômicas, convém usar transações para fazer uma alteração atômica que modifique vários documentos. Essa situação exige uma transação multidocumento. As transações de vários documentos são compatíveis com ACID porque o MongoDB garante que os dados envolvidos em suas operações de transação permaneçam consistentes, mesmo se o driver encontrar erros inesperados.

Para saber mais sobre conformidade com ACID e ACID transactions, consulte nosso artigo sobre transações ACID.

Saiba mais sobre como usar o driver para realizar transações com vários documentos nas seguintes seções deste guia:

• APIs de transações

• opções de transação

• Erros de transação

APIs de transações

O driver fornece duas APIs para realizar transações, a API Principal e a API de Transações Convenientes.

A API principal é uma estrutura que permite criar, confirmar e encerrar transações. Ao usar esta API, você deve executar explicitamente as seguintes ações:

• Crie, confirme e encerre a transação.

• Crie e finalize a sessão na qual você executa a transação.

• Implemente lógica de tratamento de erros.

A Convenient Transaction API é uma estrutura que permite que você execute transações sem ser responsável por confirmá-las ou encerrá-las. Essa API incorpora automaticamente a lógica de tratamento de erros para tentar novamente as operações quando o servidor gera determinados tipos de erro. Para saber mais sobre esse comportamento, consulte a seção Erros de transação deste guia.

async function coreTest(client) {
  const session = client.startSession();
  try {
    session.startTransaction();
    const savingsColl = client.db("bank").collection("savings_accounts");
    await savingsColl.findOneAndUpdate(
      {account_id: "9876"}, 
      {$inc: {amount: -100 }}, 
      { session });
    const checkingColl = client.db("bank").collection("checking_accounts");
    await checkingColl.findOneAndUpdate(
      {account_id: "9876"}, 
      {$inc: {amount: 100 }}, 
      { session });
    // ... perform other operations
    await session.commitTransaction();
    console.log("Transaction committed.");
  } catch (error) {
    console.log("An error occurred during the transaction:" + error);
    await session.abortTransaction();
  } finally {
    await session.endSession();
  }
}

const session = client1.startSession();
client2.db('myDB').collection('myColl').insertOne({ name: 'Jane Eyre' }, { session });

async function convTest(client) {
  let txnRes = await client.withSession(async (session) =>
    session.withTransaction(async (session) => {
      const savingsColl = client.db("bank").collection("savings_accounts");
      await savingsColl.findOneAndUpdate(
        {account_id: "9876"}, 
        {$inc: {amount: -100 }}, 
        { session });
  
      const checkingColl = client.db("bank").collection("checking_accounts");
      await checkingColl.findOneAndUpdate(
        {account_id: "9876"}, 
        {$inc: {amount: 100 }}, 
        { session });
      // ... perform other operations
      return "Transaction committed.";
    }, null)
  );
  console.log(txnRes);
}

opções de transação

Você pode passar uma instância TransactionOptions para os métodos startTransaction() e withTransaction() para configurar como o driver executa uma transação. Quando você especifica uma opção, ela substitui o valor da opção que você pode ter definido em sua instância MongoClient .

A tabela seguinte inclui opções que você pode especificar em uma instância do TransactionOptions :

Para obter uma lista completa de opções, consulte a documentação da API para TransactionOptions.

O código a seguir mostra como definir e passar as opções de transação para o método startTransaction():

const txnOpts = {
  readPreference: 'primary',
  readConcern: { level: 'local' },
  writeConcern: { w: 'majority' },
  maxCommitTimeMS: 1000
};
session.startTransaction(txnOpts);

Erros de transação

Como as transações do MongoDB são compatíveis com ACID, o driver pode produzir erros durante a operação para garantir que seus dados permaneçam consistentes. Se ocorrerem os seguintes erros, seu aplicação deverá tentar novamente a transação:

• TransientTransactionError: gerado se uma operação de gravação encontrar um erro antes do driver confirmar a transação. Para saber mais sobre esse tipo de erro, consulte a Descrição do TransientTransactionError na página API de Drivers no manual do Servidor.

• UnknownTransactionCommitResult: Criado se a operação de commit encontrar um erro. Para saber mais sobre esse tipo de erro, consulte a Descrição do UnknownTransactionCommitResult na página API de Drivers no manual do Servidor.

As seções a seguir descrevem como lidar com esses erros ao usar APIs diferentes.