CQRS Pattern

Command Query Responsibility Segregation: o modelo de escrita (normalizado, append-only) fica separado do modelo de leitura (desnormalizado, pré-calculado). As regras de negócio são validadas na escrita; a leitura responde sem agregação em tempo de consulta. Use quando leitura e escrita têm formas e cargas muito diferentes.

passos: 6
arquivos: 10
testes: 2
tecnologias: 5

Infraestrutura realTypeScriptBunPostgreSQLRedisDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um banco digital abre duas contas, faz depósitos e saques. Um saque acima do saldo é recusado no lado da escrita. O extrato resumido e o ranking de contas de alto saldo vêm do Redis, atualizado de forma assíncrona. No fim, o lado de leitura é apagado e reconstruído só com o replay do log de eventos.

Como funciona

6 passos

Separa modelo de escrita e de leitura.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

COMMIT+5

pg_notify+2

01
Command sideaccountCommandHandle relê o stream da conta, valida (conta aberta, valor positivo, saldo suficiente) e grava o evento com versão + 1
02
Concorrência otimistaUNIQUE (account_id, version) deixa entrar só um de dois comandos decididos sobre a mesma versão; o outro recebe ErrorAccountConflict
03
Sincronização assíncronapg_notify na mesma transação — o aviso só sai no COMMIT; o projector escuta em processo próprio
04
Projeção idempotenteO projector refaz o modelo a partir do stream inteiro e um script Lua grava só se a versão for mais nova — aviso perdido, repetido ou atrasado não deixa o modelo errado
05
Query sideDetalhes por hash e ranking por saldo num sorted set — sem KEYS, sem agregação na consulta
06
ReconstruçãoO read model nunca é fonte de verdade; o projector refaz tudo por replay na partida

apps/patterns/cqrs-pattern

10 arquivos

sql/

01_schema.sqlschemaTabela account_events com versão única por conta

src/

command_account.tsCommand side: regras, append e pg_notify
projection_account.tsProjeção pura do stream no read model
projector_account.tsProcesso que escuta o canal e grava no Redis com guarda de versão
query_account.tsQuery side: detalhes e ranking por saldo
config_account.tsLê e valida o ambiente no boot
command_account.test.tstesteIntegração contra PostgreSQL e Redis reais
projection_account.test.tstesteProjeção pura e reprodutível
demo.tsdemoComandos, consultas e reconstrução do lado de leitura

./

docker-compose.ymlinfraPostgreSQL (escrita) e Redis (leitura)

Executar · com Docker

$ docker compose up -d# sobe PostgreSQL · Redis
$ cp .env.example .env# variáveis de ambiente
$ bun install# dependências
$ bun run demo# roda o cenário
$

Testes: bun run test.

Requisitos: BunDocker
Sobe junto: PostgreSQLRedis

Por que se relacionam

Vem antes

Snapshot PatternProjeções separadas para leitura.

Próximo passo

Materialized ViewLeitura pré-calculada.

Combina com

Teste rápido

Qual é o próximo passo depois de CQRS?

Próximo projeto · Padrões FundamentaisDead-Letter Queue

Contatos

CQRS Pattern