Streaming replication no PostgreSQL, passo a passo

Uma réplica de leitura é a base da alta disponibilidade e da escala de leitura no PostgreSQL — e montá-la é mais acessível do que parece. Este passo a passo leva você de um único primário a um standby por streaming verificado, e explica as partes que a maioria dos tutoriais pula: replication slots e os três tipos de lag.

O que é streaming replication

A replicação física por streaming envia o Write-Ahead Log (WAL) de um primário para um ou mais standbys somente leitura quase em tempo real. O standby reaplica cada mudança byte a byte, dando uma cópia quente para failover e escala de leitura. É em nível de bloco: o standby é um clone físico exato, mesma versão major do PostgreSQL, mesma arquitetura.

1. Configure o primário

No postgresql.conf:

wal_level = replica
max_wal_senders = 10
max_replication_slots = 10
wal_keep_size = 1GB        # rede de segurança se um slot não for usado
hot_standby = on

Crie um papel de replicação dedicado e libere no pg_hba.conf:

CREATE ROLE replicator WITH REPLICATION LOGIN PASSWORD 'secret';

# pg_hba.conf
host  replication  replicator  10.0.0.0/24  scram-sha-256

Recarregue: SELECT pg_reload_conf(); (ou reinicie se mudou o wal_level).

2. Crie um replication slot

Um slot garante que o primário mantenha o WAL até o standby consumi-lo — sem mais erros de "requested WAL segment already removed":

SELECT pg_create_physical_replication_slot('standby1');

3. Clone o diretório de dados com pg_basebackup

No host do standby, faça um base backup que também grava as configurações de conexão:

pg_basebackup \
  -h primary.internal -U replicator \
  -D /var/lib/postgresql/16/main \
  -X stream -S standby1 -R -P

As flags importantes: -R grava o standby.signal e o primary_conninfo automaticamente; -S standby1 liga o backup ao slot; -X stream transmite o WAL durante a cópia para o backup ficar consistente.

4. Suba o standby e verifique

Inicie o PostgreSQL no standby. Ele sobe em modo somente leitura e começa a transmitir. Sempre verifique — não presuma. No primário:

SELECT client_addr, state, sent_lsn, replay_lsn,
       write_lag, flush_lag, replay_lag
FROM pg_stat_replication;

state = streaming e valores de lag minúsculos indicam saúde. No standby, SELECT pg_is_in_recovery(); retorna t.

Síncrono vs assíncrono

Por padrão a replicação é assíncrona — o primário não espera o standby, então um crash pode perder as últimas transações. Para zero perda de dados, defina synchronous_standby_names e o primário esperará a confirmação do standby a cada commit (ao custo de latência de escrita). A maioria roda assíncrono com monitoramento próximo de lag.

Os três lags que importam

Repare que o pg_stat_replication reporta lag de write, flush e replay separadamente. Cada um conta uma história: write aponta para a rede, flush para o I/O de disco do standby, replay para uma consulta longa no standby bloqueando a reaplicação do WAL. Um único número "lag: 12s" esconde qual deles está falhando.

Essa decomposição é exatamente o que o PG Monitoring acompanha continuamente, com um score de risco preditivo que avisa que um standby está caminhando para a falha horas antes de cair — em vez de um snapshot que você tem que consultar na mão.