Patroni é um sistema de gerenciamento de cluster de alta disponibilidade para PostgreSQL, desenvolvido para automatizar o failover, a replicação e a manutenção da consistência entre os nós do banco de dados.
Inicialmente criado pela empresa Zalando, o Patroni é hoje uma das soluções mais populares para a construção de clusters PostgreSQL tolerantes a falhas.
O Patroni fornece comutação automática de papéis (primary/replica), monitora a integridade dos nós e mantém o cluster PostgreSQL operacional sem necessidade de intervenção manual do administrador.
Como é estruturado um cluster Patroni
O cluster Patroni é composto por vários componentes que interagem entre si:
- Primary (master) – o servidor principal do PostgreSQL, responsável pelas gravações.
- Replica (standby) – réplica(s) que recebem dados via replicação em fluxo.
- DCS (Distributed Configuration Store) – armazenamento externo de configuração e estado do cluster (por exemplo, Etcd, Consul ou ZooKeeper).
- Agentes Patroni – processos executados em cada nó que gerenciam o PostgreSQL e coordenam o trabalho por meio do DCS.
Cada nó no cluster possui seu próprio daemon Patroni, que:
- Monitora o estado do PostgreSQL.
- Consulta o DCS para saber quem é o líder atual (primary).
- Pode assumir o papel de primary se o servidor principal ficar indisponível.
Princípio de funcionamento do Patroni
O funcionamento do Patroni baseia-se no conceito de eleição de líder (leader election) via DCS.
- Um dos nós recebe a “liderança” – torna-se o primary.
- Os outros nós sincronizam seus dados com o primary por meio da replicação interna do PostgreSQL.
- Se o líder falhar (por exemplo, o servidor ficar inacessível ou o banco não responder), o Patroni executa um failover automático:
- Um novo líder é escolhido entre as réplicas disponíveis.
- O cluster atualiza as informações no DCS.
- Os aplicativos redirecionam as requisições para o novo primary (via HAProxy, PgBouncer ou outro software intermediário).
Assim, o Patroni garante tempo mínimo de inatividade e alta disponibilidade do banco de dados.
Recursos e vantagens do Patroni
- Failover automático A comutação entre nós ocorre automaticamente em caso de falha, sem intervenção do administrador.
- Integração com sistemas externos O Patroni suporta DCS (Etcd, Consul, ZooKeeper) para coordenar o estado do cluster.
- Configuração flexível de replicação É possível usar replicação síncrona ou assíncrona do PostgreSQL.
- REST API Cada nó expõe uma API para gerenciamento, monitoramento e integração com ferramentas externas.
- Suporte a balanceadores externos O Patroni integra-se facilmente com HAProxy ou PgBouncer para rotear conexões de clientes ao primary atual.
Exemplo de topologia do Patroni
Um esquema simples de cluster Patroni pode ser assim:
+------------------+
| HAProxy |
| (balancer) |
+--------+---------+
|
+---------+---------+
| |
+------+-----+ +-------+------+
| PostgreSQL | | PostgreSQL |
| (Primary) | | (Replica) |
+------+-----+ +-------+------+
| |
+----+----+ +----+----+
| Patroni | | Patroni |
+----+----+ +----+----+
| |
+---------+---------+
|
+------+------+
| Etcd / |
| Consul |
+-------------+Instalação e configuração do Patroni
O Patroni pode ser instalado via gerenciador de pacotes ou a partir do código-fonte:
pip install patroni[etcd]Exemplo mínimo de configuração (/etc/patroni.yml):
scope: postgres name: node1
restapi:
listen: 0.0.0.0:8008
connect_address: 192.168.1.10:8008
etcd:
host: 192.168.1.100:2379
postgresql:
listen: 0.0.0.0:5432
connect_address: 192.168.1.10:5432
data_dir: /var/lib/postgresql/data
authentication:
replication:
username: repl
password: repl_pass
superuser:
username: postgres
password: admin_pass
parameters:
max_connections: 100
shared_buffers: 256MB
Após configurar todos os nós e iniciar o Patroni, o processo de coordenação e replicação ocorrerá automaticamente.
Conclusão: dicas práticas
O Patroni não é apenas uma camada sobre o PostgreSQL — é um sistema completo de gerenciamento do ciclo de vida de um cluster. Ele combina replicação, failover automático e configuração dinâmica, tornando-se essencial em ambientes de produção onde o tempo de inatividade é inaceitável.
Tecnicamente, o Patroni atua como um “coordenador” entre os nós do PostgreSQL, sincronizando o estado via armazenamento distribuído (Etcd, Consul ou ZooKeeper). Isso permite:
- Monitorar a integridade dos nós – cada réplica envia periodicamente seu status ao DCS (Distributed Configuration Store);
- Eleger um líder – em caso de falha do nó principal, o sistema designa automaticamente um novo sem intervenção humana;
- Atualizar a configuração do cluster sem downtime – as mudanças são aplicadas dinamicamente via REST API do Patroni;
- Integrar com sistemas de orquestração – por exemplo, o operador Patroni para Kubernetes permite executar PostgreSQL altamente disponível em ambientes conteinerizados;
- Configurar o nível de sincronização das réplicas – escolhendo entre synchronous_mode e asynchronous_mode conforme o SLA de dados.
Para maior resiliência em produção, recomenda-se:
- Implantar pelo menos três nós PostgreSQL e três nós DCS (por exemplo, Etcd);
- Configurar HAProxy ou PgBouncer para rotear conexões de clientes;
- Realizar testes regulares de failover e backups dos arquivos WAL;
- Monitorar via Prometheus Exporter, incluído no Patroni.
O Patroni funciona muito bem com ferramentas como pgBackRest, Grafana, Ansible e Kubernetes, formando uma base confiável para infraestruturas modernas em nuvem.
FAQ
- É possível usar o Patroni sem Etcd ou Consul? Não. O Patroni requer um DCS (como Etcd, ZooKeeper ou Consul) para armazenar metadados e gerenciar a eleição de líder.
- É necessário um servidor separado para o DCS? Sim, o DCS deve ser implantado independentemente dos nós PostgreSQL para evitar ponto único de falha.
- O Patroni suporta replicação síncrona? Sim, é possível configurar réplicas síncronas com synchronous_mode: true.
- Como monitorar o cluster? Através da REST API (/patroni) ou ferramentas externas como Prometheus + Grafana.
- O Patroni pode ser executado em Docker? Sim, ambientes conteinerizados são oficialmente suportados — há imagens prontas e Helm Charts para Kubernetes.
