Melhor VPS

Infraestrutura

Replicação PostgreSQL com Patroni: failover em VPS

Aprenda a configurar replicação PostgreSQL com Patroni, etcd e HAProxy em VPS, com eleição de líder, failover automático, segurança e testes práticos.

Revisão editorial: Concluída

Resposta direta

A replicação PostgreSQL com Patroni usa replicação física por streaming, um armazenamento distribuído como etcd e verificações periódicas de estado para eleger o servidor primário. Quando o líder deixa de responder, os membros restantes confirmam o quorum, escolhem uma réplica elegível e promovem esse nó automaticamente. Em uma implantação consistente, são usados pelo menos três membros do etcd, dois ou três servidores PostgreSQL e uma camada de conexão, normalmente HAProxy, para direcionar escritas ao líder atual. O failover reduz o tempo de indisponibilidade, mas não elimina risco de perda de dados, falhas de aplicação ou corrupção lógica. Antes da produção, a equipe precisa testar perda de rede, desligamento do líder, atraso de réplica, restauração de backup e reconexão dos clientes.

Resumo rápido

  • Patroni coordena PostgreSQL, eleição de líder, promoção de réplicas e reentrada de nós no cluster.
  • etcd mantém o estado distribuído e precisa de número ímpar de membros, normalmente três.
  • Uma base inicial razoável para cada nó PostgreSQL é 2 vCPUs, 4 GB de RAM e 80 GB de SSD ou NVMe.
  • HAProxy consulta a API REST do Patroni e envia escritas apenas ao líder saudável.
  • Replicação assíncrona prioriza disponibilidade, enquanto a síncrona reduz a janela de perda com maior impacto na latência.
  • Failover não substitui backup com retenção, cópia externa e teste de restauração.
  • A aplicação deve usar pool de conexões, timeouts e repetição controlada de transações interrompidas.

Como funciona a arquitetura com Patroni

O papel do Patroni e do armazenamento distribuído

Patroni não substitui o PostgreSQL nem implementa um banco novo. Ele executa como um processo ao lado de cada instância, altera parâmetros de replicação, acompanha a saúde local e disputa uma chave de liderança em um Distributed Configuration Store, ou DCS. etcd é uma escolha comum para esse papel. Consul e Kubernetes também podem ser usados, mas mudam os procedimentos de instalação e operação.

Imagine três VPS chamadas pg1, pg2 e pg3. Cada uma executa PostgreSQL e Patroni. Três membros do etcd, preferencialmente distribuídos entre domínios de falha, mantêm o consenso. O nó líder renova periodicamente sua sessão no DCS. Se ele falhar e a sessão expirar, as réplicas verificam fatores como atraso de WAL, estado do PostgreSQL e regras de elegibilidade. Uma delas adquire a liderança e executa a promoção. O processo costuma levar segundos, mas o tempo real depende de ttl, loop_wait, rede, carga e comportamento do cliente.

O Patroni oferece uma API REST, geralmente na porta 8008. Um balanceador pode consultar /primary para localizar o líder e /replica para encontrar réplicas disponíveis. Isso evita colocar o endereço fixo de pg1 na aplicação. Se a liderança migrar para pg2, o HAProxy atualiza o destino após o próximo health check.

Quem ainda está definindo a base do ambiente pode consultar o conteúdo sobre VPS para banco PostgreSQL, que detalha CPU, memória, armazenamento e isolamento antes da camada de alta disponibilidade.

Replicação não substitui backup

Uma exclusão acidental, um DROP TABLE ou uma atualização incorreta é replicada para os demais nós. Para recuperar o estado anterior, ainda são necessários backups completos e arquivamento de WAL. Também existe risco de perda em replicação assíncrona: uma transação confirmada no líder pode ainda não ter alcançado a réplica promovida. Patroni melhora a continuidade do serviço, mas RPO e RTO continuam dependendo da configuração, da latência e dos procedimentos de recuperação.

Dimensionamento das VPS e desenho da topologia

Configurações por perfil

O cluster deve ser dimensionado pela carga normal e pelo pico esperado depois de uma falha. Se três nós atendem consultas de leitura e um deles desaparece, os dois restantes precisam absorver o trabalho sem entrar em swap. CPU compartilhada pode atender laboratórios, porém cargas transacionais com latência previsível se beneficiam de vCPUs dedicadas ou de políticas claras de compartilhamento. O disco precisa sustentar escrita de WAL, checkpoints, tabelas temporárias e leitura aleatória ao mesmo tempo.

PerfilNós PostgreSQLRecurso por nóDCSArmazenamento sugeridoUso esperado
Laboratório22 vCPUs, 2 GB RAM3 membros pequenos40 GB SSDTestes de eleição, deploy e treinamento
Produção pequena32 a 4 vCPUs, 4 a 8 GB RAM3 membros80 a 160 GB SSD ou NVMeAPIs internas e aplicações com carga moderada
Produção crítica3 ou mais4 a 8 vCPUs, 16 GB RAM ou mais3 ou 5 membros isoladosNVMe com folga de IOPS e capacidadeSaaS, comércio eletrônico e serviços com SLO formal

Os números são pontos de partida, não garantias de desempenho. Um banco de 20 GB com muitas atualizações pode exigir mais IOPS que outro de 300 GB usado quase só para leitura. Meça latência de disco, taxa de transações, volume diário de WAL, conexões simultâneas e crescimento mensal. Reserve pelo menos 25% a 30% do volume para picos, manutenção e recriação de índices. Discos quase cheios aumentam o risco operacional e podem impedir o PostgreSQL de criar arquivos temporários.

Latência, disco e rede

Na replicação síncrona, cada confirmação pode esperar a resposta de outra instância. Uma latência de rede de 2 ms não produz o mesmo efeito que 40 ms entre regiões. Para bancos sensíveis, mantenha os nós na mesma região, mas em hosts físicos ou zonas distintas quando o provedor oferecer essa separação. A distribuição geográfica pode ser reservada a uma réplica assíncrona de recuperação de desastre.

A rede privada reduz exposição e evita que o tráfego de replicação atravesse a internet pública. Se isso não estiver disponível, use firewall restritivo, TLS e endereços explicitamente autorizados. Confirme também limites de banda e tráfego do plano. Uma recriação de réplica de 500 GB pode consumir a franquia rapidamente, mesmo que o tráfego diário da aplicação seja pequeno.

Preparação dos servidores e do cluster etcd

Rede, nomes e portas

Comece com três endereços privados estáveis, por exemplo 10.20.0.11, 10.20.0.12 e 10.20.0.13. Configure resolução por DNS interno ou /etc/hosts, sincronização de horário com chrony e uma distribuição Linux suportada. Os exemplos abaixo assumem Debian ou Ubuntu. Ajuste nomes de pacotes para outras distribuições.

Restrinja a porta 5432 aos servidores da aplicação, ao HAProxy e aos membros PostgreSQL. A porta 8008 deve aceitar apenas balanceadores e administradores autorizados. No etcd, 2379 atende clientes e 2380 faz comunicação entre pares. Não exponha essas portas indiscriminadamente. Um conjunto simples de regras permite 2379 e 2380 apenas entre os três membros, 5432 entre os nós e o balanceador, e SSH somente a partir de uma rede administrativa.

Instale o etcd nos três membros:

sudo apt update
sudo apt install -y etcd-server etcd-client

Em ambientes maiores, é preferível executar o DCS separado dos bancos. Colocar etcd e PostgreSQL nas mesmas três VPS economiza recursos e funciona em projetos menores, mas uma pressão de memória ou falha do host remove simultaneamente um membro do banco e um voto do consenso. Essa decisão precisa aparecer no registro de riscos da arquitetura.

Formação do quorum do etcd

Cada membro recebe um nome e anuncia seus endereços. No primeiro servidor, a configuração conceitual fica assim:

name: etcd1
listen-peer-urls: http://10.20.0.11:2380
initial-advertise-peer-urls: http://10.20.0.11:2380
listen-client-urls: http://10.20.0.11:2379,http://127.0.0.1:2379
advertise-client-urls: http://10.20.0.11:2379
initial-cluster: etcd1=http://10.20.0.11:2380,etcd2=http://10.20.0.12:2380,etcd3=http://10.20.0.13:2380
initial-cluster-state: new
initial-cluster-token: pg-prod-01

Repita nos demais nós, alterando nome e endereço local. Depois de iniciar os serviços, valide o quorum com etcdctl endpoint status --cluster -w table e etcdctl endpoint health --cluster. Três endpoints saudáveis devem aparecer, com um líder do etcd e índices Raft próximos. Não prossiga se um membro estiver reiniciando, com relógio divergente ou inacessível.

O exemplo usa HTTP apenas para simplificar a leitura. Em produção, configure certificados de cliente e servidor no etcd. Guarde chaves privadas com permissões restritas e automatize a renovação. O conceito mais amplo de distribuição entre falhas de host também é abordado no artigo sobre alta disponibilidade e failover em VPS.

Instalação e configuração do Patroni

Pacotes e credenciais

Em cada nó de banco, instale PostgreSQL, dependências Python e Patroni com suporte ao etcd. Fixe versões em automações para impedir atualização inesperada durante um rebuild.

sudo apt install -y postgresql python3-venv python3-pip
sudo python3 -m venv /opt/patroni
sudo /opt/patroni/bin/pip install patroni[etcd3] psycopg2-binary
sudo systemctl disable --now postgresql

O serviço nativo do PostgreSQL é desativado porque o Patroni deve controlar inicialização e promoção. Crie um usuário de sistema sem shell, diretórios com proprietário correto e um arquivo de ambiente legível apenas por root. Não coloque senhas reais em repositórios Git, imagens de máquina ou exemplos públicos. Patroni aceita variáveis como PATRONI_POSTGRESQL_AUTHENTICATION_SUPERUSER_PASSWORD e PATRONI_POSTGRESQL_AUTHENTICATION_REPLICATION_PASSWORD, que podem ser carregadas por um EnvironmentFile do systemd.

Arquivo de configuração do primeiro nó

Uma base para pg1 pode ser escrita em /etc/patroni/patroni.yml:

scope: postgres-prod
namespace: /service/
name: pg1

restapi:
  listen: 10.20.0.11:8008
  connect_address: 10.20.0.11:8008

etcd3:
  hosts: 10.20.0.11:2379,10.20.0.12:2379,10.20.0.13:2379

bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
    postgresql:
      use_pg_rewind: true
      use_slots: true
      parameters:
        wal_level: replica
        hot_standby: on
        max_wal_senders: 10
        max_replication_slots: 10
        wal_keep_size: 1024MB
        password_encryption: scram-sha-256
  pg_hba:
    - host replication replicator 10.20.0.0/24 scram-sha-256
    - host all all 10.20.0.0/24 scram-sha-256

postgresql:
  listen: 10.20.0.11:5432
  connect_address: 10.20.0.11:5432
  data_dir: /var/lib/postgresql/patroni
  bin_dir: /usr/lib/postgresql/16/bin
  authentication:
    replication:
      username: replicator
    superuser:
      username: postgres

Ajuste bin_dir à versão instalada. maximum_lag_on_failover de 1 MiB impede a promoção de uma réplica muito atrasada, mas também pode deixar o cluster sem candidato. Defina esse limite segundo o RPO, não por cópia cega. ttl: 30 e loop_wait: 10 são valores iniciais comuns, não uma promessa de failover em 30 segundos.

Inicialização das réplicas

Crie uma unidade systemd apontando para /opt/patroni/bin/patroni /etc/patroni/patroni.yml, carregue o arquivo de credenciais e inicie primeiro pg1. Em pg2 e pg3, altere name, listen, connect_address e o endereço local. Ao iniciar, eles devem clonar o líder com pg_basebackup.

Use patronictl -c /etc/patroni/patroni.yml list para conferir função, timeline, estado e atraso. Faça também uma consulta em cada nó: SELECT pg_is_in_recovery(); retorna false no líder e true nas réplicas. Se a clonagem falhar, verifique permissões do diretório, rota de rede, pg_hba, versão dos binários e espaço livre antes de repetir o bootstrap.

HAProxy e conexão transparente com o líder

Health checks da API REST

Mesmo com eleição automática, a aplicação precisa descobrir o novo líder. HAProxy resolve isso consultando a API REST de cada Patroni. Para reduzir outro ponto único de falha, execute dois balanceadores e use um IP virtual, DNS com TTL baixo ou um balanceador gerenciado. Uma única VPS com HAProxy simplifica o laboratório, mas não entrega alta disponibilidade ponta a ponta.

A configuração abaixo publica escritas na porta 5000:

frontend postgres_write
    bind *:5000
    mode tcp
    default_backend patroni_primary

backend patroni_primary
    mode tcp
    option httpchk GET /primary
    http-check expect status 200
    default-server inter 2s fall 3 rise 2 on-marked-down shutdown-sessions
    server pg1 10.20.0.11:5432 check port 8008
    server pg2 10.20.0.12:5432 check port 8008
    server pg3 10.20.0.13:5432 check port 8008

O HAProxy consulta /primary na porta 8008, mas encaminha o tráfego aprovado para 5432. Com inter 2s e fall 3, um destino pode levar aproximadamente seis segundos para ser marcado como indisponível, além do tempo de eleição. shutdown-sessions encerra sessões ligadas ao servidor removido. Isso acelera a reconexão, mas também interrompe transações abertas. Teste o comportamento do driver antes de adotar a opção.

Separação entre escrita e leitura

Outro frontend pode usar a porta 5001 e consultar /replica, distribuindo consultas somente leitura. Essa separação exige disciplina na aplicação. Uma leitura feita logo após uma escrita pode chegar a uma réplica que ainda não recebeu o WAL correspondente. Operações que exigem consistência imediata devem continuar no endpoint do líder.

Conexões persistentes também merecem atenção. HAProxy não transfere uma sessão existente para o novo primário. O cliente recebe erro e precisa abrir outra conexão. PgBouncer reduz o custo de reconexões e controla o número de sessões no banco, mas deve ser configurado com timeouts e modo de pool compatíveis com a aplicação. O tutorial de como configurar PgBouncer em VPS complementa essa camada.

Use connect_timeout entre 3 e 5 segundos no driver e repetição com backoff apenas para operações idempotentes ou transações cujo resultado possa ser verificado. Repetir cegamente um pagamento ou criação de pedido pode duplicar dados. A lógica de retry pertence ao desenho da aplicação, não apenas ao balanceador.

Testes de failover, segurança e operação diária

Como simular uma falha real

Teste primeiro em staging com carga representativa. Abra uma sessão através do HAProxy, crie uma tabela de teste e grave uma linha por segundo com timestamp. Em outra janela, acompanhe patronictl list, logs do Patroni e métricas do HAProxy. Desligue o serviço Patroni no líder com systemctl stop patroni, sem tocar nos demais nós. Registre o instante da última escrita aceita, o momento da promoção e o tempo da primeira reconexão bem-sucedida.

Depois, execute cenários diferentes. Bloqueie temporariamente o acesso do líder ao etcd para testar perda de quorum percebida. Interrompa a rede de replicação para observar o crescimento de atraso. Encha um volume de laboratório até um limite seguro para validar alertas de capacidade. Cada teste investiga uma falha distinta, e simplesmente reiniciar o PostgreSQL não cobre problemas de rede, disco ou consenso.

Não force promoções simultâneas nem use comandos de remoção do DCS sem entender a situação. Uma partição de rede mal tratada pode manter um antigo primário acessível aos clientes. Esse cenário, conhecido como split-brain, precisa ser contido com quorum, watchdog quando suportado e regras de rede que impeçam escrita no nó isolado.

Switchover planejado e retorno do nó

Para manutenção, prefira patronictl switchover. O comando permite escolher candidato e horário, reduzindo surpresa para a aplicação. Após a troca, confirme a timeline e execute escritas pelo endpoint do HAProxy. Quando o antigo líder retornar, pg_rewind pode sincronizá-lo sem cópia completa, desde que os pré-requisitos estejam atendidos. Se o rewind falhar ou o histórico divergir demais, recrie o nó a partir do líder atual.

Mantenha TLS entre clientes e PostgreSQL, autenticação SCRAM, contas separadas por aplicação e privilégios mínimos. A API do Patroni e o etcd não devem ficar abertos à internet. Atualizações de PostgreSQL, Patroni e sistema operacional devem passar por switchover controlado, um nó de cada vez.

Backup, métricas e alertas

Use uma ferramenta como pgBackRest ou Barman para backups completos, incrementais e arquivamento contínuo de WAL. Armazene ao menos uma cópia fora do cluster e faça restaurações periódicas em servidor isolado. Monitore atraso de replicação em bytes e segundos, geração de WAL, checkpoints, uso de disco, reinicializações, mudanças de timeline e saúde do etcd. Um alerta de réplica atrasada deve chegar antes do failover, porque uma réplica inelegível reduz a tolerância a falhas justamente quando ela é necessária.

Recomendações por perfil

Desenvolvedor solo e laboratório

Para estudar Patroni, duas VPS PostgreSQL pequenas e três membros do etcd são suficientes para observar eleição e promoção, embora dois bancos não ofereçam a mesma margem operacional de três. Uma configuração de 2 vCPUs, 2 GB de RAM e 40 GB SSD por banco atende testes com bases pequenas. Os membros do etcd podem usar 1 vCPU e 1 GB de RAM. Se o orçamento exigir colocalização, documente que a topologia serve para aprendizado, não para sustentar um SLA. Automatize a criação com Ansible e pratique falhas repetidamente. O ganho principal nesse perfil é entender a sequência de eleição, reconexão e reintegração.

Equipe pequena com serviço interno

Use três nós PostgreSQL com 2 a 4 vCPUs, 4 a 8 GB de RAM e pelo menos 80 GB de armazenamento cada. Mantenha etcd em três membros e coloque dois HAProxy diante do cluster. Uma aplicação interna com algumas dezenas de conexões pode adicionar PgBouncer para limitar sessões e facilitar reinicializações. Replicação assíncrona costuma oferecer bom equilíbrio quando alguns segundos ou poucos megabytes de RPO são aceitos, mas o limite deve ser formalizado. Configure backup externo, alerta de atraso acima de 64 ou 128 MiB e teste de switchover mensal.

Produção crítica

Sistemas com receita, contratos ou SLO rigoroso precisam de três ou mais nós, isolamento entre hosts e capacidade para operar após a perda de um servidor. Comece a avaliação com 4 a 8 vCPUs, 16 GB de RAM e armazenamento NVMe por nó, mas valide com carga e volume de WAL reais. Considere replicação síncrona quando a redução do RPO justificar a latência adicional e o risco de bloquear commits sem réplica elegível. Separe etcd dos bancos, use TLS mútuo, dois balanceadores e observabilidade externa ao cluster. Documente procedimentos para failover, split-brain, perda de região e restauração pontual. Execute exercícios trimestrais, pois uma arquitetura que nunca foi testada ainda é apenas uma hipótese operacional.

Perguntas frequentes

Quantas VPS são necessárias para usar PostgreSQL com Patroni?

Um laboratório pode funcionar com duas VPS PostgreSQL e três membros do etcd, inclusive colocalizando componentes para reduzir custo. Em produção, a topologia mais equilibrada usa três nós PostgreSQL, três membros do etcd e dois balanceadores. Os serviços podem compartilhar servidores em projetos pequenos, mas isso correlaciona falhas: perder uma VPS remove simultaneamente um banco e um voto do DCS. Ambientes críticos devem separar essas funções e distribuir os nós entre hosts físicos ou zonas distintas. A quantidade final depende do RTO, do RPO e da tolerância a pontos únicos de falha.

Patroni evita qualquer perda de dados durante o failover?

Não. Com replicação assíncrona, uma transação pode ser confirmada no líder antes de seu WAL chegar à réplica promovida. O parâmetro `maximum_lag_on_failover` limita quais réplicas são elegíveis, mas não transforma o processo em perda zero. A replicação síncrona reduz essa janela ao exigir confirmação de outra instância, com custo de latência e possível bloqueio quando não existe réplica disponível. O projeto deve definir um RPO aceitável, monitorar atraso e manter backups com arquivamento de WAL. Failover automático melhora disponibilidade, mas não substitui proteção e recuperação de dados.

É obrigatório usar etcd com Patroni?

Patroni precisa de um mecanismo distribuído para armazenar estado e coordenar a liderança, mas esse mecanismo não precisa ser obrigatoriamente o etcd. Consul, ZooKeeper e a API do Kubernetes estão entre as alternativas compatíveis, dependendo da versão e do ambiente. etcd é comum em instalações sobre VPS porque oferece consenso por Raft, documentação ampla e operação independente de um orquestrador. O ponto central é manter quorum e baixa latência entre os membros. Usar um único servidor DCS elimina a tolerância a falhas e pode impedir eleições quando esse servidor estiver indisponível.

Quanto tempo demora um failover do Patroni?

Não existe um tempo universal. Com `ttl` de 30 segundos, `loop_wait` de 10 segundos e health checks do HAProxy a cada dois segundos, a interrupção percebida pode ficar na faixa de dezenas de segundos, mas varia conforme o tipo de falha. Queda limpa do processo, partição de rede, disco travado e perda de quorum produzem comportamentos diferentes. A promoção também depende do atraso da réplica e da recuperação do PostgreSQL. Meça o resultado com tráfego real, registrando a última escrita aceita, a eleição, a atualização do balanceador e a primeira reconexão da aplicação.

HAProxy e PgBouncer exercem a mesma função no cluster?

Não. HAProxy identifica quais servidores estão saudáveis e direciona novas conexões para o líder ou para as réplicas, conforme o endpoint configurado. PgBouncer mantém pools de conexões PostgreSQL, reduz o custo de abertura de sessões e limita quantas conexões chegam ao banco. Eles podem ser usados juntos: a aplicação conecta ao PgBouncer, que alcança o endpoint de escrita publicado pelo HAProxy. O desenho exato depende do modo de pool e da descoberta do líder. Nenhum deles transfere uma transação aberta durante o failover, então o cliente ainda precisa tratar desconexões.

Como atualizar PostgreSQL e Patroni sem derrubar o cluster?

Atualizações menores podem ser aplicadas de forma sequencial. Comece por uma réplica, remova-a temporariamente do tráfego, atualize pacotes, reinicie e confirme que ela alcançou o líder. Repita no segundo nó e faça um switchover planejado antes de atualizar o antigo primário. Mudanças de versão principal do PostgreSQL exigem outro procedimento, como replicação lógica, `pg_upgrade` coordenado ou construção de um cluster paralelo. Faça backup antes da manutenção e teste o plano em staging. Atualize o DCS e os balanceadores separadamente para não combinar várias mudanças críticas na mesma janela.

Fontes consultadas