Outbox Pattern

Gravar no banco e publicar no broker são duas operações: o processo cai entre elas e o evento some. No Outbox o evento entra numa tabela outbox_messages na mesma transação do dado de negócio, e um relay separado o publica depois. Aqui o relay é acordado por LISTEN/NOTIFY no commit, com polling lento só como rede de segurança.

passos: 6
arquivos: 7
teste: 1
tecnologias: 5

Infraestrutura realTypeScriptBunPostgreSQLRedisDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Banco digital liquida TEDs e precisa avisar o antifraude de cada uma. Liquidar e publicar separadamente perde o aviso quando o processo cai no meio — e uma TED sem triagem de fraude é inaceitável. O aviso também não pode esperar segundos de polling.

Planta

Sequência

7/7

7 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

6 passos

Publicação confiável a partir do banco.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

SET NX+3

pg_notify+2

publishing+1

Outbox Pattern

claimed_at+1

Outbox Pattern

eventId+1

Outbox Pattern

01
transferSettle grava a TED e o evento transfer.settled na outbox na mesma transação; falhou, somem os dois
02
O trigger faz pg_notify no insert da outbox; o NOTIFY só é entregue se a transação commitar
03
O relay escuta numa conexão dedicada, esvazia a outbox a cada aviso e, sem aviso, confere no polling de fallback
04
O claim grava publishing e claimed_at com SKIP LOCKED: vários relays pegam lotes disjuntos
05
Relay que morre após o claim deixa a linha em publishing; o reaper a devolve a pending após o lease
06
Entrega é at-least-onceO antifraude deduplica pelo eventId com SET NX

Trade-offs

O que se ganha, o que se paga

3 vantagenscada ganho tem um preço3 custos

Vantagens

Evento nunca se perde: atomicidade do próprio banco
NOTIFY publica em milissegundos sem polling agressivo
Sem dependência além do banco e do broker

Custos

Entrega at-least-once: consumidor idempotente obrigatório
Conexão dedicada por relay para o LISTEN
Tabela da outbox exige limpeza de published

apps/data-patterns/outbox-pattern

7 arquivos

sql/

01_schema.sqlschematransfers, outbox_messages e o trigger de NOTIFY

src/

service_transfer.tsTED e evento na mesma transação
relay_outbox.tsClaim, publicação, reaper e laço acordado por NOTIFY
consumer_fraud.tsConsumer group com deduplicação por eventId
demo.tsdemoTEDs publicadas logo após o commit
relay_outbox.test.tstesteAtomicidade, NOTIFY, lease, SKIP LOCKED e duplicata contra PostgreSQL e Redis reais