Transactions

Escopo: transversal. Exemplos em JavaScript puro para manter o foco no padrão transacional. As regras aqui valem para qualquer linguagem com acesso a banco transacional ou que precise coordenar mudanças cruzando o limite de um agregado.

Uma transação cobre um agregado. Essa frase resolve a maior parte das dúvidas sobre onde abrir e fechar uma transação, e o resto desta página explica o que fazer quando a operação não cabe nesse formato. Aqui você encontra três decisões: até onde uma transação ACID resolve o problema; quando trocar bloqueio no banco por verificação de versão; quando aceitar que a consistência entre dois agregados vai levar um tempo para se completar e coordenar isso em outro nível.

O que fica de fora: persistência específica (drivers, sintaxe, índices) vive em ../platform/database.md; a propagação de mudanças por eventos vive em domain-events.md; as garantias que cada tipo de broker (intermediário de mensagens) oferece vivem em ../platform/messaging.md.

O agregado define a unidade de consistência forte, e a transação implementa essa consistência no banco. Quando uma operação precisa alterar dois agregados, o desenho está pedindo dois passos.

Esse alinhamento vem de entity-modeling.md. Lá, o agregado é o limite das invariantes (as regras que precisam valer sempre). Aqui, a transação é o limite mecânico que garante essas regras contra concorrência e falha. Quando os dois limites coincidem, o código fica simples. Quando não coincidem, o custo aparece como bloqueio distribuído, 2PC ou bug intermitente.

async function placeOrder(orderInput, customerId) {
  const transaction = await database.beginTransaction();

  try {
    const customer = await customerRepository.findById(customerId, transaction);
    customer.recordPurchase(orderInput.total);
    await customerRepository.save(customer, transaction);

    const order = Order.place({ customerId, ...orderInput });
    await orderRepository.save(order, transaction);

    await transaction.commit();
  } catch (error) {
    await transaction.rollback();
    throw error;
  }
}

async function placeOrder(orderInput, customerId) {
  const order = Order.place({ customerId, ...orderInput });
  const persistedOrder = await orderRepository.save(order);
  return persistedOrder;
}

class CustomerPurchaseRecorder {
  constructor(customerRepository) {
    this.customerRepository = customerRepository;
  }

  async on(event) {
    const customer = await this.customerRepository.findById(event.customerId);
    customer.recordPurchase(event.total);

    await this.customerRepository.save(customer);
  }
}

Quando o caso de uso parece precisar atualizar dois agregados juntos, há três caminhos.

Quando um caso de uso faz várias mudanças no mesmo agregado, o padrão Unit of Work resolve dois problemas: chamar save uma vez só no fim, em vez de a cada alteração, e desfazer tudo automaticamente quando algo falha no meio.

A ideia é manter durante o caso de uso uma lista do que foi criado, alterado e removido, e aplicar tudo junto no commit. Quem chama o caso de uso enxerga apenas a operação; a camada acima abre a unidade de trabalho no começo e a fecha no fim.

async function fulfillOrder(orderId) {
  const order = await orderRepository.findById(orderId);
  order.markAsPickedUp();
  await orderRepository.save(order);

  for (const item of order.items) {
    item.deductFromInventory();
    await inventoryRepository.save(item.productId, item.quantity);
  }

  order.markAsShipped();
  await orderRepository.save(order);
}

class UnitOfWork {
  constructor(database) {
    this.database = database;
    this.pendingSaves = [];
  }

  register(aggregate) {
    this.pendingSaves.push(aggregate);
  }

  async commit() {
    const transaction = await this.database.beginTransaction();

    try {
      for (const aggregate of this.pendingSaves) {
        await aggregate.repository.save(aggregate, transaction);
      }

      await transaction.commit();
    } catch (error) {
      await transaction.rollback();
      throw error;
    }
  }
}

async function fulfillOrder(orderId, unitOfWork) {
  const order = await orderRepository.findById(orderId);
  order.fulfill();

  unitOfWork.register(order);

  return order;
}

Em projeto pequeno, a unidade de trabalho já vem pronta no ORM (Object-Relational Mapping · Mapeamento Objeto-Relacional) que você usa. Em Entity Framework, o DbContext cumpre esse papel; em SQLAlchemy, a Session; em Sequelize, a transaction passada como contexto. Escrever uma classe própria em cima dessa camada compensa quando o domínio cresce a ponto de um caso de uso precisar coordenar várias mudanças.

Duas transações mexendo no mesmo registro ao mesmo tempo é o problema clássico, e há duas formas de resolver. A escolha depende de quanto o conflito acontece.

Pessimismo (SELECT ... FOR UPDATE): a transação reserva o registro para si até o commit, e quem chegar depois espera na fila. Serve para conflito frequente com leitura curta, onde a espera compensa a garantia. Exemplo: estoque em promoção relâmpago, contador de assentos em voo lotado.

Otimismo (campo version incrementado a cada escrita): a transação lê o registro com a versão atual, faz o trabalho em memória e, na hora de gravar, confere se a versão continua a mesma. Se mudou, a escrita falha e o caso de uso decide entre tentar de novo ou avisar o usuário do conflito. Serve para conflito raro e processamento demorado, onde manter o registro bloqueado seria desperdício.

async function topUpWallet(walletId, amount) {
  const wallet = await walletRepository.findById(walletId);
  const newBalance = wallet.balance + amount;
  wallet.balance = newBalance;

  await walletRepository.save(wallet);
}

// dois pedidos chegam ao mesmo tempo, ambos leem balance = 100,
// ambos calculam 100 + 50, ambos gravam 150.
// resultado real: deveria ser 200, ficou 150. perda silenciosa.

class Wallet {
  constructor({ id, balance, version }) {
    this.id = id;
    this.balance = balance;
    this.version = version;
  }

  topUp(amount) {
    if (amount <= 0) {
      throw new Error("amount must be positive");
    }

    this.balance += amount;
    this.version += 1;
  }
}

class WalletRepository {
  async save(wallet) {
    const expectedVersion = wallet.version - 1;

    const updatedRowCount = await this.database.execute(
      `UPDATE
         wallets
       SET
         balance = $1,
         version = $2
       WHERE
         wallets.id = $3 AND
         wallets.version = $4`,
      [wallet.balance, wallet.version, wallet.id, expectedVersion],
    );

    if (updatedRowCount === 0) {
      throw new ConcurrencyConflictError(wallet.id);
    }
  }
}

class SeatRepository {
  async reserveSeat(flightId, seatNumber, customerId) {
    const transaction = await this.database.beginTransaction();

    try {
      const seat = await transaction.queryOne(
        `SELECT
           seats.id,
           seats.status
         FROM
           seats
         WHERE
           seats.flight_id = $1 AND
           seats.seat_number = $2
         FOR UPDATE`,
        [flightId, seatNumber],
      );

      if (seat.status !== "available") {
        throw new SeatUnavailableError(flightId, seatNumber);
      }

      await transaction.execute(
        `UPDATE
           seats
         SET
           status = 'reserved',
           customer_id = $1
         WHERE
           seats.id = $2`,
        [customerId, seat.id],
      );

      await transaction.commit();
    } catch (error) {
      await transaction.rollback();
      throw error;
    }
  }
}

Regra de decisão prática:

Cada caso de uso escolhe uma das duas estratégias e a mantém do início ao fim da transação. Alternar entre elas no mesmo fluxo aumenta a chance de deadlock.

O SQL (Structured Query Language · Linguagem de Consulta Estruturada) define quatro níveis de isolamento, e cada um decide o quanto uma transação enxerga do trabalho ainda em curso das outras. Comece pelo padrão do banco: PostgreSQL e SQL Server entregam Read Committed, que atende à maior parte dos casos.

Duas leituras do mesmo dado que trazem valores diferentes na mesma transação são o non-repeatable read (leitura não repetível). Uma segunda consulta que encontra linhas novas que não existiam na primeira é o phantom read (leitura fantasma).

Suba o nível apenas quando aparecer um bug concreto de leitura inconsistente, e mesmo assim confira antes se a causa era transação longa demais ou agregado mal modelado.

async function reportMonthlyRevenue(month, year) {
  const transaction = await database.beginTransaction("SERIALIZABLE");

  try {
    const totalSales = await transaction.queryOne(
      `SELECT
         SUM(orders.total) AS total_sales
       FROM
         orders
       WHERE
         orders.month = $1 AND
         orders.year = $2`,
      [month, year],
    );

    const refundsTotal = await transaction.queryOne(
      `SELECT
         SUM(refunds.amount) AS total_refunds
       FROM
         refunds
       WHERE
         refunds.month = $1 AND
         refunds.year = $2`,
      [month, year],
    );

    const netRevenue = totalSales.total_sales - refundsTotal.total_refunds;

    await transaction.commit();

    return netRevenue;
  } catch (error) {
    await transaction.rollback();
    throw error;
  }
}

async function reportMonthlyRevenue(month, year) {
  const snapshot = await snapshotRepository.findByMonth(month, year);

  if (!snapshot.isClosed) {
    throw new MonthNotClosedError(month, year);
  }

  return snapshot.netRevenue;
}

Quando subir de fato compensa:

Fora esses casos, o default do banco atende ao código de negócio.

Transação ACID resolve problemas curtos, dentro de um banco, em um agregado. Uma operação com várias etapas, sistemas externos ou tempo de espera (segundos, minutos, horas) trava o sistema se ficar dentro de uma transação aberta. O padrão para esses casos é a saga: uma sequência de transações locais coordenadas, cada uma com sua compensação.

A saga aparece em dois formatos:

Choreography (coreografia): cada serviço escuta eventos e reage por conta própria, sem coordenador central. O acoplamento acontece pelo contrato do evento. Serve para fluxos com poucas etapas e regras estáveis. Exemplo: pedido pago publica OrderSettled → módulo de estoque reserva → publica StockReserved → módulo de entrega agenda.

Orchestration (orquestração): um coordenador comanda os passos. Ele conhece o fluxo inteiro, envia um comando a cada passo e aciona a compensação explícita quando um passo falha. Serve para fluxos longos com muitas etapas e regras de cancelamento. Exemplo: aprovação de empréstimo em sete passos.

async function processPayment(orderId, paymentDetails) {
  const transaction = await database.beginTransaction();

  try {
    const order = await orderRepository.findById(orderId, transaction);

    if (order.status !== "pending") {
      throw new Error("Order is not pending");
    }

    const paymentResult = await paymentGateway.charge(paymentDetails);

    order.markAsSettled(paymentResult.transactionId);
    await orderRepository.save(order, transaction);

    await transaction.commit();
  } catch (error) {
    await transaction.rollback();
    throw error;
  }
}

class Order {
  static place(input) {
    const order = new Order({ ...input, status: "pending" });
    order.events.push(OrderPlaced.from(order));

    return order;
  }

  markAsSettled(externalTransactionId) {
    if (this.status !== "pending") {
      throw new Error(`Cannot pay order in status ${this.status}`);
    }

    this.status = "settled";
    this.externalTransactionId = externalTransactionId;
    this.events.push(OrderSettled.from(this));
  }

  markAsRefunded(reason) {
    if (this.status !== "settled") {
      throw new Error(`Cannot refund order in status ${this.status}`);
    }

    this.status = "refunded";
    this.refundReason = reason;
    this.events.push(OrderRefunded.from(this));
  }
}

class PaymentHandler {
  async on(event) {
    const paymentResult = await this.paymentGateway.charge(
      event.paymentDetails,
    );

    if (!paymentResult.isSuccessful) {
      await this.commandBus.send(
        new CancelOrder(event.orderId, paymentResult.reason),
      );
      return;
    }

    await this.commandBus.send(
      new MarkOrderAsSettled(event.orderId, paymentResult.transactionId),
    );
  }
}

Quatro pontos importantes sobre saga:

Sobre 2PC: o protocolo existe e raramente é a resposta. Ele amarra a disponibilidade do sistema à do recurso mais lento, exige um coordenador transacional ativo, e os bancos modernos desencorajam seu uso em fluxos novos. Quando ele aparece como tentação, o sinal é outro: dois agregados que deveriam ser um, ou uma regra que deveria virar saga.

Duas escritas em agregados separados alcançam consistência com um intervalo entre elas. Aceitar esse intervalo sai mais barato do que disfarçá-lo com 2PC ou bloqueio distribuído.

O outbox é a ferramenta que sustenta essa coordenação sem perder evento no caminho. A regra: na mesma transação que persiste o agregado, gravar o evento na tabela outbox. Um worker (processo separado que roda em segundo plano) lê o outbox e publica no broker. Se a publicação falhar, o evento continua no outbox para a próxima tentativa. Se o consumer (quem consome a mensagem) falhar, ele recebe a mensagem de novo, porque a entrega é at-least-once (ao menos uma vez), e a idempotência cobre a repetição.

async function placeOrder(orderInput) {
  const order = Order.place(orderInput);
  await orderRepository.save(order);

  await eventBus.publish(new OrderPlaced(order));
}

class OrderRepository {
  async save(order) {
    const transaction = await this.database.beginTransaction();

    try {
      await this.persistOrder(order, transaction);
      await this.persistEvents(order.events, transaction);

      await transaction.commit();

      order.events = [];
    } catch (error) {
      await transaction.rollback();
      throw error;
    }
  }

  async persistOrder(order, transaction) {
    await transaction.execute(
      `INSERT INTO orders
       (
         id,
         customer_id,
         status,
         total
       )
       VALUES
         ($1, $2, $3, $4)
       ON CONFLICT (id) DO UPDATE
       SET
         status = $3,
         total = $4`,
      [order.id, order.customerId, order.status, order.total],
    );
  }

  async persistEvents(events, transaction) {
    for (const event of events) {
      await transaction.execute(
        `INSERT INTO outbox
         (
           id,
           type,
           payload,
           created_at
         )
         VALUES
         (
           $1,
           $2,
           $3,
           NOW()
         )`,
        [event.id, event.type, JSON.stringify(event.payload)],
      );
    }
  }
}

Esse intervalo aparece na UI (User Interface · Interface do Usuário): logo após o POST /orders, o usuário ainda pode não ver os efeitos no Customer ou no estoque. Duas abordagens:

Modelar o estado intermediário no agregado (status = "processing" → "confirmed") costuma ser o caminho mais claro. O usuário entende que o pedido foi aceito e que o restante ainda vai acontecer, e a tela reflete o que o backend tem de fato.

ROLLBACK alcança as mudanças no banco. E-mail enviado, pagamento processado, notificação push disparada, vídeo gerado: esses efeitos já saíram e continuam de pé depois do rollback. Quando o caso de uso passou de um agregado, ou passou pelo broker, a forma de desfazer é a compensação semântica: uma operação do domínio que anula o efeito anterior.

Dentro de uma transação ACID, confie no ROLLBACK para tudo. Fora dela, modele a compensação como ação do domínio. "Cancelar pedido pago" é uma operação com nome próprio, regras próprias e, quando for o caso, ação contra terceiros (o reembolso).

async function placeOrder(orderInput) {
  try {
    const order = Order.place(orderInput);
    await orderRepository.save(order);

    await emailService.sendOrderConfirmation(order);
    await paymentGateway.charge(order.total);
  } catch (error) {
    await orderRepository.delete(order.id);
    throw error;
  }
}

class Order {
  static place(input) {
    const order = new Order({ ...input, status: "awaiting_payment" });
    order.events.push(OrderPlaced.from(order));

    return order;
  }

  markAsSettled(externalTransactionId) {
    if (this.status !== "awaiting_payment") {
      throw new Error(`Cannot pay order in status ${this.status}`);
    }

    this.status = "settled";
    this.externalTransactionId = externalTransactionId;
    this.events.push(OrderSettled.from(this));
  }

  cancelDueToPaymentFailure(reason) {
    if (this.status !== "awaiting_payment") {
      throw new Error(`Cannot cancel settled order; refund instead`);
    }

    this.status = "cancelled";
    this.cancellationReason = reason;
    this.events.push(OrderCancelled.from(this));
  }
}

Cross-aggregate transaction. Uma transação tentando manter dois agregados consistentes. Sintoma: findById e save de dois repositórios diferentes dentro do mesmo BEGIN/COMMIT. Tratamento: separar em duas transações e coordenar por evento; ou rever a modelagem, se a invariante de fato atravessa os dois.

Long-lived transaction. Transação aberta durante chamada externa (HTTP, gateway, fila), aprovação humana ou processamento longo. Sintoma: registro bloqueado por minutos; deadlocks crescentes; relatórios sob SERIALIZABLE disputando com escritas. Tratamento: fechar a transação no fim de cada passo curto e modelar o passo longo como saga.

Transação como controle de fluxo. Usar try/catch em volta de transaction.commit como se fosse um if. Sintoma: o catch decide rumo de negócio em vez de tratar erro técnico. Tratamento: validar as pré-condições antes de abrir a transação e deixar o catch cuidar só de erro de infraestrutura.

Distributed 2PC. Tentativa de tornar atômica uma escrita em dois bancos, ou em banco e broker. Sintoma: discussão sobre coordenador transacional, XA, prepare/commit. Tratamento: outbox mais idempotência.

Subir isolation level sem entender o sintoma. Trocar o default por SERIALIZABLE porque "estava dando inconsistência". Sintoma: nada melhora, a vazão cai, conflitos aparecem onde antes não havia. Tratamento: investigar a causa real (transação longa, agregado mal desenhado, ausência de versão) em vez de esconder o problema atrás de um nível mais estrito.

Locking pessimista em caminho quente. SELECT ... FOR UPDATE em fluxo de alta concorrência onde o conflito é raro. Sintoma: fila no banco, usuários esperando, vazão em queda. Tratamento: trocar por bloqueio otimista com version e tentar de novo no caso de uso quando o conflito for esperado.

Rollback como desfeito universal. Esperar que o ROLLBACK corrija efeito que já saiu do sistema (e-mail enviado, pagamento processado, mensagem publicada). Sintoma: pedido apagado e cliente com a confirmação na caixa de entrada; estoque devolvido e terceiro já com o produto a caminho. Tratamento: compensação semântica como operação do domínio, com nome próprio.

Outbox manual sem worker. Gravar o evento na tabela e publicar inline no mesmo request. Sintoma: o "outbox" vira tabela morta e a publicação continua sendo o ponto de falha. Tratamento: um worker separado, dedicado a publicar; o request termina assim que o save completa.

Cross-links dentro do guia:

Bibliografia externa (livros, artigos, especificações): REFERENCES.md.

DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.