Transações

Visão geral

Leia este guia para saber como realizar transação no MongoDB usando o driver Node.js. A transaction is a unit of work, composed of a series of operations that you want either to succeed together, or fail together when one or more of the operations fail. Esse comportamento é chamado de atomicidade. Atomicidade é uma propriedade na qual transação compostas de uma ou mais operações ocorrem de uma só vez, de modo que nenhum outro cliente possa observá-las como operações separadas, e que não deixa alterações se uma das operações falhar.

Como todas as operações de gravação em um único documento no MongoDB são atômicas, você pode se beneficiar mais das transações quando precisar fazer uma alteração atômica que modifique vários documentos, o que é chamado de transação multidocumento. Semelhante às operações de gravação em um único documento, as transações de vários documentos são compatíveis com ACID, o que significa que o MongoDB garante que os dados envolvidos em suas operações de transação permaneçam consistentes, mesmo que encontrem erros inesperados. Saiba mais neste artigo do MongoDB sobre transações ACID.

Você pode usar o driver para realizar transação com vários documento.

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 garantir a execução sequencial. 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 as preocupações de leitura e escrita da maioria, o driver pode garantir consistência causal entre as operações. Consulte o guia do manual do servidor sobre Sessões de cliente e garantias de consistência causal para obter mais informações.

Saiba mais sobre como usar o driver para executar transação de vários documento no MongoDB nas seguintes seções deste guia:

• APIs de transações

• Configurações de transação

• Exemplos de Core API

APIs de transações

Use a Core API para implementar uma transação com o driver. Para usar a Core API, você declara o ponto de início e confirmação da transação.

Configurações de transação

Ao instanciar uma transação, você pode especificar as seguintes opções para definir o comportamento padrão para essa transação:

Se você não fornecer valores, o driver usará as configurações do cliente.

Você pode especificar as opções de transação na Core API usando um código semelhante ao seguinte:

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

Exemplos

Considere um cenário em que um cliente compra itens de sua loja online. Para registrar a compra, seu aplicativo precisa atualizar as informações relacionadas ao estoque, aos pedidos do cliente e registrar os detalhes do pedido. Suponha que você organize as atualizações de dados da seguinte maneira:

Uma compra pode falhar de várias maneiras, como se houver quantidade insuficiente do item no estoque, se o pedido não puder ser concluído ou se o sistema de pagamento estiver off-line.

Se o pagamento falhar, você poderá usar uma transação para evitar a exposição de atualizações parciais que possam causar problemas de consistência de dados para outras operações que dependem desses dados.

{ _id: 98765, orders: [] }

[
 { name: "sunblock", sku: 5432, qty: 85 },
 { name: "beach towel", sku: 7865, qty: 41 }
]

const cart = [
  { name: 'sunblock', sku: 5432, qty: 1, price: 5.19 },
  { name: 'beach towel', sku: 7865, qty: 2, price: 15.99 }
];
const payment = { customer: 98765, total: 37.17 };

1
async function placeOrder(client, cart, payment) {
2
  const transactionOptions = {
3
    readConcern: { level: 'snapshot' },
4
    writeConcern: { w: 'majority' },
5
    readPreference: 'primary'
6
  };
7
8
  const session = client.startSession();
9
  try {
10
    session.startTransaction(transactionOptions);
11
12
    const ordersCollection = client.db('testdb').collection('orders');
13
    const orderResult = await ordersCollection.insertOne(
14
      {
15
        customer: payment.customer,
16
        items: cart,
17
        total: payment.total,
18
      },
19
      { session }
20
    );
21
22
    const inventoryCollection = client.db('testdb').collection('inventory');
23
    for (let i=0; i<cart.length; i++) {
24
      const item = cart[i];
25
26
      // Cancel the transaction when you have insufficient inventory
27
      const checkInventory = await inventoryCollection.findOne(
28
        {
29
          sku: item.sku,
30
          qty: { $gte: item.qty }
31
        },
32
        { session }
33
      )
34
      if (checkInventory === null) {
35
        throw new Error('Insufficient quantity or SKU not found.');
36
      }
37
38
      await inventoryCollection.updateOne(
39
        { sku: item.sku },
40
        { $inc: { 'qty': -item.qty }},
41
        { session }
42
      );
43
    }
44
45
    const customerCollection = client.db('testdb').collection('customers');
46
    await customerCollection.updateOne(
47
      { _id: payment.customer },
48
      { $push:  { orders: orderResult.insertedId }},
49
      { session }
50
    );
51
    await session.commitTransaction();
52
    console.log('Transaction successfully committed.');
53
54
  } catch (error) {
55
    if (error instanceof MongoError && error.hasErrorLabel('UnknownTransactionCommitResult')) {
56
      // add your logic to retry or handle the error
57
    }
58
    else if (error instanceof MongoError && error.hasErrorLabel('TransientTransactionError')) {
59
      // add your logic to retry or handle the error
60
    } else {
61
      console.log('An error occured in the transaction, performing a data rollback:' + error);
62
    }
63
    await session.abortTransaction();
64
  } finally {
65
    await session.endSession();
66
  }
67
}

const { MongoError, MongoClient } = require('mongodb');

{
  "_id": 98765,
  "orders": [
    "61dc..."
  ]
}

[
  {
    "_id": ...,
    "name": "sunblock",
    "sku": 5432,
    "qty": 84
  },
  {
    "_id": ...,
    "name": "beach towel",
    "sku": 7865,
    "qty": 39
  }
]

[
  {
    "_id": "...",
    "customer": 98765,
    "items": [
      {
        "name": "sunblock",
        "sku": 5432,
        "qty": 1,
        "price": 5.19
      },
      {
        "name": "beach towel",
        "sku": 7865,
        "qty": 2,
        "price": 15.99
      }
    ],
    "total": 37.17
  }
]