Transactional Outbox — o evento que nunca aconteceu

Arquitetura · Sistemas distribuídos

O evento que nunca aconteceu

Seu save() foi commitado. Seu publish() falhou. Para o resto do sistema, aquele pagamento simplesmente não existe. Isso se chama dual-write (escrita dupla), e o Transactional Outbox (caixa de saída transacional) é a maneira mais comum de resolver.

TypeScript · NestJS · PostgreSQL · SQS/SNS

O bug que só aparece em produção

Todo backend que grava no banco e publica um evento tem essa linha em algum lugar:

o problemacreate-payment.use-case.ts

await this.repository.save(payment);   // ✅ commitado
await this.broker.publish(event);      // ❌ timeout

Funciona centenas de vezes por dia. Até o broker ficar dois segundos fora do ar. Aí o pagamento existe no seu banco, mas o serviço de ledger nunca ficou sabendo e a notificação nunca saiu. No dia seguinte, a conciliação acusa uma divergência e alguém passa a manhã tentando entender o que aconteceu.

Inverter a ordem não resolve — só troca o jeito de quebrar. Se você publicar primeiro e a transação der rollback, o evento já saiu falando de um pagamento que nunca foi gravado. Os consumidores vão processar algo que não existe.

A raiz do problema: não existe transação atômica entre um banco de dados e um message broker (intermediador de mensagens). São dois sistemas separados, cada um com o seu próprio commit. Não importa a ordem que você escolher: sempre vai existir um instante em que o primeiro já aconteceu e o segundo ainda não.

Antes de ir para a solução, vale descartar o que não funciona. Um try/catch em volta do publish não ajuda: se a publicação falhou, ela vai falhar de novo dentro do catch. Guardar o evento numa fila em memória para tentar mais tarde também não, porque essa fila desaparece quando o processo reinicia. E transação distribuída (2PC/XA) entre Postgres e SQS nem é suportada.

A ideia central

Se você não consegue escrever nos dois sistemas de forma atômica, escreva em um só. Em vez de publicar o evento, grave-o numa tabela outbox na mesma transação que salva o estado. A partir daí, ou os dois existem, ou nenhum dos dois existe — e quem garante isso é o banco, não o seu código.

A publicação vira um segundo passo, separado e que pode ser repetido: um processo — o relay (retransmissor) — lê as linhas pendentes e publica no broker. Se falhar, ele tenta de novo na próxima rodada. A linha continua lá, esperando.

O estado e o evento são gravados no mesmo commit. A publicação vira um passo separado, que pode ser repetido até dar certo.

A escrita atômica

O agregado registra o que aconteceu. O repositório recolhe esses eventos e grava no outbox, junto com o estado. Repare que o agregado nunca publica nada — ele nem sabe que existe um broker.

escrita atômicaadapters/typeorm-payment.repository.ts

@Injectable()
export class TypeOrmPaymentRepository implements PaymentRepository {
  constructor(private readonly dataSource: DataSource) {}

  async save(payment: Payment): Promise<void> {
    await this.dataSource.transaction(async (tx) => {
      await tx.save(PaymentModel, toModel(payment));

      for (const event of payment.pullEvents()) {
        await tx.insert(OutboxModel, {
          id: randomUUID(),      // vira o messageId → chave de dedupe
          type: event.type,        // 'payment.created'
          aggregateId: payment.id,
          payload: event.payload,
          status: 'PENDING',
        });
      }
    });
  }
}

A tabela é deliberadamente simples:

Coluna	Por quê
`id`	UUID. Vira o `messageId` publicado — é a chave que o consumidor usa para deduplicar.
`type`	O nome do evento de integração. Roteamento e observabilidade dependem disso.
`aggregate_id`	Liga o evento ao agregado que o gerou. Quando algo dá errado, é por aqui que você investiga.
`payload`	`jsonb`. É um contrato versionado para quem consome — não jogue a entidade inteira aqui.
`status`	`PENDING → PUBLISHED`. Índice em `(status, created_at)`.

O relay

Um poller (processo que consulta a tabela de tempos em tempos) lê as linhas pendentes e publica. O detalhe que permite rodar várias réplicas é o FOR UPDATE SKIP LOCKED: sem ele, duas réplicas disputam as mesmas linhas e uma fica parada esperando a outra. Com ele, cada réplica pega um lote diferente e segue em frente.

relay · pollerinfrastructure/outbox/outbox-relay.ts

@Injectable()
export class OutboxRelay {
  constructor(
    private readonly dataSource: DataSource,
    private readonly sns: SnsPublisher,
  ) {}

  @Interval(2000)
  async flush(): Promise<void> {
    await this.dataSource.transaction(async (tx) => {
      // concorrência segura entre réplicas do relay
      const batch = await tx.query(
        `SELECT * FROM outbox WHERE status = 'PENDING'
         ORDER BY created_at FOR UPDATE SKIP LOCKED LIMIT 100`,
      );

      for (const row of batch) {
        await this.sns.publish(row.type, row.payload, { messageId: row.id });
        await tx.update(OutboxModel, row.id, { status: 'PUBLISHED' });
      }
    });
  }
}

Duas decisões pequenas aqui têm consequências grandes.

A primeira: nunca apague a linha antes do ACK do broker (a confirmação de que ele recebeu). Marque como PUBLISHED e deixe a limpeza para um job separado. Se você apagar antes, uma falha na publicação vira perda de evento.

A segunda: se esperar dois segundos for demais para o seu caso, dá para usar LISTEN/NOTIFY do Postgres, que avisa o relay assim que a linha é inserida. O poller continua rodando como rede de segurança.

At-least-once (ao menos uma vez) não é um defeito

A garantia de que toda mensagem vai ser entregue — em troca de aceitar que algumas cheguem repetidas. O contrário de at-most-once (no máximo uma vez), onde nada chega duplicado, mas alguma coisa pode se perder no caminho.

Essa é a parte que costuma incomodar quem implementa o padrão pela primeira vez. Se o relay publica a mensagem e morre antes de marcar a linha como PUBLISHED, na próxima rodada ele vai publicar de novo. O evento sai duas vezes.

A tentação é tentar consertar isso. Não vale a pena: exactly-once (exatamente uma vez) não é possível nessa fronteira. Toda tentativa de simular isso acrescenta complexidade sem fechar a janela de falha. O caminho que funciona é aceitar o at-least-once e passar a responsabilidade para o outro lado: o consumidor precisa ser idempotente.

Em fintech isso não é detalhe. A diferença entre processar uma mensagem uma vez e processá-la duas é a diferença entre um pagamento e um pagamento em dobro. Idempotência não é polimento — é requisito.

Camada 1 — dedupe na borda

A ideia é reservar o messageId de forma atômica. Se ele já estava reservado, a mensagem é duplicata: não faça nada e dê o ACK.

consumer idempotenteuse-cases/on-payment-created.consumer.ts

@Injectable()
export class OnPaymentCreatedConsumer {
  constructor(
    private readonly idempotency: IdempotencyStore,
    private readonly ledger: PostEntryUseCase,
  ) {}

  @SqsMessageHandler('ledger-queue')
  async handle(message: SqsMessage): Promise<void> {
    const { messageId, payload } = parse(message);

    // claim atômico. false = já visto → no-op
    const firstTime = await this.idempotency.claim(messageId, { ttl: '24h' });
    if (!firstTime) return;

    await this.ledger.execute({
      paymentId: payload.aggregateId,
      amount: payload.amountCents,
    });
  }
}

Existem duas formas de implementar esse claim. Redis com SETNX e TTL é rápido, mas é mais um sistema que pode cair — e o TTL pode expirar antes da hora. Uma tabela processed_messages com UNIQUE em message_id é mais segura, porque participa da mesma transação da escrita de negócio. Isso fecha uma brecha que a versão com Redis deixa aberta.

Camada 2 — a operação em si é idempotente

O TTL expira, o Redis cai, a chave se perde. Por isso, vale escrever de um jeito que repetir não cause estrago — mesmo que a camada 1 falhe:

UPSERT por chave de negócio (insere ou atualiza, conforme já exista), em vez de INSERT cego.
Transições condicionais: UPDATE ... WHERE status = 'PENDING' — um replay afeta zero linhas.
Nunca balance = balance + x sem guarda. Registre uma entrada de ledger com o messageId e deixe a constraint rejeitar a duplicata.

A camada 1 é a otimização: resolve o caso comum de forma barata. A camada 2 é a garantia de que está correto. Confiar só numa delas é contar com a sorte.

O outro lado: o Inbox Pattern

Inbox pattern (caixa de entrada transacional) — o mesmo princípio do outbox, só que do lado de quem recebe: em vez de gravar o evento antes de publicar, você grava a mensagem que chegou antes de processar.

Repare na simetria. No outbox, você grava no banco e depois publica. No inbox, você recebe do broker, grava no banco e só então dá o ACK. Nos dois casos vale a mesma regra: primeiro o que é durável, por último a conversa com o sistema externo. Se o ACK se perder no caminho, o broker entrega de novo — e a duplicata esbarra na chave que já está gravada.

Aqui vale uma distinção que costuma passar batido: a tabela processed_messages da camada 1 não é um inbox completo. Ela guarda só o identificador, para conseguir descartar repetições. Um inbox de verdade guarda a mensagem inteira — payload, tipo, metadados. É isso que permite fazer algo que a deduplicação sozinha não faz: aceitar rápido agora e processar depois.

inbox · tabelamigrations/create-inbox.sql

CREATE TABLE inbox_messages (
  id                UUID PRIMARY KEY,        -- = messageId; a PK é a idempotência
  type              VARCHAR(255) NOT NULL,
  payload           JSONB NOT NULL,
  received_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  processed_at      TIMESTAMPTZ NULL,        -- NULL = ainda não processada
  error             TEXT NULL
);

-- índice parcial: só as pendentes entram, então ele fica pequeno
CREATE INDEX idx_inbox_pending
  ON inbox_messages (received_at)
  WHERE processed_at IS NULL;

O consumidor faz o insert idempotente e a escrita de negócio na mesma transação, e só confirma o broker depois do commit:

consumer com inboxuse-cases/on-payment-created.consumer.ts

@SqsMessageHandler('ledger-queue')
async handle(message: SqsMessage): Promise<void> {
  const { messageId, type, payload } = parse(message);

  await this.dataSource.transaction(async (tx) => {
    // ON CONFLICT DO NOTHING → duplicata não gera efeito nenhum
    const inserted = await tx.query(
      `INSERT INTO inbox_messages (id, type, payload)
       VALUES ($1, $2, $3) ON CONFLICT (id) DO NOTHING RETURNING id`,
      [messageId, type, payload],
    );
    if (inserted.length === 0) return;   // já processada antes

    await this.ledger.execute(payload, tx);  // mesma transação
  });

  // ACK só depois do commit. Crash aqui = reentrega, absorvida pelo insert acima.
}

A regra de ouro: confirme o broker depois do commit, nunca antes. Se você desse o ACK primeiro e o processo caísse em seguida, a mensagem estaria perdida: o broker já descartou e o banco nunca gravou. Fazendo o commit antes, o pior que acontece é a mensagem chegar de novo.

Quando o inbox se paga

O inbox custa uma tabela, uma rotina de limpeza e, na versão assíncrona, mais um processo para operar. Ele compensa quando:

o processamento é caro ou demorado, e segurar a mensagem na fila enquanto isso acontece é arriscado;
ele depende de terceiros instáveis — aceitar rápido e tentar de novo internamente absorve a indisponibilidade deles;
você precisa de um registro auditável do que chegou, não só do que foi aplicado.

Fora esses casos, a camada 1 (processed_messages) já resolve, e sai bem mais barato. E se a operação já for idempotente por natureza — um UPSERT, ou gravar um valor absoluto em vez de somar — provavelmente você não precisa de nenhum dos dois.

Um detalhe que morde: o tempo que você guarda os registros do inbox precisa ser maior que a janela máxima de reentrega do broker. Se a limpeza roda a cada 24 h e uma mensagem volta no terceiro dia, ela vai parecer nova e ser processada de novo. Pelo mesmo motivo, a deduplicação do SQS FIFO não serve como substituta: a janela dela é de 5 minutos, e a própria AWS avisa que reenvios depois desse intervalo não são detectados como duplicata.

Juntando as duas pontas: o outbox garante que a mensagem seja enviada pelo menos uma vez e o inbox garante que ela seja processada exatamente uma vez. É essa combinação que dá a troca confiável entre serviços — não uma promessa de exactly-once no transporte, que ninguém consegue cumprir.

O que monitorar

A pior falha do outbox é silenciosa: o relay morre, as linhas se acumulam em PENDING e tudo parece normal. As APIs respondem, o banco está saudável, não aparece nenhum erro nos logs. Só que nenhum evento está saindo.

Por isso, monitore a idade da linha pendente mais antiga, não a quantidade de linhas. Cem linhas pendentes criadas há dois segundos são operação normal; uma única linha parada há quinze minutos é incidente.

Vale também criar um alarme para quando a DLQ (dead-letter queue, a fila para onde vão as mensagens que falharam muitas vezes) tiver qualquer mensagem, e deixar escrito o plano de redrive (reprocessar as mensagens da DLQ) antes de precisar dele.

Quando não usar

O outbox tem um custo: uma tabela a mais, um processo a mais para operar e a exigência de que todo consumidor seja idempotente. Como não é de graça, não saia aplicando por reflexo.

Se todas as escritas cabem em uma transação no mesmo banco, use uma transação e pronto. Não crie um problema distribuído onde não existe um.
Se a perda ocasional de um evento é tolerável (métrica, analytics — dados analíticos, cache warming — pré-aquecimento de cache), o custo provavelmente não se paga.
Se você já usa CDC (change data capture, captura de alterações do banco) — o Debezium lendo o WAL (o log de escrita do Postgres) —, dá para gerar os eventos direto do log de replicação. Você escreve menos código, mas opera mais infraestrutura. E tem um efeito colateral: os eventos passam a refletir o seu schema interno, que é exatamente o que o outbox evita ao publicar um contrato explícito.

Ele se paga onde perder um evento tem consequência contábil ou regulatória: pagamentos, emissão, movimentação de saldo. Nesses casos, "o evento não saiu" deixa de ser um bug de sistema e vira uma divergência que alguém vai ter que explicar.

Resumo

Não existe commit atômico entre banco e broker. Qualquer sequência de duas escritas tem uma janela de falha.
Grave o evento na mesma transação do estado. Publicar vira um passo separado, que pode ser repetido.
FOR UPDATE SKIP LOCKED é o que permite rodar várias réplicas do relay ao mesmo tempo.
Marque como PUBLISHED. Nunca apague antes do ACK.
At-least-once é a garantia real que você tem. Idempotência no consumidor, em duas camadas, é obrigatória.
O inbox é o mesmo princípio do lado de quem recebe: grave a mensagem, depois dê o ACK. Outbox garante o envio pelo menos uma vez; inbox garante o processamento exatamente uma vez.
Monitore a idade da linha pendente mais antiga — aqui a falha é silenciosa.

Referências

O padrão é bem documentado. Se quiser ir além do que cobri aqui, estes são os melhores pontos de partida:

Definição canônica

Pattern: Transactional outbox — Chris Richardson, microservices.io. A formulação de referência do padrão, dentro do catálogo de transactional messaging. É daqui que o nome vem.
Pattern: Transaction log tailing — o padrão irmão: em vez de um poller lendo a tabela, um processo lê o log de transações do banco. É a base conceitual da abordagem via CDC.
Microservices Patterns (Chris Richardson, Manning) — capítulo 3 trata de mensageria transacional com mais profundidade do que qualquer artigo online.

Implementação e infraestrutura

Padrão de caixa de saída transacional — AWS Prescriptive Guidance (em português). Traz os diagramas de sequência de cada modo de falha e compara as duas abordagens: tabela de outbox com RDS versus CDC com DynamoDB Streams. Código de exemplo em aws-samples/transactional-outbox-pattern.
Outbox Event Router — documentação do Debezium. Se você for pelo caminho do CDC, é este SMT que transforma as linhas da tabela em mensagens roteadas por agregado.
Reliable Microservices Data Exchange with the Outbox Pattern — Gunnar Morling, blog do Debezium. O artigo que popularizou a combinação outbox + CDC.

Garantias de entrega e idempotência

Outbox, Inbox patterns and delivery guarantees explained — Oskar Dudycz. A fonte mais clara sobre o inbox como espelho do outbox, e sobre por que exactly-once não é alcançável na entrega mas é no processamento — que é o ponto das seções de idempotência e inbox deste post.
Pattern: Idempotent Consumer — Chris Richardson. A formalização do consumidor idempotente, incluindo a variante com tabela de mensagens processadas e a de guardar o maior ID visto por agregado.
Idempotency Patterns — Jonathan Oliver. O argumento de que, se a operação já é naturalmente idempotente, boa parte dessa maquinaria é dispensável.
Understanding the Dual-Write Problem and Its Solutions — Confluent. Bom panorama do problema e das alternativas, com viés para Kafka.
Amazon SQS standard queues e FIFO queue and message identifiers — a documentação que define, na prática, as garantias com as quais você vai trabalhar: at-least-once com possível reordenação nas filas padrão; ordenação e deduplicação (com a janela de 5 minutos) nas FIFO.

Padrões adjacentes

Padrão de orquestração da saga — AWS Prescriptive Guidance. Quando a transação atravessa serviços, o outbox resolve a publicação; a saga resolve a consistência.
What do you mean by “Event-Driven”? — Martin Fowler. Útil para separar event notification de event-carried state transfer — uma distinção que decide quanto dado vai no seu payload.
PostgreSQL: The Locking Clause — a documentação de FOR UPDATE / SKIP LOCKED, o mecanismo que sustenta o relay concorrente.

>_ undercoders

O evento que nunca aconteceu: Transactional Outbox na prática

Comentários