HA Cluster on pgcli

Patroni HA

Mon, 01 Jan 0001 00:00:00 +0000

Patroni is the de-facto standard for PostgreSQL high availability: it manages each postmaster’s lifecycle, streams replication between members, and performs automatic failover when the leader is lost. pgcli exposes Patroni as a distinct mode — pg ha — rather than folding it into the plain pg instance path.

This is a separate mode, not an addon subcommand. Patroni (not pgcli) owns the PostgreSQL process. pg ha members do not appear in cfg.Instances, share no instance lifecycle code, and are not created by pg create. The one thing it borrows from the addon system is the etcd DCS.

Patroni Dynamic Configuration

Mon, 01 Jan 0001 00:00:00 +0000

These parameters are stored in the DCS (etcd) under /service/<scope>/config and applied to every member of the cluster. Modify them with pg ha edit-config:

pg ha edit-config app -- -s loop_wait=5
pg ha edit-config app -- -s 'postgresql.parameters.max_connections=200'
pg ha edit-config app --show          # view current config

Reference: Patroni official docs, Pigsty dynamic config.

bootstrap.dcs is one-time. The bootstrap.dcs block in patroni.yml only takes effect when the first member of a scope bootstraps the cluster. Once Patroni writes the config into the DCS, subsequent changes to bootstrap.dcs in the YAML file are completely ignored — even on re-install (pg ha create). Re-running pg ha create does not re-read bootstrap.dcs — Patroni sees the existing config key in the DCS and uses it directly.

Patroni REST API

Mon, 01 Jan 0001 00:00:00 +0000

Patroni exposes an HTTP REST API on each member, providing health check endpoints (for load balancers and Kubernetes probes), monitoring data (including Prometheus metrics), and cluster management operations.

Reference: Patroni official docs, Pigsty REST API.

Finding the REST API

Each member’s REST API port is assigned automatically by pgcli and stored in pg.yaml under addons.patroni.<scope>.members.<name>.restapi_port. The port is also embedded in the rendered patroni.yml as restapi.connect_address.

# Find REST API ports
pg ha status app          # shows pg= and rest= ports for each member

Authentication

pgcli enables basic-auth on the REST API (username postgres, auto-generated password). But authentication is method-based, not blanket:

Extensions in HA Clusters

Mon, 01 Jan 0001 00:00:00 +0000

Installing PostgreSQL extensions in a Patroni-managed HA cluster is fundamentally different from a single-node instance. This page explains why, and walks through the pg ha extension command subtree that handles it.

Why not `pg extension install`?

The single-node flow (pg extension install <instance> <ext>) works by:

Building a -ext derived image with Pigsty packages
Stopping and recreating the container from the new image
Editing postgresql.conf to set shared_preload_libraries
Running CREATE EXTENSION inside the container

In a Patroni cluster, steps 2-4 all break:

Patroni Cluster Backup

Mon, 01 Jan 0001 00:00:00 +0000

This page walks the complete procedure for backing up a Patroni HA cluster: getting the backup infrastructure up with pg backup setup, taking full/incr/diff backups with pg ha snapshot, and one operational pitfall — when a replica’s Replay LSN stalls and pg ha status shows members disagreeing on LSN, how to pull it back with patronictl reinit. Command and mechanism details live in Patroni HA and Backup; this page strings them into a path you can run end to end.

Patroni Cluster Restore

Mon, 01 Jan 0001 00:00:00 +0000

This page is the restore-side companion to Patroni Cluster Backup. Once a cluster has a stanza with WAL archiving (pg backup setup + pg ha snapshot), pg ha restore brings the whole cluster back to a point in time — the Patroni counterpart of the single-instance pg restore. It walks the mechanism (why a cluster PITR is not just pgbackrest restore), the safety pre-check on where the leader lives, an end-to-end runbook, and the re-baseline steps that must follow. Command/flag details also live in Restore → Patroni cluster; this page strings them into a procedure you can run.

HA Exec / psql

Mon, 01 Jan 0001 00:00:00 +0000

pg ha exec and pg ha psql are the direct way to run SQL against a Patroni cluster. They are the cluster-side twins of the single-instance pg exec and pg psql: you name a scope, they resolve the target and connect. No --dsn to hand-assemble, no member container to podman exec into, and — because the connection is plain TCP — a leader or replica on another host is just as reachable as a local one.

Example: HA Cluster with a Self-CA MinIO

Mon, 01 Jan 0001 00:00:00 +0000

This page is a worked example, run end to end and verified: create a Patroni HA cluster, stand up a MinIO addon that serves a bring-your-own domain certificate (a self-signed CA of our own making — the same shape as a public-CA or corporate-CA cert, just without buying one), and point the cluster’s pgBackRest backups and WAL archiving at it. Every command below is a real one from the run; only hostnames, ports, passwords, and the certificate material are genericized.

Generating a Certificate — pg cert

Mon, 01 Jan 0001 00:00:00 +0000

pg cert mints a self-signed certificate — its SubjectAltNames covering any mix of DNS names and IP addresses you ask for — for any place you need TLS without going through a CA: a dev or test server, an internal endpoint, a service whose clients you control. The certificate it writes is a normal TLS server leaf, usable anywhere.

The use this docs tree exercises is pgBackRest’s S3 path: a Patroni cluster’s backups push to an S3 store (MinIO or silo, typically) that must serve TLS — pgBackRest refuses plaintext S3 — and pgcli’s MinIO/silo addons can serve a bring-your-own certificate (pg addon install minio --tls-cert ... --tls-key ...). The quickest way to get a cert to try that with is pg cert:

S3 Storage High Availability

Mon, 01 Jan 0001 00:00:00 +0000

A Patroni cluster survives a node loss; the S3 repository its WAL and backups stream into must survive one too, or “high availability” quietly ends at the backup path. The store is a MinIO or silo addon (the two are interchangeable — silo is Pigsty’s MinIO fork with the same feature surface). Two fault domains matter, and they are orthogonal:

Fault	Who absorbs it
A disk dies inside a node	the drive-level EC under SNMD/MNMD, or the storage layer under MinIO’s data directory (ZFS)
A node dies entirely	MinIO’s own erasure coding (EC) across hosts

This page records the shapes pgcli supports for combining the two, and how to pick among them.

HA Cluster on pgcli

Patroni HA

Patroni Dynamic Configuration

Patroni REST API

Finding the REST API

Authentication

Extensions in HA Clusters

Why not pg extension install?

Patroni Cluster Backup

Patroni Cluster Restore

HA Exec / psql

Example: HA Cluster with a Self-CA MinIO

Generating a Certificate — pg cert

S3 Storage High Availability

Why not `pg extension install`?