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.

No MongoDB, transações de vários documentos são executadas dentro de uma sessão de cliente. Uma sessão de cliente é um agrupamento de operações de leitura ou escrita relacionadas que você deseja executar sequencialmente. Recomendamos que você reutilize seu cliente para várias sessões e transações, em vez de fazer a instância de um novo cliente a cada vez.

Quando combinado com majority preocupações de leitura e gravação, o driver garante a consistência causal entre as operações. Para saber mais, consulte Sessões de cliente e garantias de consistência causal no manual do servidor.

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

Se você estiver usando a API Central para executar uma transação, deverá incorporar a lógica de tratamento de erros em seu aplicativo para os seguintes erros:

• TransientTransactionError: gerado se uma operação de gravação falhar antes do driver confirmar a transação. Para saber mais sobre esse erro, consulte a descrição TransientTransactionError na página API do Driver no manual do servidor.

• UnknownTransactionCommitResult: Criado se a operação de confirmação encontrar um erro. Para saber mais sobre esse erro, consulte a descrição UnknownTransactionCommitResult na página API do driver no manual do servidor.

A API Convenient Transaction incorpora a lógica de repetição para esses tipos de erro, de modo que o driver repita a transação até que haja uma confirmação bem-sucedida.