Patroni & etcd/Consul

O Patroni 3.x automatiza a eleição de líder do PostgreSQL, o failover e o gerenciamento de configuração. Ele armazena o estado do cluster em um armazenamento de configuração distribuído (DCS): etcd ou Consul.

Receita

Cluster Patroni de três nós com quorum etcd e PostgreSQL 18.4.

# /etc/patroni/patroni.yml (trecho)
scope: prod-pg18
namespace: /service/
name: pg1
 
restapi:
  listen: 0.0.0.0:8008
  connect_address: 10.0.1.11:8008
 
etcd3:
  hosts: 10.0.2.1:2379,10.0.2.2:2379,10.0.2.3:2379
 
bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
  initdb:
    - encoding: UTF8
    - data-checksums
 
postgresql:
  listen: 0.0.0.0:5432
  connect_address: 10.0.1.11:5432
  data_dir: /var/lib/postgresql/18/main
  authentication:
    replication:
      username: replicator
      password: repl-secret
    superuser:
      username: postgres
      password: postgres-secret

# Inicia o Patroni em cada nó
sudo systemctl enable --now patroni
 
# Status do cluster
patronictl -c /etc/patroni/patroni.yml list

Quando usar isso: HA de PostgreSQL auto-hospedado com failover automatizado e verificações de integridade baseadas em API.

Exemplo de Funcionamento

Implantação do etcd, inicialização do Patroni, verificação do candidato a failover:

# Saúde do cluster etcd de 3 nós
etcdctl endpoint health --endpoints=https://10.0.2.1:2379,https://10.0.2.2:2379,https://10.0.2.3:2379
 
# Visão do cluster Patroni
patronictl -c /etc/patroni/patroni.yml list

-- Em qualquer membro via endpoint gerenciado pelo Patroni
SELECT pg_is_in_recovery();

# Switchover controlado (não failover de emergência)
patronictl -c /etc/patroni/patroni.yml switchover --master pg1 --candidate pg2 --force

O que isso demonstra:

O etcd fornece quorum para o bloqueio do líder (/service/prod-pg18/leader).
O Patroni gerencia postgresql.conf, configuração de recuperação e promoção.
patronictl switchover executa a mudança planejada do líder com proteção de lag (maximum_lag_on_failover).

Mergulho Profundo

Opções de DCS

Armazenamento	Prós	Contras
etcd 3.x	Nativo do Kubernetes, caminho maduro do Patroni	Operar 3+ nós para quorum
Consul	Integração multi-datacenter, service mesh	Configuração do Consul no Patroni difere do etcd
Kubernetes	CRD / endpoints como DCS	Requer padrões de operador K8s

Responsabilidades do Patroni

Aquisição e renovação da chave do líder no DCS
Reconfiguração de réplicas após failover (atualizações de primary_conninfo)
Gerenciamento opcional do modo síncrono
API REST na porta 8008 para saúde e orquestração
Integração com callbacks (recarregar HAProxy, notificar PgBouncer)

Configurações Chave do DCS

Configuração	Propósito
`ttl`	Duração do lease do líder
`loop_wait`	Intervalo de polling do Patroni
`maximum_lag_on_failover`	Bloquear promoção se a réplica estiver muito atrasada
`synchronous_mode`	Habilitar gerenciamento de quorum síncrono

Armadilhas

etcd de dois nós - Sem quorum; risco de split-brain em caso de partição. Correção: Contagem ímpar de nós etcd (3 ou 5).
Patroni sem watchdog - Raro caso de duplo primário se o fencing falhar. Correção: Habilitar watchdog em hosts Linux.
maximum_lag_on_failover muito alto - Promove réplica desatualizada, grande RPO. Correção: Definir com base no SLA de lag de bytes medido.
Token ACL do Consul mal configurado - Patroni não consegue escrever a chave do líder. Correção: Testar patronictl list após alterações de ACL.
pg_ctl promote manual ignorando o Patroni - Dessincronização do estado do cluster. Correção: Sempre usar patronictl failover ou switchover.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
repmgr	Expertise legada em repmgr	Greenfield (Patroni é o padrão de fato)
Runbook de failover manual	Pequenos clusters de desenvolvimento	Produção tier-0
HA gerenciada na nuvem	RDS Multi-AZ	Extensões personalizadas + hooks do Patroni

FAQs

etcd vs Consul para Patroni 3.x?

Ambos funcionam. O etcd é mais comum em ambientes com muito Kubernetes; o Consul se encaixa em pilhas HashiCorp existentes.

Quantos nós PostgreSQL?

Mínimo de 3 para HA significativa: 1 líder + 2 réplicas (uma candidata síncrona opcional).

O Patroni gerencia o PgBouncer?

O Patroni não executa o PgBouncer; use callbacks ou verificações do HAProxy para redirecionar pools após o failover.

PostgreSQL 18.4 com Patroni 3.x?

Suportado. Consulte as notas de lançamento do Patroni para binários PG 18 e caminhos data_dir.

O que é `patronictl pause`?

Desabilita o failover automático durante a manutenção. Retome prontamente; documente quem pausou.

Relacionados

Noções Básicas de HA - Contexto RTO/RPO
Prevenção de Split-Brain - Fencing e quorum
Proxies de Conexão - Integração com HAProxy
Noções Básicas de Streaming Replication - Configuração de réplica

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.

Patroni & etcd/Consul

Receita

Cluster Patroni de três nós com quorum etcd e PostgreSQL 18.4.

# /etc/patroni/patroni.yml (trecho)
scope: prod-pg18
namespace: /service/
name: pg1
 
restapi:
  listen: 0.0.0.0:8008
  connect_address: 10.0.1.11:8008
 
etcd3:
  hosts: 10.0.2.1:2379,10.0.2.2:2379,10.0.2.3:2379
 
bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
  initdb:
    - encoding: UTF8
    - data-checksums
 
postgresql:
  listen: 0.0.0.0:5432
  connect_address: 10.0.1.11:5432
  data_dir: /var/lib/postgresql/18/main
  authentication:
    replication:
      username: replicator
      password: repl-secret
    superuser:
      username: postgres
      password: postgres-secret

# Inicia o Patroni em cada nó
sudo systemctl enable --now patroni
 
# Status do cluster
patronictl -c /etc/patroni/patroni.yml list

Quando usar isso: HA de PostgreSQL auto-hospedado com failover automatizado e verificações de integridade baseadas em API.

Exemplo de Funcionamento

Implantação do etcd, inicialização do Patroni, verificação do candidato a failover:

# Saúde do cluster etcd de 3 nós
etcdctl endpoint health --endpoints=https://10.0.2.1:2379,https://10.0.2.2:2379,https://10.0.2.3:2379
 
# Visão do cluster Patroni
patronictl -c /etc/patroni/patroni.yml list

-- Em qualquer membro via endpoint gerenciado pelo Patroni
SELECT pg_is_in_recovery();

# Switchover controlado (não failover de emergência)
patronictl -c /etc/patroni/patroni.yml switchover --master pg1 --candidate pg2 --force

O que isso demonstra:

O etcd fornece quorum para o bloqueio do líder (/service/prod-pg18/leader).
O Patroni gerencia postgresql.conf, configuração de recuperação e promoção.
patronictl switchover executa a mudança planejada do líder com proteção de lag (maximum_lag_on_failover).

Mergulho Profundo

Opções de DCS

Armazenamento	Prós	Contras
etcd 3.x	Nativo do Kubernetes, caminho maduro do Patroni	Operar 3+ nós para quorum
Consul	Integração multi-datacenter, service mesh	Configuração do Consul no Patroni difere do etcd
Kubernetes	CRD / endpoints como DCS	Requer padrões de operador K8s

Responsabilidades do Patroni

Aquisição e renovação da chave do líder no DCS
Reconfiguração de réplicas após failover (atualizações de primary_conninfo)
Gerenciamento opcional do modo síncrono
API REST na porta 8008 para saúde e orquestração
Integração com callbacks (recarregar HAProxy, notificar PgBouncer)

Configurações Chave do DCS

Configuração	Propósito
`ttl`	Duração do lease do líder
`loop_wait`	Intervalo de polling do Patroni
`maximum_lag_on_failover`	Bloquear promoção se a réplica estiver muito atrasada
`synchronous_mode`	Habilitar gerenciamento de quorum síncrono

Armadilhas

etcd de dois nós - Sem quorum; risco de split-brain em caso de partição. Correção: Contagem ímpar de nós etcd (3 ou 5).
Patroni sem watchdog - Raro caso de duplo primário se o fencing falhar. Correção: Habilitar watchdog em hosts Linux.
maximum_lag_on_failover muito alto - Promove réplica desatualizada, grande RPO. Correção: Definir com base no SLA de lag de bytes medido.
Token ACL do Consul mal configurado - Patroni não consegue escrever a chave do líder. Correção: Testar patronictl list após alterações de ACL.
pg_ctl promote manual ignorando o Patroni - Dessincronização do estado do cluster. Correção: Sempre usar patronictl failover ou switchover.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
repmgr	Expertise legada em repmgr	Greenfield (Patroni é o padrão de fato)
Runbook de failover manual	Pequenos clusters de desenvolvimento	Produção tier-0
HA gerenciada na nuvem	RDS Multi-AZ	Extensões personalizadas + hooks do Patroni

FAQs

etcd vs Consul para Patroni 3.x?

Ambos funcionam. O etcd é mais comum em ambientes com muito Kubernetes; o Consul se encaixa em pilhas HashiCorp existentes.

Quantos nós PostgreSQL?

Mínimo de 3 para HA significativa: 1 líder + 2 réplicas (uma candidata síncrona opcional).

O Patroni gerencia o PgBouncer?

O Patroni não executa o PgBouncer; use callbacks ou verificações do HAProxy para redirecionar pools após o failover.

PostgreSQL 18.4 com Patroni 3.x?

Suportado. Consulte as notas de lançamento do Patroni para binários PG 18 e caminhos data_dir.

O que é `patronictl pause`?

Desabilita o failover automático durante a manutenção. Retome prontamente; documente quem pausou.

Relacionados

Noções Básicas de HA - Contexto RTO/RPO
Prevenção de Split-Brain - Fencing e quorum
Proxies de Conexão - Integração com HAProxy
Noções Básicas de Streaming Replication - Configuração de réplica

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.

Patroni & etcd/Consul

Buscar na documentação

Patroni & etcd/Consul