HA Cluster

Patroni high-availability clusters with pgcli — pg ha commands, dynamic configuration, REST API, extensions, cluster backup and restore, direct SQL

Patroni is the de-facto standard for PostgreSQL high availability: it owns each postmaster’s lifecycle, streams replication between members, and performs automatic failover when the leader is lost. pgcli exposes Patroni as its own top-level command — pg ha — a distinct mode rather than a plain pg instance or an addon installed with pg addon install.

Note on placement. Patroni pages used to live under Addons. They are listed here as a standalone HA Cluster section because pg ha is not installed via the addon system — the addon index only mentions it for discovery. The etcd DCS and the HAProxy load balancer remain addon pages (etcd, HAProxy); this section links to them where relevant.

Pages

Page	What it covers
Patroni HA	The `pg ha` command set: create, status, switchover/failover, pause, cross-host members, passwords, namespace & DCS layout
Dynamic Configuration	`pg ha edit-config` / `pg ha ctl` — the DCS-backed runtime config, and why it never recreates a container
REST API	The per-member Patroni REST API: health checks, leader redirects, what HAProxy probes
Extensions in HA	Installing/removing PostgreSQL extensions across a cluster (rolling shared_preload_libraries changes)
Cluster Backup	`pg backup setup` + `pg ha snapshot` — stanza, WAL archiving to S3, cross-host trust
Cluster Restore	`pg ha restore` — cluster PITR via the custom-bootstrap mechanism, the leader-locality pre-check, the post-restore re-baseline
Exec / psql	`pg ha exec` / `pg ha psql` — run SQL against the leader or any member directly, no dsn, no container exec
Example: HA + self-CA MinIO	A verified end-to-end walkthrough: a cluster backed up to a MinIO serving a bring-your-own cert, in a fully isolated second environment
Generating a Certificate	`pg cert` — self-signed cert with DNS and IP SANs for any TLS you need without a CA (dev/test servers, an internal endpoint, or a MinIO serving a bring-your-own cert): its flags, and how the single self-signed leaf acts as its own trust anchor
S3 Storage High Availability	Making the MinIO/silo repo itself fault-tolerant: the SNSD and MNSD modes pgcli exposes and why only those two, plus ZFS under the data directory — single-host raidz, per-node pools in a distributed cluster, heterogeneous nodes

The typical path

# one host: bootstrap a cluster (on an installed etcd addon member)
pg ha create app --member node1 --etcd m1
pg ha create app --member node2 --etcd m1

# other hosts register their members with the same password set
pg ha passwords app --file app-passwd.yml
ssh other-host
pg ha create app --member node3 --advertise-host 10.0.0.12 \
    --etcd-endpoints 10.0.0.9:2379 --passwords-file app-passwd.yml

# run SQL directly — the leader is resolved from the DCS
pg ha exec app "SELECT version()"
pg ha psql app

# back it up and be able to go back in time
pg backup setup --s3-endpoint ...
pg ha snapshot create app --type full
pg ha restore app --time "2026-08-26 15:30:00+00"

Addons: etcd (the DCS), HAProxy (a stable client endpoint with optional read/write split), MinIO (the S3 repo the backups live in)
Restore → Patroni cluster for PITR basics shared with single-instance restores
Failover: Replica Promotion for the non-Patroni, single-replica promotion path (pg replica)
Namespace Isolation — scopes, stanzas, and container names are namespace-prefixed

Patroni HA

Run PostgreSQL high availability with Patroni as a pgcli HA mode — automatic failover, switchover, and a DCS-backed cluster

Patroni Dynamic Configuration

Reference for all dynamically configurable parameters stored in the DCS

Patroni REST API

Patroni REST API endpoints for health checks, monitoring, and cluster management

Extensions in HA Clusters

Install and manage PostgreSQL extensions in Patroni-managed HA clusters

Patroni Cluster Backup

pgBackRest backups for a Patroni HA cluster: backup setup, S3 repository and WAL archiving, pg ha snapshot operations, and reinit when a replica’s LSN is stuck

Patroni Cluster Restore

Point-in-time recovery (PITR) for a Patroni HA cluster with pg ha restore: the custom-bootstrap mechanism, the leader-locality pre-check, the end-to-end runbook, and the post-restore re-baseline steps

HA Exec / psql

Run SQL against a Patroni HA cluster with pg ha exec and pg ha psql: zero-config leader resolution from the DCS, no hand-assembled dsn, no entering a member container, and read-only or cross-host targets via –member

Example: HA Cluster with a Self-CA MinIO

A complete, verified end-to-end walkthrough: a single-member Patroni cluster backed up to a MinIO addon serving a bring-your-own (self-signed) domain certificate, run in a fully isolated pgcli environment

Generating a Certificate — pg cert

pg cert mints a self-signed certificate with DNS and IP SubjectAltNames for any TLS you need without a CA — dev/test servers, internal endpoints, and a MinIO serving a bring-your-own TLS certificate. Its flags, what it writes (a single self-signed leaf, not a chain), and how it acts as its own trust anchor

S3 Storage High Availability

Making the MinIO/silo object store behind pgBackRest highly available: the four deployment modes pgcli exposes (SNSD/SNMD/MNSD/MNMD), how native multi-drive compares to a ZFS layer for disk redundancy, and the two paths for a distributed cluster whose nodes each hold several disks

HA Cluster

Pages

The typical path

Related