Streaming replication do PostgreSQL + failover automático

Sintoma

Objetivo: configurar um hot standby para o PostgreSQL com streaming replication e adicionar Patroni/repmgr para failover automático.

1. Defina os parâmetros de WAL e de conexão no primário

Para a streaming replication, wal_level precisa ser pelo menos 'replica'. max_wal_senders precisa cobrir o número de réplicas + conexões de backup, e a remoção precoce do WAL deve ser evitada com wal_keep_size ou um replication slot. As alterações exigem restart.

PostgreSQL

ALTER SYSTEM SET wal_level = 'replica';
ALTER SYSTEM SET max_wal_senders = 10;
ALTER SYSTEM SET max_replication_slots = 10;
ALTER SYSTEM SET hot_standby = on;
-- To apply the postgresql.conf change:
-- systemctl restart postgresql

2. Defina o papel de replicação e o acesso no pg_hba

Crie um papel com o atributo REPLICATION para o standby se conectar. Adicione ao pg_hba.conf uma linha que permita acesso ao banco 'replication' a partir do IP do standby e recarregue com pg_reload_conf().

PostgreSQL

CREATE ROLE replicator WITH REPLICATION LOGIN PASSWORD 'secret';
-- Add to pg_hba.conf:
-- host replication replicator 10.0.0.20/32 scram-sha-256
SELECT pg_reload_conf();

3. Crie um replication slot persistente no primário

Um replication slot físico impede que o primário remova o WAL necessário mesmo quando o standby fica para trás; gerenciar por slot é mais seguro que wal_keep_size. Usaremos o nome do slot na configuração do standby.

PostgreSQL

SELECT pg_create_physical_replication_slot('standby1_slot');
SELECT slot_name, active, restart_lsn FROM pg_replication_slots;

4. Faça um base backup no servidor standby com pg_basebackup

Com o diretório de dados do standby vazio, faça uma cópia completa a partir do primário. A opção -R grava automaticamente o arquivo standby.signal e o primary_conninfo; -C também pode criar o slot. O nome do slot é passado com -S.

PostgreSQL

pg_basebackup -h 10.0.0.10 -U replicator -D /var/lib/pgsql/data \
  -R -X stream -S standby1_slot -P -v

5. Verifique primary_conninfo e hot_standby e inicie o standby

Confira o primary_conninfo (host, usuário, slot) no postgresql.auto.conf gravado pelo -R; a presença do arquivo standby.signal determina o modo standby. Com hot_standby=on, o standby aceita consultas somente leitura. Inicie o serviço.

PostgreSQL

-- Expected in postgresql.auto.conf:
-- primary_conninfo = 'host=10.0.0.10 user=replicator password=secret'
-- primary_slot_name = 'standby1_slot'
-- systemctl start postgresql
SELECT pg_is_in_recovery();  -- should return true on the standby

6. Monitore o lag de replicação a partir do primário

No primário, pg_stat_replication mostra o LSN enviado/reaplicado e o atraso de cada standby. Os atrasos write/flush/replay devem ficar pequenos; sync_state é 'sync' se for usada uma réplica síncrona.

PostgreSQL

SELECT client_addr, state, sync_state,
       pg_wal_lsn_diff(sent_lsn, replay_lsn) AS replay_lag_bytes,
       write_lag, flush_lag, replay_lag
FROM pg_stat_replication;

7. Adicione Patroni ou repmgr para failover automático

A streaming replication pura exige um promote manual. O failover automático exige um gerenciador de cluster: Patroni (eleição de líder no etcd/Consul + promote automático) ou repmgr (monitoramento/failover com repmgrd). No lado da aplicação, ofereça um único endpoint com HAProxy/pgBouncer. Se for necessário um promote manual: pg_ctl promote. Antes de promover, garanta que o primário antigo esteja realmente parado e que as aplicações não consigam escrever nele (risco de split-brain). Reintegrar o primário antigo como standby do novo primário exige pg_rewind; para isso, wal_log_hints = on ou data checksums precisam estar ativos.

PostgreSQL

-- Manual promote (if there is no cluster manager):
pg_ctl promote -D /var/lib/pgsql/data
-- or via SQL:
SELECT pg_promote();
-- With Patroni: patronictl -c /etc/patroni.yml switchover mycluster