Guia Passo a Passo para Configurar a Replicação por Streaming do PostgreSQL

A replicação por streaming é o mecanismo fundamental para alcançar alta disponibilidade (HA) e escalabilidade de leitura em ambientes PostgreSQL. Ao configurar um servidor primário (mestre) para transmitir continuamente registros do Write-Ahead Log (WAL) para um ou mais servidores de standby (réplica), você garante a sincronização de dados com atraso mínimo.

Este guia abrangente percorre os passos essenciais necessários para estabelecer uma replicação por streaming assíncrona robusta. Abordamos as mudanças de configuração necessárias tanto nos servidores primário quanto de standby, utilizando recursos modernos do PostgreSQL como pg_basebackup e arquivos de sinal para uma configuração simplificada. Seguir este tutorial irá equipá-lo com uma base confiável para uma operação PostgreSQL robusta.

Pré-requisitos e Configuração do Ambiente

Antes de começar, certifique-se de que os seguintes pré-requisitos sejam atendidos. Este guia assume dois servidores, Primário e Standby, executando a mesma versão principal do PostgreSQL (a versão 12 ou mais recente é recomendada).

Servidor	Função	Endereço IP (Exemplo)
Primário	Fonte da verdade	192.168.1.10
Standby	Réplica	192.168.1.11

• Usuário: Você deve ter acesso administrativo (por exemplo, sudo ou o usuário do sistema postgres) em ambos os servidores.
• Rede: O servidor Standby deve ser capaz de se conectar ao servidor Primário na porta do PostgreSQL (padrão 5432).

Passo 1: Configurar o Servidor Primário

O servidor primário deve ser configurado para gerar e servir arquivos WAL para replicação.

1.1 Modificar postgresql.conf

Edite o arquivo de configuração principal, tipicamente localizado no diretório de dados (por exemplo, /etc/postgresql/14/main/postgresql.conf), e defina os seguintes parâmetros:

# Permitir conexões de outros hosts
listen_addresses = '*'

# Definir o nível WAL para 'replica' ou superior
wal_level = replica

# Número máximo de conexões simultâneas de servidores standby
max_wal_senders = 5 

# Controla o número de conexões de standby que podem estar ativas simultaneamente
max_replication_slots = 5

# Necessário para consultas somente leitura no standby (Hot Standby)
hot_standby = on

1.2 Criar um Usuário de Replicação Dedicado

Por segurança, crie um usuário específico com o atributo REPLICATION. Este usuário será usado apenas pelo servidor standby para puxar registros WAL.

# Conectar ao PostgreSQL
psql -c "CREATE USER replica_user REPLICATION ENCRYPTED PASSWORD 'SuperSecurePassword123';"

1.3 Atualizar Autenticação de Cliente (pg_hba.conf)

Permita que o usuário de replicação do endereço IP do servidor standby se conecte ao pseudo-banco de dados especial replication.

# TIPO  BANCO DE DADOS  USUÁRIO         ENDEREÇO                MÉTODO
host    replication     replica_user    192.168.1.11/32         md5

1.4 Reiniciar o Servidor Primário

Aplique as mudanças reiniciando o serviço PostgreSQL:

sudo systemctl restart postgresql

Passo 2: Preparar o Servidor Standby

Antes de clonar os dados, certifique-se de que o serviço PostgreSQL do standby esteja parado e seu diretório de dados existente esteja limpo.

2.1 Parar o Serviço PostgreSQL do Standby

sudo systemctl stop postgresql

2.2 Limpar o Diretório de Dados

Aviso: Este passo exclui permanentemente todos os dados atualmente no diretório de dados do standby. Confirme o caminho antes da execução.

# Exemplo de caminho para PG 14
PG_DATA=/var/lib/postgresql/14/main

sudo rm -rf $PG_DATA/*

2.3 Clonar Dados Usando pg_basebackup

Use pg_basebackup para criar uma cópia exata do diretório de dados do primário. A flag -R é crucial, pois ela gera automaticamente os arquivos de configuração necessários (standby.signal e primary_conninfo) para a replicação por streaming (PostgreSQL 12+).

Execute este comando no servidor Standby:

PG_DATA=/var/lib/postgresql/14/main

sudo -u postgres pg_basebackup -h 192.168.1.10 -D $PG_DATA -U replica_user -P -v -R

Opção	Descrição
-h	Nome do host/endereço IP do servidor primário.
-D	Caminho do diretório de dados local.
-U	Nome de usuário de replicação (replica_user).
-P	Mostrar progresso.
-v	Saída verbosa.
-R	Criar um arquivo de configuração de replicação automaticamente.

Passo 3: Configurar e Iniciar o Standby

3.1 Verificar a Configuração do Standby

Se você usou a flag -R no Passo 2.3, o pg_basebackup criou um arquivo standby.signal e preencheu a configuração primary_conninfo, geralmente em um arquivo de configuração gerado chamado postgresql.auto.conf dentro do diretório de dados.

Verifique o conteúdo da string primary_conninfo. Deve ser semelhante a este (verifique dentro de $PG_DATA/postgresql.auto.conf):

primary_conninfo = 'host=192.168.1.10 user=replica_user password=SuperSecurePassword123 application_name=standby_node'

Dica: Certifique-se de que a senha esteja incluída em primary_conninfo ou que você esteja usando autenticação baseada em certificado. Se estiver usando pg_hba.conf com trust ou cert, a senha pode ser omitida.

3.2 Iniciar o Serviço Standby

Como o arquivo de sinal necessário (standby.signal) está presente no diretório de dados, o serviço iniciará no modo standby somente leitura e tentará imediatamente se conectar ao primário.

sudo systemctl start postgresql

Passo 4: Verificar a Replicação por Streaming

Após iniciar o standby, você deve confirmar que a conexão está ativa e a sincronização de dados está ocorrendo.

4.1 Verificação no Servidor Primário

Conecte-se ao servidor primário e consulte a view pg_stat_replication. Você deve ver uma linha representando a conexão do servidor standby.

psql -c "SELECT client_addr, state, sync_state, sent_lsn, write_lsn, flush_lsn FROM pg_stat_replication;"

Saída Esperada (Campos Chave):

• client_addr: Deve corresponder ao IP do servidor standby (por exemplo, 192.168.1.11).
• state: Deve ser streaming. Se mostrar startup ou catching up, aguarde um momento. Se mostrar walsender iniciando, você está perto.
• sync_state: Deve ser async (para replicação assíncrona padrão).

4.2 Testando a Sincronização de Dados

Para confirmar o fluxo de dados, execute uma alteração no primário e verifique imediatamente sua existência no standby.

No Primário:

CREATE TABLE replication_test (id serial primary key, message text);
INSERT INTO replication_test (message) VALUES ('Data synchronized successfully');

No Standby (Somente Leitura):

-- Isso deve ser bem-sucedido sem erro
psql -c "SELECT * FROM replication_test;"

Se os dados estiverem visíveis no standby, a replicação por streaming está configurada e ativa com sucesso.

Melhores Práticas e Resolução de Problemas

Conexão Persistente: Slots de Replicação

Embora opcionais, os slots de replicação são altamente recomendados. Um slot de replicação garante que o servidor primário não descarte prematuramente os segmentos WAL necessários pelo standby, mesmo que o standby se desconecte temporariamente.

No Primário:

SELECT * FROM pg_create_physical_replication_slot('standby_slot_name');

Em seguida, atualize o primary_conninfo no standby para utilizar este slot:

primary_conninfo = 'host=192.168.1.10 user=replica_user ... application_name=standby_node **slotname=standby_slot_name**'

Aviso: Slots de replicação exigem monitoramento cuidadoso. Se um standby falhar por um período prolongado, os arquivos WAL acumulados protegidos pelo slot podem fazer com que o espaço em disco do servidor primário se esgote rapidamente.

Resolução de Problemas Comuns

Problema	Causa Potencial	Solução
Standby travado em starting	Firewall de rede ou pg_hba.conf incorreto no primário.	Verifique se a porta 5432 está aberta; confirme que a entrada pg_hba.conf corresponde ao IP e usuário do standby.
pg_basebackup falha com erro de autenticação	Senha incorreta ou entrada de host ausente em pg_hba.conf.	Verifique novamente a senha para replica_user; certifique-se de que o banco de dados primário seja reiniciado após modificar pg_hba.conf.
Standby está somente leitura	Este é o comportamento esperado.	A presença de standby.signal força o servidor ao modo de recuperação.

Conclusão

Configurar a replicação por streaming é um passo crítico na construção de uma arquitetura PostgreSQL resiliente. Seguindo estes passos, você configurou com sucesso um par primário-standby que garante a sincronização contínua de dados, aprimorando significativamente as capacidades de alta disponibilidade do seu sistema. O próximo passo lógico é integrar uma solução de monitoramento e um mecanismo de failover (como Patroni ou Repmgr) para automatizar completamente a configuração de HA.