Patroni manages PostgreSQL high availability with automated failover and cluster management. Among its features is the standby cluster, which is built on cascading replication: one node sets up as standby leader and behaves as the leader inside the standby cluster while actually replicating from the primary Patroni cluster. The remaining nodes replicate from that standby leader.

Why deploy a standby cluster

  • Geographic redundancy and disaster recovery: if the whole primary cluster is lost to a data center failure or infrastructure outage, the standby cluster can be promoted to primary.
  • Controlled migrations: moving a cluster to new hardware, another data center or another cloud provider with minimal downtime.
  • Read scaling in another region: applications can run read operations against the standby cluster, cutting latency to the primary.
  • Testing: disaster recovery drills, failover simulations and backup validation without touching the production primary.

Requirements and preparation

A healthy primary Patroni cluster must already exist. Several other conditions apply before the standby cluster is built:

  • For the basebackup create_replica_method, Patroni expects postgresql.conf or postgresql.conf.backup in the PGDATA directory on the remote primary. Standby leader bootstrap fails without it and so will the bootstrap of the other nodes; on distributions such as Debian that keep the file elsewhere, copying it into PGDATA is the operator's responsibility.
  • If primary_slot_name is set, the matching replication slot must be created manually — Patroni does not create a replication slot on the primary for a standby cluster. When use_slots is enabled, the permanent replication slots feature keeps the slot across switchover or failover.
  • standby_cluster.hosts needs either a single endpoint (VIP) or a comma-separated list of all primary cluster hosts.
  • New pg_hba rules for the standby nodes must be added on the primary cluster. Add them for every standby node, not just the designated standby leader, so switchover or failover inside the standby cluster stays clean.

After the changes are applied, a replication slot named my_standby_cluster_slot exists and pg_hba entries cover all standby nodes. The demonstration source cluster runs on a RHEL-based distribution, so postgresql.conf already sits in PGDATA and was left there. standby_cluster.hosts is set to '192.168.122.237,192.168.122.93,192.168.122.128', and the slot is still inactive on the primary leader until the standby cluster is bootstrapped.

Bootstrapping the first standby node

Three points matter in the first node's configuration. The primary cluster is named pgcluster, and the standby cluster reuses that name, which is safe only because the standby cluster has its own independent etcd cluster — the HA control planes stay isolated. If an etcd instance is shared between primary and standby, the scope must differ or a separate namespace must be used. The username/password pairs for replication and rewind under postgresql.authentication must match those on the primary exactly, or bootstrap or rewind will fail. Local pg_hba rules let the standby nodes connect to each other; if the current primary is to be turned into a standby after the standby cluster is promoted, those rules have to be written with that in mind.

With all standby nodes configured, the Patroni service is started on each of them. The standby leader bootstraps from the remote primary, while the replica bootstraps from the standby leader. The slot my_standby_cluster_slot is then active on the primary leader.

Behaviour during switchover

A switchover inside the primary cluster leaves the primary healthy and the replication slot intact: with the permanent replication slot feature, Patroni maintains it across switchover and failover automatically, so the standby cluster keeps replicating without any interruption after the primary's leader changes. A switchover inside the standby cluster itself can be tested the same way.

Promoting the standby cluster

Before promotion, confirm that both clusters are fully synchronized by comparing the "Receive and Replay LSN" values in patronictl list output on both sides. The comparison is meaningless while writes are landing on the primary, so a short downtime with the application stopped is preferable. The sequence is:

  1. Schedule a short maintenance window.
  2. Stop application traffic and remove the VIP from the primary cluster.
  3. Compare "Receive and Replay LSN" for both clusters.
  4. Once the standby cluster is ready, run the promotion command on one of its nodes.
  5. After confirming the promotion, assign the VIP to the new primary Patroni cluster.

The application can then be restarted.

Standby clusters give PostgreSQL environments a synchronized secondary that recovers quickly from major infrastructure failures with minimal downtime and data loss, and they serve controlled migrations, cross-region read scaling and operational testing without disturbing the production primary.