# HA Cluster

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

---

LLMS index: [llms.txt](/llms.txt)

---

[Patroni](https://patroni.readthedocs.io) 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](../addon/). 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](../addon/etcd/),
> [HAProxy](../addon/haproxy/)); this section links to them where relevant.

## Pages

| Page | What it covers |
|------|----------------|
| [Patroni HA](./ha/) | The `pg ha` command set: create, status, switchover/failover, pause, cross-host members, passwords, namespace & DCS layout |
| [Dynamic Configuration](./ha-dynamic/) | `pg ha edit-config` / `pg ha ctl` — the DCS-backed runtime config, and why it never recreates a container |
| [REST API](./ha-rest-api/) | The per-member Patroni REST API: health checks, leader redirects, what HAProxy probes |
| [Extensions in HA](./ha-extensions/) | Installing/removing PostgreSQL extensions across a cluster (rolling shared_preload_libraries changes) |
| [Cluster Backup](./ha-backup/) | `pg backup setup` + `pg ha snapshot` — stanza, WAL archiving to S3, cross-host trust |
| [Cluster Restore](./ha-restore/) | `pg ha restore` — cluster PITR via the custom-bootstrap mechanism, the leader-locality pre-check, the post-restore re-baseline |
| [Exec / psql](./ha-exec/) | `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](./ha-example-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](./ha-cert/) | `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](./ha-s3-storage/) | 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

```bash
# 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"
```

## Related

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

---

Section pages:

- [Patroni HA](/docs/ha-cluster/ha/): Run PostgreSQL high availability with Patroni as a pgcli HA mode — automatic failover, switchover, and a DCS-backed cluster
- [Patroni Dynamic Configuration](/docs/ha-cluster/ha-dynamic/): Reference for all dynamically configurable parameters stored in the DCS
- [Patroni REST API](/docs/ha-cluster/ha-rest-api/): Patroni REST API endpoints for health checks, monitoring, and cluster management
- [Extensions in HA Clusters](/docs/ha-cluster/ha-extensions/): Install and manage PostgreSQL extensions in Patroni-managed HA clusters
- [Patroni Cluster Backup](/docs/ha-cluster/ha-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](/docs/ha-cluster/ha-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](/docs/ha-cluster/ha-exec/): 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](/docs/ha-cluster/ha-example-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](/docs/ha-cluster/ha-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](/docs/ha-cluster/ha-s3-storage/): 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

---

Backlinks:

- [Addons](/docs/addon/)