Logical replication do PostgreSQL (publication / subscription)

Logical replication em nível de tabela entre dois clusters PostgreSQL: wal_level=logical, verificação de replica identity, publication e subscription, sincronização inicial, monitoramento, tratamento de conflitos e sincronização manual das sequences. Inclui também os passos finais de cutover que limitam o downtime a segundos em migrações entre versões (major upgrade, troca de servidor).

Logical replication não é método de HA nem de backup: para uma cópia exata do cluster inteiro e failover use streaming replication ou Patroni, e para backup pgBackRest. O upgrade de major version no mesmo servidor (pg_upgrade) está em pg-major-upgrade.

Topologia: 2 servidores: publisher + subscriber; o publisher pode ser um servidor único, um ambiente de streaming replication ou um cluster Patroni

Cenários

• Replicação contínua (relatórios, integração, cópia parcial) — As tabelas escolhidas fluem continuamente para outro cluster (servidor de relatórios, alimentação de data warehouse, integração entre serviços). O subscriber continua gravável.
• Migração: novo servidor / nova major version + cutover — Mudar para um novo servidor ou uma nova major version com segundos de downtime: cópia inicial e sincronização contínua, depois um breve congelamento de escritas e o cutover.

Antes de começar

• O PostgreSQL … está em execução no publisher e o banco … existe.
• O cluster Patroni … está saudável e … é o Leader no momento; hot_standby_feedback = on nas replicas (padrão do pg-patroni).
• O standby … está conectado ao primary por um physical replication slot (primary_slot_name = …, a opção de slot no pg-streaming). A sincronização de slots não funciona sem esse slot.
• O PostgreSQL … foi instalado no subscriber com o pg-install e está em execução; as builds … das extensões usadas no publisher (PostGIS etc.) estão instaladas.
• O subscriber alcança …o endereço HAProxy/VIP do publisher (…:…)…a porta … do publisher… (firewall / security group).
• Qual é o wal_level atual no publisher? Se não for logical, mudá-lo exige restart: planeje uma janela de manutenção.
• As tabelas a publicar têm primary key ou um unique index adequado. Caso contrário, UPDATE/DELETE falham no publisher: adicione uma PK às tabelas listadas ou defina uma replica identity (passo abaixo).
• A logical replication não replica DDL (CREATE/ALTER TABLE), nem valores de sequences ou large objects. Enquanto a replicação estiver ativa, as mudanças de schema serão aplicadas manualmente, primeiro no subscriber e depois no publisher; a equipe foi informada.
• O publisher tem folga extra de disco para WAL: se o subscriber parar, o slot retém WAL (limite: … GB).

Fases do guia

• Preparação do publisher — Verificar se o publisher é o …Leader…primary… · Gravar as configurações de logical replication · Gravar as configurações de logical replication no Patroni · Reiniciar o publisher · Reiniciar os membros do Patroni · Criar o usuário de replicação …
• Replica identity — Listar as tabelas sem PK · Definir uma replica identity para as tabelas sem PK
• Publication — Criar a publication
• Preparação do subscriber — Gravar as configurações de workers do subscriber · Reiniciar o subscriber · Gravar a senha do publisher no .pgpass · Criar o banco de dados e o schema · Transferir roles e privilégios
• Subscription e sincronização inicial — Criar a subscription · Esperar o fim da sincronização inicial · Comparar as contagens de linhas · Teste de alteração ao vivo
• Preservar o slot no failover — Definir o slot como permanente no Patroni · Verificar se o slot aparece nas replicas · Primary: definir os standby slots sincronizados · Standby: ativar a sincronização de slots · Apontar a subscription para o novo primary após um failover · Recriar a subscription após um failover
• Monitoramento — Status da subscription (subscriber) · Lag do slot (publisher)
• Tratamento de conflitos — Encontrar o erro · Corrigir a linha em conflito no subscriber · Pular a transação em conflito
• Sincronização das sequences — Transferir os valores das sequences do publisher para o subscriber
• Cutover — Parar as escritas no publisher · Verificar se as últimas alterações foram transferidas · Sincronizar as sequences uma última vez · Remover a subscription · Coletar estatísticas · Apontar as aplicações para o subscriber …
• Operações de manutenção — Adicionar uma nova tabela · Mudança de schema (ALTER TABLE) · Remover uma subscription (com o publisher inacessível)