PostgreSQL streaming replication (primary + standby)

Adiciona um ou mais hot standbys a um primary já instalado com pg_basebackup (usuário de replicação, pg_hba, replication slot, modo assíncrono ou síncrono ANY/FIRST, monitoramento de atraso) e gera os runbooks de operação deste cluster sem Patroni: switchover planejado, failover manual (pg_promote), reintegração do antigo primary com pg_rewind, reconstrução de um standby, standby em cascata e com atraso, limpeza de slots, alteração da configuração síncrona. O failover não é automático, o DBA o executa; para failover automático use pg-patroni, para fluxo de dados por tabela ou entre versões use pg-logical-repl.

Topologia: 1 primary + 1..N standbys

Cenários

• Instalação: adicionar standbys ao primary — Um ou mais hot standbys são adicionados a um primary já instalado com pg_basebackup (slot, síncrono/assíncrono, monitoramento). O primary continua aberto; a cópia inicial gera carga de disco e rede no primary.
• Switchover planejado (troca de papéis, sem perda de dados) — Manutenção planejada: o primary é desligado de forma limpa, o primeiro standby é promovido e o antigo primary volta como standby. Sem perda de dados; a interrupção de escrita costuma ser menor que 1 minuto.
• Failover manual (o primary caiu, promover o standby) — O primary caiu ou está inacessível: o antigo primary é isolado (fencing) e o standby mais atualizado é promovido manualmente. No modo assíncrono as últimas transações podem ser perdidas.
• Reintegrar o antigo primary como standby com pg_rewind — Após o failover, o antigo primary é ressincronizado com o novo primary via pg_rewind e volta como standby; é muito mais rápido que uma cópia completa.
• Adicionar um novo standby alimentado por outro standby (cascading) — O novo standby recebe o WAL do primeiro standby em vez do primary: em um data center remoto ou com muitos standbys, isso reduz a carga de rede/envio de WAL do primary. O primary não é afetado.
• Configurar um standby com atraso (delayed) — Standby que aplica o WAL horas depois (recovery_min_apply_delay): para recuperar dados apagados por engano sem restaurar backup. Não é candidato a failover.
• Reconstruir um standby do zero — O standby ficou para trás, seu WAL foi removido ou está corrompido: o diretório de dados é movido para o lado e copiado novamente do primary. O primary não é afetado.
• pg_wal crescendo, disco enchendo (limpeza de slots não usados) — A causa do acúmulo de WAL é identificada (slot inativo, falha de arquivamento, wal_keep_size); o replication slot não usado é removido e o espaço de WAL é recuperado. O primary continua aberto.
• Adicionar / remover standby síncrono (synchronous_standby_names) — Reescreve a lista síncrona conforme o modo do formulário (ANY/FIRST, k) ou volta para assíncrono; aplicado com reload, sem restart. Uma configuração errada pode deixar commits pendentes; por isso é verificada antes.

Antes de começar

• O primary … está instalado com o guia pg-install e em execução (PostgreSQL …, PGDATA …, porta …).
• Nos servidores standby foi feita apenas a fase de preparação do sistema operacional do guia pg-install (hostname, chrony, sysctl, THP). O cluster não foi criado; o software é instalado neste guia.
• Mesma família de sistema operacional, mesma arquitetura (x86_64/aarch64) e mesma versão principal do PostgreSQL (…) em todos os servidores. O standby é uma cópia física exata do primary.
• No standby há, para …, espaço livre pelo menos 20% maior que o tamanho dos dados no primary.
• Os servidores se alcançam pela porta …; os hostnames são resolvidos e os relógios estão sincronizados via NTP.
• A porta … está aberta entre os servidores no firewall (se o pg-install abriu apenas a rede da aplicação, adicione também os IPs de replicação).
• No Debian/Ubuntu os arquivos de configuração ficam fora do diretório de dados (/etc/postgresql), então o pg_basebackup não os copia; você tem acesso scp do standby ao primary como root (ou usuário com sudo), ou vai mover os arquivos manualmente.
• O diretório de dados do antigo primary está íntegro e o servidor consegue subir (em caso de falha de disco é preciso reconstruir com pg_basebackup, não com pg_rewind).
• …Foi escolhido um horário adequado para a cópia inicial (pg_basebackup), que gera carga no primary.…A janela de manutenção está aberta; as equipes de aplicação sabem da breve interrupção de escrita.…Foi confirmado que o primary está realmente inacessível; está garantido que ele não voltará aceitando escritas como um segundo primary (fencing).…O novo primary está saudável e aceitando escritas.…O novo servidor (…) está pronto: a preparação do sistema operacional foi feita, … está vazio e tem espaço suficiente; a cópia inicial vai gerar carga na origem (…).…Enquanto … é reconstruído, a carga de leitura pode ser levada para os outros servidores; a cópia vai gerar carga no primary.…A ocupação do disco está sendo monitorada; antes de remover o slot, o responsável pelo standby que o usa foi consultado.…A alteração síncrona ocorre em janela de manutenção; as equipes de aplicação foram informadas porque a latência de commit vai mudar.…

Fases do guia

• Preparação (todos os servidores) — Adicionar os nomes dos servidores ao /etc/hosts · Adicionar o repositório PGDG · Adicionar o repositório PGDG · Instalar o software do servidor PostgreSQL · Preparar o diretório de dados · Criar a configuração do cluster e esvaziar o diretório de dados
• Preparação da replicação no primary — Verificar o pré-requisito do pg_rewind · Gravar o arquivo de configuração de replicação · Carregar as configurações · Criar o usuário de replicação · Definir a senha do usuário de replicação · Adicionar as regras de replicação ao pg_hba.conf …
• Instalação do standby (pg_basebackup) — Testar a conexão de replicação com o primary · Copiar o primary: … · Copiar os arquivos de configuração do primary · Iniciar o standby
• Verificação — Verificar o estado da replicação no primary · Verificar o receptor de WAL no standby · Gravar dados de teste no primary · Ler os dados de teste no standby · Apagar a tabela de teste
• Ativar a replicação síncrona — Gravar o arquivo de configuração síncrona · Carregar a configuração em todos os servidores · Verificar o estado síncrono
• Monitoramento e pós-instalação — Consulta de monitoramento de atraso (primary) · Consulta de monitoramento de atraso (standby) · Monitoramento da ocupação dos slots · String de conexão da aplicação · Ajustar o backup em função do standby
• Verificação antes do switchover — Verificar o estado dos standbys · Confirmar que o novo primary está pronto · Verificar .pgpass e pg_hba no antigo primary
• Switchover — Desligar o antigo primary de forma limpa · Confirmar que o novo primary recebeu o último WAL · Promover o servidor … · Criar os slots no novo primary · Configurar o antigo primary como standby · Iniciar o antigo primary como standby …
• Failover manual — Parar e desativar o antigo primary (fencing) · Identificar o standby mais atualizado · Promover o servidor … · Remover temporariamente a espera síncrona · Criar os slots no novo primary · Redirecionar os demais standbys para o novo primary: … …
• Reintegrar o antigo primary com pg_rewind — Verificar o slot e a regra de conexão no novo primary · Confirmar que o antigo primary está desligado · Execução de teste do pg_rewind · Aplicar o pg_rewind · Completar a configuração do standby · Iniciar o antigo primary como standby …
• Inchaço de pg_wal e limpeza de slots — Por que o pg_wal está crescendo? · Encontrar o dono do slot · Remover o slot não usado: … · Remoção de slot: preencha o formulário · Confirmar que o espaço de WAL foi recuperado · Evitar a repetição: limite superior e monitoramento
• Alteração do standby síncrono — Estado síncrono atual · Verificação de segurança: há standbys conectados suficientes? · Gravar o arquivo de configuração síncrona · Remover a configuração síncrona (voltar para assíncrono) · Carregar a configuração em todos os servidores · Verificar o novo estado