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.

Esta página atende a duas pessoas. A primeira está desenhando a primeira operação de escrita do projeto e quer saber onde abrir e fechar a transação. A segunda volta para revisitar um caso difícil (por exemplo, vale a pena segurar lock no banco para garantir que dois usuários não comprem o último item ao mesmo tempo, ou modelar como saga). As duas saem daqui com critério, não com receita fechada.

O texto cobre três perguntas que aparecem cedo em todo sistema que persiste estado: até onde uma transação ACID resolve o problema; quando trocar lock por verificação de versão; quando aceitar que a consistência vai ser eventual e modelar a coordenação em outro nível. 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; o que cada tipo de broker (intermediário de mensagens) entrega em garantias vive em ../platform/messaging.md.

A regra que organiza todo o resto é simples: uma transação cobre um agregado. O agregado define a unidade de consistência forte; a transação implementa essa consistência no banco. Quando uma operação precisa alterar dois agregados, o desenho está pedindo dois passos, não uma transação maior.

Esse alinhamento vem de entity-modeling.md. Lá, o agregado é a fronteira de invariantes. Aqui, a transação é a fronteira mecânica que garante essas invariantes contra concorrência e falha. Quando os dois limites coincidem, o código é simples; quando não coincidem, alguém vai precisar pagar a diferença com lock 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);
  }
}

A consequência prática: quando o caso de uso parece precisar atualizar dois agregados juntos, há três caminhos.

Quando um caso de uso precisa fazer várias mudanças no mesmo agregado, ou em vários objetos do mesmo agregado, o padrão Unit of Work resolve dois problemas: chamar save uma vez só no fim (em vez de a cada mutação), e fazer rollback automático quando algo dá errado no meio.

A ideia central é manter uma lista de "novas", "alteradas" e "removidas" durante o caso de uso, e aplicar tudo de uma vez no commit. Quem chama o caso de uso não enxerga o detalhe; apenas executa a operação dentro de um bloco que abre o UoW no começo e 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, o UoW pode ser implícito: o ORM (Object-Relational Mapping) que você usa já implementa a ideia. Em Entity Framework, o próprio DbContext é um UoW; em SQLAlchemy, a Session; em Sequelize, a transaction passada como contexto. Em projeto grande, montar uma classe própria sobre essa camada faz sentido quando o domínio cresce a ponto de o caso de uso precisar coordenar várias mudanças.

Concorrência é o problema clássico que transação resolve, mas o como muda conforme a frequência do conflito. As duas estratégias atendem cenários distintos.

Pessimismo (SELECT ... FOR UPDATE): a transação reserva o registro para si até o commit. Concorrentes esperam. Funciona para conflitos frequentes e leituras curtas, onde a fila vale o preço da garantia. Exemplo: estoque em flash sale, contador de assentos em voo lotado.

Otimismo (campo version incrementado a cada escrita): a transação lê o registro com sua versão atual, faz o que precisa fazer em memória, e na hora de gravar verifica se a versão ainda é a mesma. Se não for, falha e o caso de uso decide se retenta ou propaga o conflito para o usuário. Funciona para conflitos raros e tempos de processamento maiores, onde manter lock 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:

Misturar mal os dois é caminho para deadlock. Cada caso de uso escolhe uma estratégia e mantém durante a transação.

Quatro níveis padrão do SQL (Structured Query Language, Linguagem Estruturada de Consulta) decidem o quanto uma transação enxerga do trabalho em curso das outras. O nível default da maioria dos bancos modernos (PostgreSQL, SQL Server) é Read Committed, e essa é a escolha razoável para a maior parte dos casos.

A regra prática: começar com o default do banco. Subir o nível só quando aparece um bug específico de leitura inconsistente, e mesmo assim revisar se o problema não estava na transação longa demais ou no 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 faz sentido:

Transação ACID resolve problemas curtos, dentro de um banco, de um agregado. Quando a operação envolve várias etapas, sistemas externos ou tempo de espera (segundos, minutos, horas), segurar uma transação no banco trava o sistema. 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 sabores:

Choreography (coreografia): cada serviço escuta eventos e reage. Não há coordenador central. Acoplamento por contrato de evento; bom para fluxos com poucas etapas e regras estáveis. Exemplo: pedido pago publica OrderPaid → módulo de estoque reserva → publica StockReserved → módulo de entrega agenda.

Orchestration (orquestração): um coordenador comanda os passos. O coordenador conhece o fluxo inteiro, cada passo recebe um comando, cada falha aciona compensação explícita. Bom para fluxos longos com muitas etapas e regras de cancelamento. Exemplo: workflow de aprovação de empréstimo em 7 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.markAsPaid(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;
  }

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

    this.status = "paid";
    this.externalTransactionId = externalTransactionId;
    this.events.push(OrderPaid.from(this));
  }

  markAsRefunded(reason) {
    if (this.status !== "paid") {
      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 MarkOrderAsPaid(event.orderId, paymentResult.transactionId),
    );
  }
}

Pontos importantes sobre saga:

Sobre 2PC (two-phase commit): existe, mas raramente é a resposta. Acopla a disponibilidade do sistema à do recurso mais lento, exige coordenador transacional ativo, e os bancos modernos não recomendam para fluxos novos. Quando aparece a tentação, é sinal de que dois agregados deveriam ser um, ou que a regra deveria virar saga.

Quando duas escritas precisam acontecer mas vivem em agregados separados, a consistência entre elas vai ser eventual. Aceitar isso é mais barato do que fingir o contrário com 2PC ou lock distribuído.

A ferramenta que sustenta essa coordenação sem perder evento no caminho é o outbox. A regra é: na mesma transação que persiste o agregado, gravar o evento na tabela outbox. Um worker separado lê o outbox e publica no broker. Se o publish falhar, o evento fica no outbox para retry. Se o consumer falhar, ele recebe a mensagem de novo (at-least-once); a idempotência cobre.

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)],
      );
    }
  }
}

A consequência operacional da consistência eventual aparece na UI (User Interface, Interface de Usuário): logo após o POST /orders, o usuário pode ainda não ver os efeitos no Customer ou no estoque. Duas abordagens:

Em geral, modelar o estado intermediário no agregado (status = "processing" → "confirmed") deixa o sistema honesto. O usuário entende que o pedido foi aceito e o restante vai acontecer; a tela reflete a verdade do back.

ROLLBACK desfaz mudanças no banco; não desfaz efeito que saiu do banco. E-mail enviado, pagamento processado, notificação push disparada, vídeo gerado: nada disso volta com rollback. Quando o caso de uso passou de um agregado, ou passou pelo broker, a forma de desfazer é compensação semântica.

A regra prática: dentro de uma transação ACID, confiar no ROLLBACK para tudo. Fora dela, modelar a compensação como ação do domínio. "Cancelar pedido pago" não é "deletar o pedido"; é uma operação com nome próprio, regras próprias, eventual ação contra terceiros (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;
  }

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

    this.status = "paid";
    this.externalTransactionId = externalTransactionId;
    this.events.push(OrderPaid.from(this));
  }

  cancelDueToPaymentFailure(reason) {
    if (this.status !== "awaiting_payment") {
      throw new Error(`Cannot cancel paid 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, 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: lock segurado por minutos; deadlocks crescentes; relatórios sob SERIALIZABLE que disputam com escritas. Tratamento: fechar a transação no fim de cada passo curto; modelar o passo longo como saga.

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

Distributed 2PC. Tentativa de tornar atômica uma escrita em dois bancos ou banco + broker. Sintoma: discussão sobre coordenador transacional, XA, prepare/commit. Tratamento: outbox + idempotência. 2PC é solução para um problema que raramente é o problema certo.

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

Locking pessimista em hot path. SELECT ... FOR UPDATE em fluxo de alta concorrência onde o conflito é raro. Sintoma: fila no banco, usuários esperando, throughput cai. Tratamento: trocar por bloqueio otimista com version; retentar no caso de uso quando o conflito for esperado.

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

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

Cross-links dentro do guia:

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

Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.