Data Dynamics
Open Source

Patroni PostgreSQL HA

An open-source project that builds a highly available PostgreSQL cluster on Patroni, etcd, PgBouncer, and HAProxy with a single Ansible playbook run.

Apache License 2.0 · Open SourceGitHub Repository

SQL connections and cluster control

Application connections reach PostgreSQL through the VIP, HAProxy and PgBouncer. Patroni and etcd coordinate leadership through a separate control path.

SQL connections and cluster control — Diagram of components and execution boundaries: Choose an endpoint → Route and pool connections → Store and replicate → Coordinate leadership
01 Choose an endpoint → 02 Route and pool connections → 03 Store and replicate → 04 Coordinate leadershipSelect the diagram to zoom to its original size.
1.Choose an endpoint
Port 5000 on the shared VIP accepts read/write connections; port 5001 prefers replicas. Keepalived manages the VIP on an HAProxy host.
2.Route and pool connections
HAProxy checks Patroni /primary and /replica responses, then forwards connections to PgBouncer on port 6432 of the selected database host.
3.Store and replicate
PgBouncer connects to local PostgreSQL on port 5432. WAL streams from leader to replicas; SQL traffic does not pass through Patroni.
4.Coordinate leadership
Patroni on each database host manages leader state in etcd and controls local PostgreSQL promotion or demotion. Health checks and control use separate connections.

Defaults use asynchronous replication and route the read port to the leader when no healthy replica is available. Three etcd members require a quorum of two.

View GitHub documentation and code

From leader failure to reconnection

Follow the transition from an expired leader lease through election and health checks to application reconnection.

From leader failure to reconnection — Diagram of components and execution boundaries: Detect leader loss → Acquire the leader lock → Promote and reroute → Reconnect and verify
01 Detect leader loss → 02 Acquire the leader lock → 03 Promote and reroute → 04 Reconnect and verifySelect the diagram to zoom to its original size.
1.Detect leader loss
If the old leader cannot renew its etcd lease, the lease expires. HAProxy also removes the failed backend through health checks.
2.Acquire the leader lock
Patroni on an eligible replica acquires the etcd leader key. The transition depends on etcd quorum and replication state.
3.Promote and reroute
PostgreSQL is promoted on the new leader. When Patroni /primary returns 200, HAProxy forwards write connections to that host’s PgBouncer.
4.Reconnect and verify
The application opens a new connection to the same VIP:5000. Check roles and replication with patronictl and SQL; rejoining the old leader is a separate recovery step.

Default leader TTL is 30 seconds and the Patroni loop interval is 10 seconds. Recovery depends on state and configuration; changing database leaders does not necessarily move the VIP.

View GitHub documentation and code

Choose and provision the deployment topology

Separate etcd hosts or co-locate the stack on three servers, then verify the resulting cluster.

Choose and provision the deployment topology — Separated · Converged · Component roles · Automation
Separate etcd hosts or co-locate the stack on three servers, then verify the resulting cluster.Select the diagram to zoom to its original size.
1.Separated
Use three dedicated etcd hosts and at least two database hosts.
2.Converged
Co-locate the six components on three servers.
3.Component roles
Separate SQL routing, pooling, storage and leader coordination.
4.Automation
Configure inventory, provision services and verify routing and replication.

PostgreSQL 14–17 is documented; default 16. Failover may interrupt sessions. Synchronous replication and pgBackRest are optional.

View GitHub documentation and code

Get started on GitHub

The full playbooks and installation guide are open source and available in the repository.

View on GitHubContact us