Plataformas, Microsserviços, DevOps e APIs · Hands-on 9

Hands-on 9 — Cluster de banco de dados

Um primário, duas réplicas, streaming replication — e cada trade-off que dá para provocar em um notebook

Um único container db

O gateway roda 3 réplicas atrás do Nginx, o Redis faz cache das leituras. O container db para. O que ainda funciona?

clientes
→
Nginx
→
gateway × 3
gateway
gateway
gateway
→
account, order…escalam à vontade
→
dados
Redissó o que está em cache
db paradoponto único de falha
  • As escritas param e também toda leitura que não acerta o cache.
  • Um cluster mantém cópias dos dados em vários servidores, para que um possa assumir.

O que um cluster oferece — e o que não oferece

Objetivo ✅ Oferece ❌ Não oferece
Disponibilidade um servidor com os dados, pronto para ser promovido zero downtime: o failover leva segundos
Escala de leituras SELECTs distribuídos entre as réplicas escala de escritas: um primário recebe todas
Durabilidade cada commit em outra máquina proteção contra um DELETE errado (também replicado: para isso há backups)
Replicação · este hands-oncada nó guarda todos os dados; um primário escreve
≠
Sharding · Citus, Vitessos dados divididos entre primários independentes: escala as escritas

O WAL (write-ahead log)

INSERT
→
WAL do primárioappend-only, gravado antes da página
stream →
cada réplica reexecuta o WAL
pg-replica1cópia byte a byte
pg-replica2cópia byte a byte
  • Antes de alterar uma página, o PostgreSQL acrescenta a alteração ao WAL; depois de um crash, reexecuta o WAL para se recuperar.
  • A streaming replication reaproveita o mesmo log: cópias idênticas, por isso a réplica é somente leitura e roda a mesma versão major.

A replicação física copia páginas (alta disponibilidade, réplicas de leitura); a lógica copia alterações de linhas por tabela (migrações, upgrades, integrações).

Assíncrona ou síncrona?

Quando o primário responde COMMIT ok?

Assíncrona (padrão) Síncrona
Commit retorna WAL no disco do primário uma réplica confirmou o WAL
Latência de escrita baixa + 1 ida e volta na rede
Primário morre últimos commits podem se perder nada confirmado se perde
Réplica morre nada muda commits bloqueiam

RPO (recovery point objective, objetivo de ponto de recuperação): quanto dado confirmado se pode perder num crash. Assíncrona: RPO > 0; síncrona: RPO = 0.

Teorema CAP (consistência, disponibilidade, tolerância a partição) na prática: a síncrona prefere consistência, a assíncrona prefere disponibilidade.

Quando o COMMIT ok volta?

Assíncrona
INSERT
→
WAL no disco do primário
→
COMMIT ok
⋯
a réplica recebe o WALum crash antes disso perde o commit
Síncrona
INSERT
→
WAL no disco do primário
→
uma réplica confirma+1 ida e volta; espera se ela cair
→
COMMIT ok
  • Assíncrona: o cliente ouve "ok" antes de existir uma cópia → RPO > 0
  • Síncrona: o cliente ouve "ok" depois de existir uma cópia → RPO = 0, pago com latência e commits bloqueados.

Arquitetura

serviçoaccount, order…
escritas + leituras ⇒
leituras (opcional) ⇢ réplicas
pg-primary:5432 · leitura e escrita
stream do WAL →
hot standbys · leituras
pg-replica1:5433 · somente leitura
pg-replica2:5434 · somente leitura
  • Os três rodam postgres:17; um entrypoint escolhe o papel de cada nó.
  • A aplicação decide para onde vai cada consulta: aqui, na connection string (target_session_attrs / targetServerType).
1 · Docker Composearquivos, subir, verificar
→
2 · Replicaçãoexperimentos 1–6
→
3 · Failoverplanejado, escrita perdida, consenso

Failover: à mão × automatizado

Passo À mão (este hands-on) Automatizado
detectar a falha docker compose ps health checks, heartbeats
escolher e promover uma réplica SELECT pg_promote(); eleição de líder
reapontar as outras réplicas ALTER SYSTEM SET primary_conninfo a ferramenta as reconfigura
redirecionar os clientes connection string com vários hosts IP virtual, DNS, proxy (HAProxy, PgBouncer)
trazer o primário antigo de volta pg_rewind a ferramenta faz o rewind dele

O passo difícil é o primeiro: decidir que o primário está mesmo morto.

Split brain: o primário que só parece morto

de um lado da partição
Cliente AINSERT 'x'
↓
pg-primaryvivo, ainda aceita escritas
✂ redecai entre eles
do outro lado
Monitorhealth check sem resposta → pg_promote()
↓
pg-replica1promovida
↑
Cliente BINSERT 'y'

Dois primários: 'x' só em um, 'y' só no outro, os dados divergem. Por isso a automação precisa de consenso.

1 · O projeto compose

pgcluster/: compose.yaml + scripts/ (node-entrypoint.sh, init-primary.sh, rejoin-as-replica.sh)

  • 3 × postgres:17, um volume cada, compartilhando âncoras YAML
  • cluster_name: qual nó respondeu
  • PRIMARY_HOST definido → o nó é uma réplica
  • as réplicas não têm depends_on: o entrypoint espera
  • client (profile tools): psql dentro da rede
# node-entrypoint.sh, empty data dir
pg_basebackup -h "$PRIMARY_HOST" \
  -U "$REPLICATION_USER" \
  -D "$PGDATA" -X stream -R
# -R → standby.signal
#      + primary_conninfo

init-primary.sh: role replicator, wal_keep_size, wal_log_hints, regra no pg_hba — copiados para cada réplica. Salve os scripts com fim de linha LF (não CRLF, o do Windows).

1 · Como cada nó escolhe o papel

o container sobe
→
diretório de dados já inicializado?
sim →
inicia o PostgreSQLprimário ou standby, como era
não →
PRIMARY_HOST definido?
não →
initdb + init-primary.sh
→
novo primário
sim →
espera pelo primário
→
pg_basebackup -X stream -Rcópia do primário
→
hot standbysomente leitura, recebendo o WAL
  • Um nó que já tem dados volta no papel em que terminou: depois de um failover, o pg-primary pode ser réplica.
  • Por isso docker compose down -v (apaga os volumes) é o jeito de recomeçar com os papéis originais.

1 · Subir e verificar

docker compose up -d --wait     # returns when all three nodes are healthy
docker compose exec pg-primary psql -U store \
  -c "SELECT application_name, state, sync_state FROM pg_stat_replication;"
 application_name | state     | sync_state
------------------+-----------+------------
 pg-replica1      | streaming | async
 pg-replica2      | streaming | async
logs pg-replica1
waiting for pg-primary
→
cloning pg-primarypg_basebackup
→
entering standby mode
→
started streaming WAL
  • Em uma réplica: pg_is_in_recovery() → t, pg_stat_wal_receiver → streaming a partir do pg-primary.

1 · Solução de problemas

Sintoma Causa e correção
$'\r': command not found scripts salvos com CRLF: salve como LF e recrie o cluster
réplica em loop com no pg_hba.conf entry for replication connection primário criado antes de o init-primary.sh existir: recrie
port is already allocated na 5432 o db de um hands-on anterior está no ar: pare-o ou mude as portas
réplica parada em waiting for pg-primary... o primário não está no ar: docker compose logs pg-primary
docker compose down -v && docker compose up -d --wait    # start over: one primary, two replicas

2 · Experimentos 1–3: cópias, somente leitura, lag

keyboard
mouse
monitor · INSERT no primário
pg-primary
✓
✓
✓
pg-replica1 · replay pausado
✓
✓
falta184 bytes atrás
pg-replica2
✓
✓
✓
  • 1 · CREATE TABLE + INSERT no primário → as linhas aparecem nas réplicas, vindas pelo WAL.
  • 2 · INSERT em uma réplica → cannot execute INSERT in a read-only transaction.
  • 3 · pg_wal_replay_pause() na pg-replica1: ela conta 2 linhas, a pg-replica2 conta 3; pg_stat_replication mostra os bytes de atraso.

2 · Read-your-writes: a leitura desatualizada

usuário cria um pedido
→
INSERT no pg-primary
→
COMMIT ok
→
"lista meus pedidos"
→
SELECT na pg-replica1atrasada
→
"cadê meu pedido?"
  • O WAL chega à réplica — tarde demais para aquela leitura.
  • O lag cresce com carga pesada, consultas longas na réplica ou uma rede lenta.

Correções: ler do primário logo depois de uma escrita (para aquele usuário, por alguns segundos) ou remote_apply (experimento 5) nas consultas que não podem ver dados desatualizados.

2 · Experimento 4: roteamento por papel

drivertarget_session_attrs=read-write
→
pg-primaryaceita escritas?
não ou fora →
pg-replica1aceita escritas?
não ou fora →
pg-replica2aceita escritas?
não →
erronenhum com o papel
o primeiro que responde "sim" fica com a conexão
host=pg-primary,pg-replica1,pg-replica2 target_session_attrs=read-write
host=pg-primary,pg-replica1,pg-replica2 target_session_attrs=standby load_balance_hosts=random
jdbc:postgresql://pg-primary:5432,pg-replica1:5432,pg-replica2:5432/store?targetServerType=primary
  • A lista nomeia candidatos, não o primário — ela sobrevive a um failover.

2 · Experimento 5: commits síncronos

FIRST 1 ("pg-replica1")
INSERT headset
→
pg-replica1 paradaa única que vale
→
travaCtrl+C cancela só a espera
ANY 1 (r1, r2) · quórum
INSERT webcam
→
pg-replica2 confirma
→
COMMIT okna hora
WARNING:  canceling wait for synchronous replication due to user request
DETAIL:  The transaction has already committed locally, but might not
         have been replicated to the standby.

A linha headset está confirmada? (Sim — no primário; só a espera foi cancelada.)

2 · Quanto o primário espera

COMMIT
→
recebido em memóriaremote_write
→
gravado em discoon (padrão)
→
reexecutadoremote_apply
→
COMMIT ok
synchronous_commit O commit retorna quando a réplica síncrona… Garante
remote_write recebeu o WAL (em memória) sobrevive a um crash do primário
on (padrão) gravou o WAL em disco sobrevive a um crash dos dois
remote_apply reexecutou o WAL uma leitura naquela réplica vê o commit
  • ANY 1 → as duas réplicas mostram sync_state = quorum; uma pode estar fora.
  • De volta à assíncrona antes da página de failover: ALTER SYSTEM RESET synchronous_standby_names; + pg_reload_conf().

2 · Experimento 6: sob carga (opcional)

docker compose run --rm --entrypoint pgbench client -h pg-primary -i -s 10
docker compose run --rm --entrypoint pgbench client -h pg-primary -c 8 -T 30 -P 5
docker compose run --rm --entrypoint pgbench client -S -n -c 8 -T 15 \
  "host=pg-replica1,pg-replica2 load_balance_hosts=random"
pgbench -c 8escritas
→
pg-primaryrecebe todas as escritas
WAL · replay_lag cresce →
pgbench -S · leituras
pg-replica1parte das leituras
pg-replica2parte das leituras
  • As leituras escalam com as réplicas; as escritas, não.
  • Repita com ANY 1: a queda de tps (transações por segundo) nas escritas é o preço do RPO = 0.

3 · Failover planejado

antes
o primário cai · promover
depois
pg-primary
primário
fora do ardocker compose stop
réplica da pg-replica1rejoin-as-replica.sh: pg_rewind + standby.signal
pg-replica1
réplica
primário · timeline 2SELECT pg_promote();
primário
pg-replica2
segue pg-primary
sem primário para seguir
segue pg-replica1primary_conninfo + reload
clientes
read-write → pg-primary
read-write: nenhum
mesma string → pg-replica1
  • Antes do rejoin, o pg-primary precisa estar parado: dois servidores no mesmo diretório de dados o corrompem.
  • Depois de uma parada limpa: no rewind required — o primário antigo não escreveu nada que falte ao novo.

Papéis trocados, nomes obsoletos: clusters reais chamam os nós de pg-1, pg-2… e perguntam pg_is_in_recovery().

3 · Failover não planejado: a escrita perdida

1 · para as duas réplicas
→
2 · INSERT 'lost-write'INSERT 0 1
→
3 · mata o primário
→
4 · sobe as réplicas, promove a pg-replica1
→
5 · lost-write sumiu
  • pg_rewind no primário antigo: servers diverged… rewinding → o lost-write é descartado de vez.

Esse é o RPO da replicação assíncrona. A síncrona o teria salvado — bloqueando o INSERT: o cliente nunca ouviria que o pedido existia.

ids 1, 2, 34: sequences registram valores em lotes de 32; nunca espere serial sem lacunas.

A bifurcação: para onde foi o lost-write

keyboard, mousetimeline 1, em todos os nós
→
depois da bifurcação
lost-writesó no pg-primary morto, timeline 1
after-failover · id 34pg-replica1 promovida, timeline 2
→
pg_rewindcorta o pg-primary de volta à bifurcação; ele segue a timeline 2
  • O cliente ouviu INSERT 0 1 para o lost-write: o pedido existiu e depois sumiu.
  • Uma parada planejada não tem o ramo vermelho: no rewind required.

3 · Por que não um script de failover?

O primário para de responder ao health check. Ele está morto — ou lento? Ou isolado do monitor, mas não dos clientes?

Patroni: só quem detém a leader key no etcd (Raft) roda como primário. A chave tem um tempo de vida (TTL, time to live):

pg-1 · primário
renova a chave (TTL 30 s) →
etcd · Raft
→
"ok, você é o líder"
a rede pg-1 ↔ etcd cai
→
pg-1 não renovarebaixa a si mesmo
→
a chave expira
→
pg-2 pega a chavee só então promove
  • Nunca dois primários: o isolado sai antes de outro entrar. Gerenciados (RDS Multi-AZ, Aurora, Cloud SQL) fazem o mesmo por você.

3 · Conectando a plataforma

  account:
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://pg-primary:5432,pg-replica1:5432,pg-replica2:5432/store?targetServerType=primary
      SPRING_DATASOURCE_USERNAME: store
      SPRING_DATASOURCE_PASSWORD: devpass
depois do failover
accountHikariCP descarta as conexões quebradas
→
driver JDBCtargetServerType=primary
→
pg-primaryfora do ar
→
pg-replica1o novo primário
  • Leituras nas réplicas: um segundo DataSource (preferSecondary) + AbstractRoutingDataSource para readOnly — cuidado com as leituras desatualizadas.

Limpeza: docker compose down -v — sem o -v, o cluster volta com os papéis em que terminou.

Simulador: replicação e commits síncronos

O cluster do lab no navegador: mesmos nós, mesmos comandos, mesmas saídas. Começa onde o lab começa: orders com keyboard e mouse, as duas réplicas recebendo o WAL.

Replicação 1–4
pg-primary3 linhas
pg-replica1 · replay pausado2 linhas, 184 bytes atrás
pg-replica23 linhas
Replicação 5
FIRST 1 · pg-replica1 paradaINSERT headset trava: 1 commit travado
ANY 1webcam retorna na hora; as duas viram quorum
  • A réplica recusa o INSERT; read-write acha o pg-primary e standby sorteia uma réplica.
  • synchronous_commit = remote_apply + replay pausado: o commit espera a réplica reexecutar.

Visão geral (abre no experimento 5) e topo de Replicação · simulador pg-cluster.

Simulador: failover e escrita perdida

Failover planejado
read-write: ninguémprimário parado
→
pg_promote()timeline 2
→
mesma string → pg-replica1
→
no rewind required1 primário, 0 perdidas
Escrita perdida
INSERT 0 1lost-write
→
o primário morre
→
ids 1, 2, 34pg-replica1 promovida
→
pg_rewind descarta1 escrita perdida
modo livre
pg-primary · primáriotimeline 1, sem pg_rewind
pg-replica1 · primáriotimeline 2
pg-replica2segue a pg-replica1
→
primários no ar: 2

Contadores do simulador: primários no ar, linhas no primário, commits que travaram, escritas perdidas. Topo de Failover e seção da escrita perdida · simulador pg-cluster.

Pontos-chave

  1. A replicação copia o WAL: as réplicas são cópias idênticas, somente leitura.
  2. Ela escala as leituras e dá disponibilidade; as escritas ainda vão para um primário.
  3. Assíncrona: rápida, mas lê dados desatualizados e perde escritas num crash (RPO > 0).
  4. Síncrona (ANY 1): RPO = 0, pago com latência e escritas bloqueadas.
  5. Roteie por papel na connection string; ela sobrevive a um failover.
  6. Failover = promover, reapontar, redirecionar, rebobinar — e decidir quando exige consenso, ou vira split brain.

Roteiro: (1) por que um cluster e o que ele não resolve; (2) o WAL e a streaming replication; (3) assíncrona × síncrona, CAP; (4) arquitetura e failover, à mão × automatizado, split brain; (5) Docker Compose: arquivos, papel de cada nó, subir, verificar; (6) Replicação: experimentos 1–6; (7) Failover: planejado, escrita perdida, consenso, conectando a plataforma; (8) o simulador.

O diagrama de sequência da página "Assíncrona ou síncrona?" mostra os mesmos dois caminhos passo a passo.

O mesmo fluxo está passo a passo na página Docker Compose, em "Como funciona".

A página desenha a mesma bifurcação num diagrama passo a passo em "Failover não planejado: uma escrita perdida".