pg_replica

A PostgreSQL extension that gives a small cluster of vanilla Postgres nodes automatic, consensus-driven failover — full-cluster replication (tables, roles, DDL, everything) with a built-in Raft group and no external dependencies: no etcd, no Consul, no Kubernetes.

Replaces Patroni, CloudNativePG, pgActive and many more.

One job: keep a single leader elected and the data byte-identical across N nodes, and fail over automatically when the leader dies. Do that one job well.

The one idea

Don't reinvent replication. Postgres already ships physical (WAL) streaming replication, which copies everything byte-for-byte — heap, indexes, and the shared catalog pg_authid (i.e. roles/users and their SCRAM verifiers). That is exactly why physical replicas have the same roles as the primary, while logical replication / active-active (pgactive) do not.

pg_replica adds the only piece Postgres itself lacks: automatic leader election and failover, using an embedded Raft quorum instead of an external DCS.

Result: roles, DDL, and data stay consistent on every node, and a dead primary is replaced in seconds — with no human, no etcd, no Kubernetes.

Test

# Build dependencies

sudo apt-get update
sudo apt-get install -y \
  build-essential pkg-config libssl-dev \
  libreadline-dev zlib1g-dev flex bison \
  libxml2-dev libxslt-dev libxml2-utils xsltproc \
  ccache libclang-dev clang \
  iptables libfaketime
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup default stable
rustc --version

# test dependencies
cargo install --locked cargo-pgrx --version 0.18.1
cargo pgrx init
cd extension
cargo pgrx run pg18

CREATE EXTENSION pg_replica;

Run the whole test suite

One command builds the extension + test clients and runs every test (3-node clusters in /tmp, torn down between each):

bash scripts/run-all-tests.sh            # build, then run all tests + summary
bash scripts/run-all-tests.sh --no-build # skip the rebuild

Coverage (scripts/test-*.sh, each spins a real 3-node cluster):

Goals / non-goals

Goals

• Automatic failover on a 3- or 5-node cluster (Raft majority quorum).
• Full-cluster fidelity: roles, GRANTs, DDL, extensions, data — all replicated (free, via physical replication).
• Zero external coordination services (Raft is embedded).
• Lightweight: one .so extension + Postgres; no JVM, no Go control plane, no k8s.
• Safe by default: quorum-gated, fences the old primary, picks the most-advanced replica, rejoins the loser with pg_rewind.
• Operable from SQL: SELECT pg_replica.status();, pg_replica.failover(), etc.

Non-goals (v1)

• Sharding / horizontal write scale-out → that is Citus, a different axis.
• Connection pooling / proxy → recommend HAProxy or libpq multi-host (target_session_attrs=read-write). pg_replica only publishes who the primary is.
• Backups / PITR → recommend pgBackRest or wal-g.
• Logical / multi-master replication → out of scope by design.

Positioning (honest prior art)

The niche: embedded quorum (unlike pg_auto_failover's single monitor), no external DCS (unlike Patroni-etcd / Stolon), no Kubernetes (unlike CNPG), shipped as a plain Postgres extension. Closest existing thing is Patroni's raft DCS mode — pg_replica aims to be that idea, but native, in-process, and Rust-light.