Guia Passo a Passo para Configurar Replicação por Streaming no 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 standby (réplicas), você garante a sincronização de dados com latência mínima.

Este guia aborda a replicação por streaming assíncrona usando pg_basebackup, pg_hba.conf e arquivos de sinalização standby. Você terminará com um par primário-standby funcional e as verificações necessárias para comprovar que ele está realmente transmitindo.

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 (versão 12 ou superior é 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 (ex.: sudo ou o usuário de sistema postgres) em ambos os servidores.
• Rede: O servidor Standby deve ser capaz de se conectar ao servidor Primário na porta 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. Em pacotes Debian e Ubuntu, isso geralmente está em /etc/postgresql/<versão>/main/postgresql.conf; em muitas instalações de fonte ou contêiner, ele reside no diretório de dados. Defina estes parâmetros:

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

# Definir nível WAL como '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 standby que podem estar ativas simultaneamente
max_replication_slots = 5

# Permite consultas somente leitura no 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
sudo -u postgres psql -c "CREATE ROLE replica_user WITH REPLICATION LOGIN PASSWORD 'use-a-real-secret-here';"

1.3 Atualizar Autenticação do 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.

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    replication     replica_user    192.168.1.11/32         md5

1.4 Reiniciar o Servidor Primário

Aplique as alterações de configuração. Uma reinicialização é a opção simples após alterar listen_addresses; se você alterou apenas pg_hba.conf, um recarregamento é suficiente.

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 está parado e seu diretório de dados existente está 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.

# Caminho de exemplo 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 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 detalhada.
-R	Criar um arquivo de configuração de replicação automaticamente.

Passo 3: Configurar e Iniciar o Standby

3.1 Verificar 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 isto (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 está incluída em primary_conninfo ou que você está 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 sinalização 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 visão 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 (ex.: 192.168.1.11).
• state: Deve ser streaming. Se mostrar startup ou catching up, aguarde um momento. Se mostrar walsender iniciando, 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 Soluçã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 segmentos WAL necessários para o standby, mesmo que o standby se desconecte temporariamente.

No Primário:

SELECT * FROM pg_create_physical_replication_slot('standby_slot_name');

Em seguida, defina primary_slot_name no standby. Não coloque o nome do slot dentro de primary_conninfo.

primary_conninfo = 'host=192.168.1.10 user=replica_user password=use-a-real-secret-here application_name=standby_node'
primary_slot_name = '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 encha rapidamente.

Solução de Problemas Comuns

Problema	Causa Potencial	Solução
Standby não consegue conectar	Firewall de rede, listen_addresses errado ou pg_hba.conf incorreto no primário.	Verifique se a porta 5432 está acessível; confirme se 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 foi 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.

Próximo Passo

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 sincronização contínua de dados, melhorando 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.