CS Fundamentals Trainer · Guias

Event sourcing e CQRS

Armazenar fatos em vez de estado: o event store, concorrência otimista, replay e snapshots, read models e projetores, consistência eventual, design de eventos e upcasting, e quando não vale a pena.

40 min de leitura

A maioria das aplicações armazena o estado atual: uma linha por conta guardando o saldo, sobrescrita a cada mudança. É simples, e joga informação fora. Você vê que o saldo é 20, mas não que era 100 um minuto atrás, quem o mudou ou por quê. O event sourcing guarda o histórico: o sistema armazena cada mudança como um evento imutável ("depositou 100", "sacou 80"), e o estado atual é derivado ao reproduzi-los. O CQRS (command query responsibility segregation) vem naturalmente junto: separar o modelo que decide e altera as coisas dos modelos que respondem a consultas.

Ambos são poderosos, amplamente mal aplicados e muitas vezes descritos por slogans vagos. Neste guia construí um pequeno event store sobre SQLite e medi o que replay, snapshots, controle de concorrência e projeções de read models realmente fazem (código no apêndice). Ele se conecta a filas de mensagens e sagas para integração, a microsserviços para a arquitetura em volta, e às ideias estruturadas em log dos motores de armazenamento e do consenso, onde um log replicado também é o coração do sistema.

1. Estado ou eventos?

Tome uma conta bancária. Com armazenamento de estado, a tabela tem uma linha:

contasaldo
A20

Com event sourcing, a tabela guarda o que aconteceu, em ordem, e nada é atualizado nem apagado:

streamversãoevento
conta A1Opened
conta A2Deposited 100
conta A3Withdrew 80

O saldo, 20, é um fold sobre os eventos: comece com nada, aplique cada evento em ordem. O log é a fonte da verdade; o saldo é uma visão dele que sempre pode ser recalculada.

Por que você faria isso?

E o preço, que este guia também detalha: complexidade, consistência eventual no lado de leitura, uma evolução de schema que nunca acaba e o fato de que a maioria das aplicações não precisa de nenhum dos benefícios acima.

2. O event store

Um event store é um log só de acréscimo (append-only) com algumas regras estritas:

Diagram: The write side: commands become events

Um comando é um pedido para fazer algo e pode ser recusado ("sacar 200"); um evento é um fato que já aconteceu e não pode ser recusado ("sacou 80"). O handler carrega o stream, reconstrói o estado, verifica as regras de negócio e, se valerem, acrescenta os novos eventos. Dê nomes aos eventos no passado, na linguagem do negócio (OrderPlaced, AddressChanged), não como mudanças de tabela (OrderRowUpdated): o significado é o valor.

Concorrência otimista

E se dois comandos para a mesma conta rodarem ao mesmo tempo? Cada um carrega o stream, vê um saldo de 100 e decide que sacar 80 é permitido. Sem proteção, os dois acrescentariam, e o saldo seria -60. O store evita isso com uma versão esperada: o append diz "adicione este evento se o stream ainda estiver na versão 2". Executei isso com duas threads:

ClienteResultado
escritor 1aceito (o stream vai para a versão 3)
escritor 2conflito: o stream está na versão 3, esperava-se 2

O saldo final foi 20, não -60. O perdedor recarrega o stream, vê o novo saldo de 20 e agora rejeita corretamente o saque (ou tenta de novo, se o comando ainda fizer sentido). Isso é controle de concorrência otimista: sem locks, um conflito é detectado na hora da escrita, e a restrição única (stream, version) faz isso valer mesmo sob corridas. A fronteira de consistência é o stream: as invariantes devem ser impostas dentro de um aggregate, e é por isso que os aggregates devem ser pequenos (uma conta, um pedido) e não "o banco de clientes inteiro". Regras que atravessam aggregates precisam de sagas e consistência eventual (o guia de transações distribuídas).

3. Reconstruindo o estado e os snapshots

Para reconstruir uma conta, você lê seus eventos e os aplica em ordem. Percorra o processo e depois ligue o snapshot:

Interactive animation: event replay

Reproduzir é barato para um stream com dez eventos e caro para um com milhões. Medi isso para um fold em Python sobre eventos no SQLite:

Eventos no streamReplay completoReplay a partir de um snapshot tirado 100 eventos antes do fim
1000,4 ms0,3 ms
10 000cerca de 22 ms0,25 ms (100 eventos lidos)
1 000 000cerca de 2,4 a 2,7 s0,4 ms (100 eventos lidos)

Um snapshot é uma cópia salva do estado em alguma versão. Para carregar o aggregate, leia o último snapshot e reproduza apenas os eventos depois dele. O custo de carregar torna-se constante, e é por isso que os snapshots são a resposta padrão quando os streams ficam longos. Duas ressalvas: os eventos continuam sendo a fonte da verdade (um snapshot é um cache e pode ser descartado e reconstruído), e um snapshot é escrito em uma forma do estado, então, quando você muda a classe de estado, precisa invalidar ou migrar os snapshots antigos. Muitas vezes você nem precisa de snapshots: os streams por entidade costumam ser curtos, e um stream que cresce sem limite é sinal de que o aggregate é grande demais (feche os livros e comece um novo stream, por exemplo um por mês para uma conta).

4. CQRS: modelos separados para escrever e ler

O event sourcing deixa o lado de escrita excelente em decidir e fraco em responder perguntas: "todas as contas com saldo acima de 1 000" exigiria reproduzir todos os streams. Então você constrói read models (projeções): tabelas ou índices moldados para as consultas de que precisa, mantidos atualizados por um projetor que assina os eventos. Essa separação é o CQRS.

Diagram: CQRS with event sourcing

Cada read model pode usar a tecnologia que lhe convém: uma tabela relacional, um índice de busca (veja busca e indexação de texto completo), um cache, um grafo. Você pode adicionar um novo a qualquer momento e construí-lo a partir do histórico.

Um projetor, construído com cuidado

Um projetor lê eventos a partir de um checkpoint (a última posição global que tratou), os aplica ao read model e grava o novo checkpoint. O detalhe que importa é que a mudança do read model e o avanço do checkpoint acontecem na mesma transação, de modo que uma queda não possa aplicar um evento duas vezes nem pular um. Escrevi um que mantém uma tabela de pedidos por cliente:

Essa reconstrução é um grande benefício: um bug em uma projeção é corrigido corrigindo o código e reproduzindo, não reparando dados à mão. Para um histórico grande, as reconstruções levam tempo, então as equipes constroem a nova versão de um read model ao lado da antiga, trocam as consultas quando ela alcança e descartam a antiga.

Consistência eventual

O read model é atualizado depois de o evento ser confirmado, então por um momento uma consulta pode devolver dados antigos. O quanto ele fica obsoleto depende de como o projetor recebe seus eventos. Um modelo simples, em que o projetor consulta a cada intervalo e precisa de 5 ms para processar um lote, dá:

Intervalo de pollingObsolescência medianaPercentil 99
10 ms10 ms15 ms
100 ms55 ms104 ms
1 000 ms502 ms995 ms

Assinar uma notificação push em vez de fazer polling reduz isso ao tempo de processamento mais a rede, normalmente milissegundos, mas nunca zero. As consequências precisam ser incorporadas ao design:

O CQRS sem event sourcing é comum e muitas vezes suficiente: um banco de escrita normalizado mais tabelas de leitura desnormalizadas, views materializadas ou um índice de busca alimentado por captura de dados de mudança. O event sourcing sem CQRS raramente é prático, por causa do problema de consulta acima.

4.1 Rodando projetores em produção: quedas, eventos venenosos e reconstruções

Um projetor é um programinha que precisa rodar por anos, e os problemas interessantes não estão no caminho feliz. Testei quatro deles em um event store em SQLite (script no apêndice; conjuntos de dados pequenos, então leia as proporções e os modos de falha, não os milissegundos).

Recuperação depois de uma queda. Um projetor lê um lote, atualiza o modelo de leitura e registra até onde chegou (o checkpoint). Se ele morre entre as duas coisas, uma reinicialização relê o lote. Com incrementos como balance = balance + amount, aplicar o lote duas vezes conta em dobro. Injetei uma queda com probabilidade de 4% por lote em 300 execuções sobre 2.000 eventos; 163 execuções tiveram pelo menos uma queda:

ProjetoExecuções com quedaExecuções que terminaram com um modelo de leitura errado
modelo de leitura confirmado e, depois, o checkpoint gravado separadamente163163
modelo de leitura e checkpoint em uma só transação1630

Se o modelo de leitura está no mesmo banco que o checkpoint, use uma só transação. Se não está (um índice de busca, outro armazenamento), torne cada atualização idempotente (defina um valor calculado a partir do evento, ou guarde a posição do evento na linha e ignore tudo que não for mais novo) para que reaplicar um lote não mude nada.

Um evento venenoso (poison event) é um que o projetor não consegue processar: dados malformados, um tipo desconhecido, um bug. Passei 5.000 eventos por um projetor com um evento na posição 2.500 que tinha texto ("142 EUR") onde se esperava um número:

EstratégiaO que aconteceu
parar no erroparou no evento 2.500; os outros 2.501 eventos (50%) nunca chegaram ao modelo de leitura, e todas as 50 contas ficaram desatualizadas ou erradas
pular em silêncio4.999 aplicados; uma conta permanentemente errada, e nada avisa
tentar três vezes e depois estacionar o evento e o seu stream em uma tabela de dead-letter e seguir em frente4.932 aplicados; 68 eventos estacionados (o evento venenoso e todos os eventos seguintes daquela conta, para manter a ordem dos eventos dela); as outras 49 contas continuam atualizadas; um alerta dispara

Depois de corrigir a causa (aqui, um upcaster que lê "142 EUR" como 142) e reenviar em ordem os 68 eventos estacionados, 0 de 50 saldos estavam errados. O padrão é: tentar de novo para erros transitórios, pôr em quarentena no menor escopo que preserve a ordem (o stream, não o log inteiro), alertar sobre a contagem de dead-letter, guardar a carga que falhou para diagnóstico e reenviar depois da correção. Parar só é a escolha certa quando a ordem entre streams importa ou quando você prefere ficar fora do ar a ficar errado. Pular em silêncio quase nunca está certo. Previna eventos venenosos na origem, validando os eventos quando são escritos e testando toda versão armazenada de todo tipo de evento (próxima seção).

Reconstruindo um modelo de leitura sem atrapalhar a produção. Você reconstrói quando muda uma projeção, corrige um bug ou acrescenta uma nova visão. O jeito ingênuo é esvaziar a tabela e reprocessar. Fiz isso com 150.000 eventos enquanto um leitor consultava o total a cada poucos milissegundos:

ReconstruçãoTempoLeituras que devolveram um total errado
no lugar: apagar as linhas e depois reprocessar1,0 s407 de 407 (100%)
lado a lado: reprocessar para uma nova tabela balances_v2 e depois trocar os nomes em uma transação1,0 s0 de 449

A reconstrução ingênua mostra dados parciais aos usuários enquanto dura; com um log real (horas de reprocessamento), isso é uma queda. O procedimento seguro é o azul/verde (blue/green): (1) construa o novo modelo de leitura ao lado do antigo, a partir da posição 0, enquanto o antigo continua atendendo; (2) deixe o projetor ao vivo alimentar os dois, ou alcance a partir da última posição até o atraso ser de poucos eventos; (3) compare os dois onde deveriam concordar (contagens de linhas, checksums, uma amostra de consultas); (4) troque os leitores em um passo atômico (renomear, uma view ou um alias, uma feature flag), sob um bloqueio de escrita curto para que nenhum evento caia entre alcançar e trocar; (5) guarde o antigo por um tempo para rollback e depois descarte-o. O script mede os passos 1 e 4; os passos 2, 3 e 5 são o procedimento operacional e não foram medidos. Limite também a taxa do reprocessamento para que ele não sufoque o sistema em produção, e lembre que ele precisa de capacidade para ler o log inteiro.

5. Projetando eventos

Evolução de schema: upcasting

Você não pode reescrever o histórico, mas a forma dos eventos muda. A técnica comum é o upcasting: quando um evento antigo é lido, uma pequena função o converte para a forma atual. No meu teste, a versão 1 de Opened guardava o dono como uma string, a versão 2 como nome e sobrenome:

ArmazenadoLido como (forma atual)
schema 1: {"owner": "Ada Lovelace"}{"owner": {"first": "Ada", "last": "Lovelace"}}
schema 2: {"owner": {"first": "Grace", "last": "Hopper"}}inalterado

Regras: guarde uma versão de schema com cada evento; faça apenas mudanças aditivas sempre que possível; escreva upcasters para o resto; mantenha toda versão antiga testável. A alternativa, uma migração pontual que reescreve os eventos armazenados, é possível, mas derrota a ideia de um log imutável e é arriscada.

Evoluindo eventos e reprocessando depois de mudanças no código

O upcasting resolve o caso simples. As regras mais amplas, porque os eventos são guardados durante toda a vida do sistema e todo reprocessamento executa o código de hoje sobre os dados de ontem:

Jeitos de mudar um evento, do mais seguro ao mais disruptivo

MudançaComoObservações
acrescentar um campo opcionalos leitores usam um padrão quando ele falta ("leitor tolerante")sem migração; a mudança preferida
mudar o formato ou o significado de um campouma nova versão de schema mais um upcaster da antiga; encadeie-os (v1 para v2 para v3) para que qualquer versão armazenada chegue ao formato atualtoda versão antiga precisa continuar legível; mantenha um evento de exemplo de cada versão nos testes
o significado de negócio mudouum novo tipo de evento (AddressChanged contra AddressCorrected), nunca um significado alterado sob o nome antigoos eventos antigos mantêm o significado antigo para sempre
dividir ou juntar streams, ou reestruturar muitocopiar e transformar: ler o log antigo e escrever um novo no novo formato, rodar os dois até verificar, e então migrarum projeto, não uma edição; o log antigo é guardado como arquivo
reescrever eventos armazenados no lugarevite; se for inevitável, faça backup, faça como uma migração versionada e verifique reconstruindo o estado antes e depoisquebra a promessa de "histórico imutável" e qualquer cadeia de hashes

Reprocessando depois de uma mudança no código. O estado de um agregado é fold(apply, events). Isso só continua verdadeiro se apply for uma função pura do evento: sem relógio, sem números aleatórios, sem consultas a banco ou a serviços e sem decisões de negócio dentro dela. As decisões pertencem ao command handler, e o seu resultado é registrado no evento. Mostrei a diferença com uma taxa de saque. Quando a taxa era calculada dentro de apply, a 1%, o saldo era 444 quando os eventos aconteceram; o negócio mudou a regra para um valor fixo de 5, e um reprocessamento produziu 435: o histórico mudou em silêncio. Quando a taxa estava guardada em cada evento, o saldo continuou 444 depois da mudança da regra, e a nova regra valeu apenas para os novos comandos.

Regras relacionadas:

Dados pessoais e exclusão

A imutabilidade colide com o direito ao apagamento (LGPD, GDPR). Estratégias comuns: manter os dados pessoais fora dos eventos, guardando apenas um identificador e mantendo os dados em um armazenamento separado e apagável; ou usar o crypto-shredding: criptografar os dados de cada pessoa nos eventos com uma chave por pessoa e apagar a chave quando a pessoa pede para ser esquecida, deixando bytes ilegíveis. Planeje isso no começo; é muito difícil acrescentar depois.

Um log de eventos é uma trilha de auditoria?

É tentador dizer "guardamos toda mudança, então temos uma trilha de auditoria". Um log de eventos dá um bom começo, não algo que atenda sozinho a uma exigência legal ou regulatória. As lacunas:

O resumo honesto: o event sourcing torna barato um registro completo das mudanças de estado, o que ajuda uma auditoria. Fazer esse registro merecer confiança como prova exige evidência de adulteração, ancoragem, identidade e tempo confiáveis, registro de acessos e um acordo com quem audita você.

6. Integrando com o resto do sistema

Outros serviços querem reagir aos seus eventos. Duas regras mantêm isso confiável:

Um process manager ou saga escuta eventos e emite comandos para coordenar um processo de negócio de vários passos entre aggregates e serviços, com comandos compensatórios quando algo falha.

7. Quando usar e quando não

Bom encaixeMau encaixe
um domínio em que histórico, auditoria e o "porquê" importam: livros-razão, pedidos, estoque, sinistros, edição colaborativaCRUD simples, gerenciamento de conteúdo, telas de configurações
regras de negócio e fluxos complexos que se beneficiam de testes "dados eventos, quando comando, então eventos"relatórios e consultas ad hoc sobre o estado atual como necessidade principal
várias visões diferentes dos mesmos dados, construídas e reconstruídas ao longo do tempouma equipe pequena sem experiência, com pouco tempo e sem necessidade dos benefícios
necessidade de assinar o que aconteceu em vez de fazer pollingdados com forte necessidade de leitura imediata após a escrita em todo lugar

Alternativas mais baratas para parte do benefício: uma tabela de auditoria gravada na mesma transação da mudança, tabelas temporais (system-versioned tables) em alguns bancos de dados, ou captura de dados de mudança para transmitir mudanças de linhas a outros sistemas. Use event sourcing para um aggregate ou um bounded context que realmente precise, não para um sistema inteiro por padrão. Se usar, use um store comprovado (EventStoreDB, ou uma tabela append-only em um banco relacional com as restrições mostradas acima, ou um sistema de log como o Kafka para o lado da distribuição) e um framework que trate snapshots, projeções e upcasting, em vez de inventá-los.

8. Erros comuns

9. Coisas a mencionar em uma entrevista

Resumo rápido

Apêndice: o código dos experimentos

Um script Python 3 que usa apenas a biblioteca padrão (SQLite em memória). Ele constrói o event store com a restrição única em (stream, version), acrescenta com uma versão esperada, executa duas threads que sacam da mesma conta, reproduz streams de 100, 10 000 e 1 000 000 de eventos com e sem snapshot, executa um projetor com checkpoint e o reconstrói a partir do log, e mostra o upcasting. Os tempos de replay são medições reais em uma pequena máquina virtual e variam de execução para execução (os números do guia estão arredondados); a tabela de obsolescência é um cálculo a partir do intervalo de polling e de um tempo de lote de 5 ms, não uma medição de um sistema real. O SQLite roda aqui em um único processo, então o lock em volta do append representa a transação de banco de dados que um store real usaria; a restrição (stream, version) é o que garante a correção em um banco de dados real.

Um event store no SQLite: replay, snapshots, concorrência, um projetor e upcasting

import sqlite3, json, time, random, threading

# ---------- an append-only event store on SQLite, with optimistic concurrency per stream
db = sqlite3.connect(":memory:", check_same_thread=False, isolation_level=None)
db.execute("pragma journal_mode=off"); db.execute("pragma synchronous=off")
db.execute("""create table events(global_pos integer primary key autoincrement, stream text not null, version int not null,
              type text not null, data text not null, schema int not null default 1, unique(stream, version))""")
db.execute("create table snapshots(stream text primary key, version int, state text)")
lock = threading.Lock()

class Conflict(Exception): pass
def append(stream, expected_version, events):
    """Appends events only if the stream is still at expected_version (optimistic concurrency)."""
    with lock:
        try:
            db.execute("begin")
            v = db.execute("select coalesce(max(version), 0) from events where stream=?", (stream,)).fetchone()[0]
            if v != expected_version: raise Conflict(f"stream {stream} is at version {v}, expected {expected_version}")
            for i, (t, d) in enumerate(events): db.execute("insert into events(stream, version, type, data) values (?,?,?,?)", (stream, v + i + 1, t, json.dumps(d)))
            db.execute("commit"); return v + len(events)
        except Exception: db.execute("rollback"); raise

def apply(state, t, d):
    if t == "Opened": return {"balance": 0, "open": True}
    if t == "Deposited": return {**state, "balance": state["balance"] + d["amount"]}
    if t == "Withdrew": return {**state, "balance": state["balance"] - d["amount"]}
    return state
def load(stream, snapshot=True):
    state, v = {}, 0
    if snapshot:
        row = db.execute("select version, state from snapshots where stream=?", (stream,)).fetchone()
        if row: v, state = row[0], json.loads(row[1])
    n = 0
    for t, d, ver in db.execute("select type, data, version from events where stream=? and version>? order by version", (stream, v)):
        state = apply(state, t, json.loads(d)); v = ver; n += 1
    return state, v, n

# ---------- 1. cost of rebuilding state, with and without snapshots
rnd = random.Random(1)
def fill(stream, n):
    rows = [(stream, 1, "Opened", "{}")] + [(stream, i + 2, rnd.choice(["Deposited", "Withdrew"]), json.dumps({"amount": rnd.randint(1, 100)})) for i in range(n - 1)]
    db.execute("begin"); db.executemany("insert into events(stream, version, type, data) values (?,?,?,?)", rows); db.execute("commit")
print("rebuilding one account by replaying its events (Python fold, SQLite in memory):")
for n in (100, 10_000, 1_000_000):
    s = f"acct-{n}"; fill(s, n)
    t = time.perf_counter(); st, v, replayed = load(s, snapshot=False); full = time.perf_counter() - t
    # build a real snapshot 100 events before the end
    st2 = {}
    for t_, d_, ver in db.execute("select type, data, version from events where stream=? and version<=? order by version", (s, v - 100)): st2 = apply(st2, t_, json.loads(d_))
    db.execute("insert or replace into snapshots values (?,?,?)", (s, v - 100, json.dumps(st2)))
    t = time.perf_counter(); st3, v3, replayed3 = load(s, snapshot=True); snap = time.perf_counter() - t
    assert st3 == st
    print(f"  {n:>9,} events: full replay {full*1000:>9.1f} ms ({replayed:,} events read), from a snapshot {snap*1000:>6.2f} ms ({replayed3} events read)")

# ---------- 2. optimistic concurrency: two writers, one decision each
append("acct-A", 0, [("Opened", {}), ("Deposited", {"amount": 100})])
out = []
def withdraw(name, amount):
    state, v, _ = load("acct-A", snapshot=False)
    time.sleep(0.01)                                  # both read the state before either one writes
    if state["balance"] < amount: out.append((name, "rejected: insufficient funds")); return
    try: append("acct-A", v, [("Withdrew", {"amount": amount})]); out.append((name, "accepted"))
    except Conflict as e: out.append((name, f"conflict: {e}"))
ths = [threading.Thread(target=withdraw, args=(n, 80)) for n in ("writer 1", "writer 2")]
[t.start() for t in ths]; [t.join() for t in ths]
print("\ntwo clients withdraw 80 from a balance of 100 at the same moment:"); [print("  ", o) for o in sorted(out)]
print("   final balance:", load("acct-A", False)[0]["balance"])

# ---------- 3. a projection (read model) with a checkpoint, run in batches: how stale is it?
db.execute("create table orders_by_customer(customer text primary key, orders int, total int)")
db.execute("create table checkpoint(name text primary key, pos int)"); db.execute("insert into checkpoint values ('orders', 0)")
def project(batch=100):
    pos = db.execute("select pos from checkpoint where name='orders'").fetchone()[0]
    rows = db.execute("select global_pos, type, data from events where global_pos>? and type='OrderPlaced' order by global_pos limit ?", (pos, batch)).fetchall()
    last = pos
    db.execute("begin")
    for gp, t, d in rows:
        d = json.loads(d)
        db.execute("insert into orders_by_customer values (?,1,?) on conflict(customer) do update set orders=orders+1, total=total+excluded.total", (d["customer"], d["total"])); last = gp
    db.execute("update checkpoint set pos=? where name='orders'", (last,)); db.execute("commit")   # the read model and the checkpoint move together
    return len(rows)
for i in range(1000): append(f"order-{i}", 0, [("OrderPlaced", {"customer": f"c{i % 50}", "total": 10 + i % 7})])
while project(): pass
print("\nread model built from", db.execute("select count(*) from events where type='OrderPlaced'").fetchone()[0], "OrderPlaced events:", db.execute("select count(*), sum(orders), sum(total) from orders_by_customer").fetchone(), "(customers, orders, total)")
# the projection can be dropped and rebuilt from the log at any time, with the same result
before = db.execute("select * from orders_by_customer order by customer").fetchall()
db.execute("delete from orders_by_customer"); db.execute("update checkpoint set pos=0")
t = time.perf_counter(); n = 0
while True:
    k = project(500); n += k
    if not k: break
print(f"rebuilt from scratch in {1000*(time.perf_counter()-t):.0f} ms; identical to the original: {db.execute('select * from orders_by_customer order by customer').fetchall() == before}")
# replaying a batch twice must not change the result: the checkpoint and the data change in one transaction
pos = db.execute("select pos from checkpoint where name='orders'").fetchone()[0]
print("running the projector again with nothing new applies", project(), "events")

# staleness of the read model if the projector polls every `interval` ms and a write is committed at a random moment
rnd2 = random.Random(5)
print("\nread model staleness (time from commit to visible), projector polling every interval, 5 ms to process a batch:")
for interval in (10, 100, 1000):
    lags = sorted(rnd2.uniform(0, interval) + 5 for _ in range(100000))
    print(f"  poll every {interval:>4} ms: median {lags[50000]:.0f} ms, 99th percentile {lags[99000]:.0f} ms, worst {lags[-1]:.0f} ms")

# ---------- 4. schema evolution: events are forever, so old shapes must still be readable
db.execute("insert into events(stream, version, type, data, schema) values ('acct-B', 1, 'Opened', ?, 1)", (json.dumps({"owner": "Ada Lovelace"}),))
db.execute("insert into events(stream, version, type, data, schema) values ('acct-B', 2, 'Opened', ?, 2)", (json.dumps({"owner": {"first": "Grace", "last": "Hopper"}}),))
def upcast(t, d, schema):
    if t == "Opened" and schema == 1: first, _, last = d["owner"].partition(" "); return {"owner": {"first": first, "last": last}}
    return d
print("\nupcasting version 1 events to the current shape when they are read:")
for t, d, s in db.execute("select type, data, schema from events where stream='acct-B' order by version"): print("  schema", s, "->", upcast(t, json.loads(d), s))

# ---------- 5. the temporal query that a state table cannot answer
state = {}; 
print("\nbalance of acct-A after each event (a state table keeps only the last row):")
for t, d, v in db.execute("select type, data, version from events where stream='acct-A' order by version"):
    state = apply(state, t, json.loads(d)); print(f"  version {v}: {t:<10} balance {state['balance']}")

Operando um sistema com event sourcing: reprocessamento, eventos venenosos, quedas, reconstruções e cadeias de hashes

Python 3, apenas biblioteca padrão, SQLite em um arquivo temporário. Os tempos dependem da máquina.

"""Operating an event-sourced system: replay after code changes, poison events, projector crashes, rebuilding a read model while it is being read,
and what a hash chain can and cannot prove. SQLite and the standard library only; numbers are from one small machine."""
import hashlib, json, os, random, sqlite3, threading, time

DB = "/var/tmp/es_ops.db"
def fresh():
    for ext in ("", "-wal", "-shm"):
        try: os.remove(DB + ext)
        except FileNotFoundError: pass
    c = sqlite3.connect(DB, isolation_level=None); c.execute("pragma journal_mode=wal"); c.execute("pragma synchronous=off")
    c.execute("create table events(pos integer primary key autoincrement, stream text, type text, data text)")
    return c

def add(c, stream, type, **data): c.execute("insert into events(stream,type,data) values (?,?,?)", (stream, type, json.dumps(data)))

def workload(c, n_streams=200, n=20_000, seed=1):
    r = random.Random(seed); bal = {f"acct-{i}": 0 for i in range(n_streams)}
    c.execute("begin")
    for _ in range(n):
        s = r.choice(list(bal))
        if bal[s] < 50 or r.random() < .6: a = r.randrange(10, 200); add(c, s, "Deposited", amount=a); bal[s] += a
        else: a = r.randrange(1, min(bal[s], 150) + 1); add(c, s, "Withdrawn", amount=a); bal[s] -= a
    c.execute("commit"); return bal

# ---------------------------------------------------------------------------------------------------------------- A. replay after a code change
def part_a():
    print("A. Replay after the business rules change")
    events = [("Deposited", 1000), ("Withdrawn", 200), ("Withdrawn", 300), ("Deposited", 50), ("Withdrawn", 100)]
    fee_v1 = lambda amount: round(amount * 0.01)             # the rule when the events were written: 1 percent
    fee_v2 = lambda amount: 5                                # the rule after a change in the business: a flat 5
    def fold_fee_in_apply(fee):                              # BAD: the fee is computed inside `apply`, from today's code
        b = 0
        for t, a in events: b += a if t == "Deposited" else -(a + fee(a))
        return b
    live = fold_fee_in_apply(fee_v1); replayed = fold_fee_in_apply(fee_v2)
    print(f"   fee computed in apply:  balance when the events happened {live}, balance after replaying with the new rule {replayed}  -> history silently changed")
    stored = []                                              # GOOD: the decision (including the fee) is recorded in the event
    for t, a in events: stored.append((t, a, 0 if t == "Deposited" else fee_v1(a)))
    def fold_recorded(stored): return sum(a if t == "Deposited" else -(a + f) for t, a, f in stored)
    print(f"   fee recorded in the event: balance {fold_recorded(stored)} now, and after the new rule is deployed {fold_recorded(stored)} (the new rule only applies to new commands)")

# ---------------------------------------------------------------------------------------------------------------- B. poison events
def project(c, events, strategy, max_retries=3):
    """A projector that keeps `balances`. `events` come in order. Returns (balances, dead_letters, applied_count, halted_at)."""
    bal = {}; dead = []; quarantined = set(); applied = 0
    def apply(stream, t, d):
        a = d["amount"]
        if not isinstance(a, int): raise TypeError(f"bad amount {a!r}")
        bal[stream] = bal.get(stream, 0) + (a if t == "Deposited" else -a)
    for pos, stream, t, data in events:
        d = json.loads(data)
        if strategy == "dead-letter-per-stream" and stream in quarantined: dead.append((pos, stream, t, data)); continue   # keep the order of that stream
        for attempt in range(max_retries if strategy != "skip" else 1):
            try: apply(stream, t, d); applied += 1; break
            except Exception:
                if strategy == "halt": return bal, dead, applied, pos
        else:
            if strategy == "dead-letter-per-stream": dead.append((pos, stream, t, data)); quarantined.add(stream)
    return bal, dead, applied, None

def part_b():
    print("B. A poison event in the middle of the log")
    c = fresh(); truth = workload(c, n_streams=50, n=5_000); poison_pos = 2500
    row = c.execute("select stream, type, data from events where pos=?", (poison_pos,)).fetchone()
    true_amount = json.loads(row[2])["amount"]
    c.execute("update events set data=? where pos=?", (json.dumps({"amount": f"{true_amount} EUR"}), poison_pos))      # a bad producer wrote text instead of a number
    events = c.execute("select pos, stream, type, data from events order by pos").fetchall(); total = len(events)
    for strategy in ("halt", "skip", "dead-letter-per-stream"):
        bal, dead, applied, halted = project(c, events, strategy)
        wrong = sum(1 for s in truth if bal.get(s, 0) != truth[s])
        extra = f", halted at position {halted}: {total - applied} events ({100*(total-applied)/total:.0f}%) not visible" if halted else ""
        print(f"   {strategy:<22} applied {applied}/{total}, accounts with a wrong balance {wrong}/{len(truth)}, parked {len(dead)}{extra}")
    # the fix: an upcaster that understands the bad format, then re-drive the parked events in order
    bal, dead, applied, _ = project(c, events, "dead-letter-per-stream")
    fixed = []
    for pos, stream, t, data in dead:
        d = json.loads(data)
        if isinstance(d["amount"], str): d["amount"] = int(d["amount"].split()[0])
        fixed.append((pos, stream, t, json.dumps(d)))
    for pos, stream, t, data in fixed:
        d = json.loads(data); bal[stream] = bal.get(stream, 0) + (d["amount"] if t == "Deposited" else -d["amount"])
    print(f"   after the fix and re-driving {len(fixed)} parked events: accounts with a wrong balance {sum(1 for s in truth if bal.get(s, 0) != truth[s])}/{len(truth)}")

# ---------------------------------------------------------------------------------------------------------------- C. crash between the read-model update and the checkpoint
def part_c(trials=300):
    print("C. The projector crashes at a random moment")
    c = fresh(); truth = workload(c, n_streams=20, n=2_000, seed=3)
    events = c.execute("select pos, stream, type, data from events order by pos").fetchall()
    def run(design, rnd):
        m = sqlite3.connect(":memory:", isolation_level=None)
        m.execute("create table balances(stream text primary key, balance int)"); m.execute("create table checkpoint(pos int)"); m.execute("insert into checkpoint values (0)")
        crashes = 0
        while True:
            pos0 = m.execute("select pos from checkpoint").fetchone()[0]
            batch = [e for e in events if e[0] > pos0][:100]
            if not batch: break
            crash_at = rnd.randrange(len(batch) + 2) if rnd.random() < .04 else None
            try:
                if design == "separate":                              # update the read model, commit, THEN write the checkpoint
                    for i, (pos, s, t, d) in enumerate(batch):
                        a = json.loads(d)["amount"]; m.execute("insert into balances values (?,0) on conflict(stream) do nothing", (s,))
                        m.execute("update balances set balance = balance + ? where stream=?", (a if t == "Deposited" else -a, s))
                    if crash_at is not None: raise RuntimeError("crash after the read model, before the checkpoint")
                    m.execute("update checkpoint set pos=?", (batch[-1][0],))
                else:                                                 # one transaction: read model and checkpoint together
                    m.execute("begin")
                    for i, (pos, s, t, d) in enumerate(batch):
                        a = json.loads(d)["amount"]; m.execute("insert into balances values (?,0) on conflict(stream) do nothing", (s,))
                        m.execute("update balances set balance = balance + ? where stream=?", (a if t == "Deposited" else -a, s))
                    if crash_at is not None: raise RuntimeError("crash before commit")
                    m.execute("update checkpoint set pos=?", (batch[-1][0],)); m.execute("commit")
            except RuntimeError:
                crashes += 1
                if design == "atomic": m.execute("rollback")
        return dict(m.execute("select stream, balance from balances")), crashes
    for design in ("separate", "atomic"):
        wrong = 0; crashed = 0
        for k in range(trials):
            got, cr = run(design, random.Random(k)); crashed += cr > 0; wrong += got != truth
        print(f"   {design:<8}: {crashed} of {trials} runs had a crash, {wrong} runs ended with a wrong read model")

# ---------------------------------------------------------------------------------------------------------------- D. rebuilding a read model that is being read
def rebuild_batches(c, table, start=0, batch=5000):
    pos = start
    while True:
        rows = c.execute("select pos, stream, type, data from events where pos>? order by pos limit ?", (pos, batch)).fetchall()
        if not rows: return pos
        c.execute("begin")
        for p, s, t, d in rows:
            a = json.loads(d)["amount"]; c.execute(f"insert into {table} values (?,0) on conflict(stream) do nothing", (s,))
            c.execute(f"update {table} set balance = balance + ? where stream=?", (a if t == "Deposited" else -a, s))
        c.execute("commit"); pos = rows[-1][0]

def part_d():
    print("D. Rebuilding a read model while the application keeps reading it")
    for mode in ("in place", "side by side, then swap"):
        c = fresh(); workload(c, n_streams=200, n=150_000, seed=5)
        c.execute("create table balances(stream text primary key, balance int)"); last = rebuild_batches(c, "balances")
        expected = c.execute("select sum(balance) from balances").fetchone()[0]
        stop = threading.Event(); stats = {"reads": 0, "wrong": 0, "worst": 0.0}
        def reader():
            r = sqlite3.connect(DB, isolation_level=None, timeout=30)
            while not stop.is_set():
                t = time.perf_counter()
                try: total = r.execute("select coalesce(sum(balance),0) from balances").fetchone()[0]
                except sqlite3.OperationalError: continue
                stats["worst"] = max(stats["worst"], time.perf_counter() - t); stats["reads"] += 1; stats["wrong"] += total != expected
                time.sleep(0.002)
        th = threading.Thread(target=reader); th.start(); t0 = time.perf_counter()
        if mode == "in place":
            c.execute("delete from balances"); rebuild_batches(c, "balances")
        else:
            c.execute("create table balances_v2(stream text primary key, balance int)"); rebuild_batches(c, "balances_v2")
            c.execute("begin immediate"); c.execute("alter table balances rename to balances_old"); c.execute("alter table balances_v2 rename to balances"); c.execute("commit")
        took = time.perf_counter() - t0; stop.set(); th.join()
        print(f"   {mode:<24}: rebuild took {took:4.1f} s; {stats['reads']} reads, {stats['wrong']} of them ({100*stats['wrong']/max(1,stats['reads']):.0f}%) returned a wrong total; slowest read {stats['worst']*1000:.0f} ms")

# ---------------------------------------------------------------------------------------------------------------- E. a hash chain: what it proves
def part_e(n=100_000):
    print("E. Tamper evidence with a hash chain")
    h = "0" * 64; chain = []
    rows = [(i, f"acct-{i % 50}", "Deposited" if i % 3 else "Withdrawn", json.dumps({"amount": 10 + i % 90})) for i in range(1, n + 1)]
    t = time.perf_counter()
    for pos, s, ty, d in rows: h = hashlib.sha256((h + f"{pos}|{s}|{ty}|{d}").encode()).hexdigest(); chain.append(h)
    write = time.perf_counter() - t; anchored_head = chain[-1]                          # the head hash is published somewhere the database admin cannot change
    def verify(rows, anchor=None):
        h = "0" * 64
        for k, (pos, s, ty, d) in enumerate(rows):
            h = hashlib.sha256((h + f"{pos}|{s}|{ty}|{d}").encode()).hexdigest()
            if h != chain[k]: return f"first broken link at position {pos}"
        return "chain consistent" + ("" if anchor is None else ("; head matches the anchor" if h == anchor else "; HEAD DIFFERS FROM THE ANCHOR"))
    t = time.perf_counter(); r0 = verify(rows, anchored_head); vt = time.perf_counter() - t
    print(f"   {n:,} events: chaining took {write*1000:.0f} ms, verifying {vt*1000:.0f} ms ({r0})")
    tampered = list(rows); tampered[49_999] = (50_000, rows[49_999][1], rows[49_999][2], json.dumps({"amount": 99999}))
    print(f"   a stored amount changed:  plain log -> nothing notices; hash chain -> {verify(tampered, anchored_head)}")
    h = "0" * 64; chain2 = []                                                            # the attacker has write access to the table AND recomputes every later hash
    for pos, s, ty, d in tampered: h = hashlib.sha256((h + f"{pos}|{s}|{ty}|{d}").encode()).hexdigest(); chain2.append(h)
    chain_backup, chain[:] = chain[:], chain2
    print(f"   same edit with the chain recomputed: chain alone -> {verify(tampered).split(';')[0]}; with the head anchored outside -> {verify(tampered, anchored_head).split('; ')[-1]}")
    chain[:] = chain_backup

if __name__ == "__main__":
    part_a(); part_b(); part_c(); part_d(); part_e()

Fontes

Pratique este tema: Databases

Mais guias