Patroni & etcd/Consul

Patroni 3.x automates PostgreSQL leader election, failover, and configuration management. It stores cluster state in a distributed config store (DCS): etcd or Consul.

Recipe

Three-node Patroni cluster with etcd quorum and PostgreSQL 18.4.

# /etc/patroni/patroni.yml (snippet)
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

# Start Patroni on each node
sudo systemctl enable --now patroni
 
# Cluster status
patronictl -c /etc/patroni/patroni.yml list

When to reach for this: Self-hosted PostgreSQL HA with automated failover and API-driven health checks.

Working Example

Deploy etcd, bootstrap Patroni, verify failover candidate:

# etcd 3-node cluster health
etcdctl endpoint health --endpoints=https://10.0.2.1:2379,https://10.0.2.2:2379,https://10.0.2.3:2379
 
# Patroni cluster view
patronictl -c /etc/patroni/patroni.yml list

-- On any member via Patroni-managed endpoint
SELECT pg_is_in_recovery();

# Controlled switchover (not emergency failover)
patronictl -c /etc/patroni/patroni.yml switchover --master pg1 --candidate pg2 --force

What this demonstrates:

• etcd provides quorum for leader lock (/service/prod-pg18/leader).
• Patroni manages postgresql.conf, recovery config, and promotion.
• patronictl switchover exercises planned leader change with lag guard (maximum_lag_on_failover).

Deep Dive

DCS Options

Patroni Responsibilities

• Leader key acquisition and renewal in DCS
• Replica reconfiguration after failover (primary_conninfo updates)
• Optional synchronous mode management
• REST API on port 8008 for health and orchestration
• Integration with callbacks (reload HAProxy, notify PgBouncer)

Key DCS Settings

Gotchas

• Two-node etcd - No quorum; split brain risk on partition. Fix: Odd count (3 or 5) etcd nodes.
• Patroni without watchdog - Rare double-primary if fencing fails. Fix: Enable watchdog on Linux hosts.
• maximum_lag_on_failover too high - Promote stale replica, large RPO. Fix: Set based on measured byte lag SLA.
• Consul token ACL misconfig - Patroni cannot write leader key. Fix: Test patronictl list after ACL changes.
• Manual pg_ctl promote bypassing Patroni - Cluster state desync. Fix: Always use patronictl failover or switchover.

Alternatives

FAQs

Related

• HA Basics - RTO/RPO context
• Split-Brain Prevention - fencing and quorum
• Connection Proxies - HAProxy integration
• Streaming Replication Basics - replica setup

Stack versions: This page was written for PostgreSQL 18.4 (stable 18, maintenance 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, and PostGIS 3.5+.