Overview
Each replica runs on its own node with its own independent volume; PostgreSQL's streaming replication is the redundancy, not DRBD. A lease-gated controller built on the cluster's Raft lease picks the primary: the winner becomes primary, every other replica clones from it with pg_basebackup, and when the primary is lost a surviving replica is promoted live with pg_promote(), with no restart.
Clients use one VIP. Its load balancer routes only to the replica the controller marks primary, so a plain single-host connection string always reaches a writable primary.
- Shape
- Replicas, one volume each
- Reached at
- VIP routed to the primary
- Node package
pkgs.postgresql_18
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.postgresql_18, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: pg namespace: default spec: type: db/postgres replicas: 3 placement: antiAffinity: ANTI_AFFINITY_NODE resources: requests: cpu: 200m memory: 256Mi storage: - name: pgdata size: 10Gi replication: 1 # one independent volume per replica mountPath: /var/lib/postgresql-data config: port: 15432 database: app replicationPassword: <shared secret> superuserPassword: <shared secret> network: ports: - name: pg port: 5432 target_port: 15432 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 15432 period_seconds: 2
storage[0].replication must be 1: three replicas means three independent volumes, kept in sync by PostgreSQL itself.
$ expanse ctl block apply -f postgres.yaml --dry-run # validate only $ expanse ctl block apply -f postgres.yaml
Configuration
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
replicationPassword | required | Password of the internal replicator role standbys stream with. Standbys read it from a libpq passfile in a per-replica tmpfs directory, so it never reaches disk in plain text, postgresql.auto.conf or the block's log. Sealed: kept out of the stored block (block secrets). |
superuserPassword | required | Password of the postgres superuser over TCP. Local socket access, which the failover controller uses, needs none. Sealed: kept out of the stored block (block secrets). |
port | 5432 | Port for client and replication connections. Behind a VIP, use another port, such as the 15432 the deploy form sets, so the VIP can take 5432 on the same node. |
database | app | Database created on the first primary at bootstrap. |
sharedBuffers | 256MB | shared_buffers. |
maxWalSenders | 10 | max_wal_senders. Keep it above the replica count, with headroom for pg_basebackup during a rejoin. |
maxReplicationSlots | 10 | max_replication_slots; the controller creates one physical slot per standby. |
Using it
Connect to the VIP like any single PostgreSQL server:
$ PGPASSWORD=<superuserPassword> psql -h <VIP> -p 5432 -U postgres -d app
pg_hba.conf accepts password logins (scram-sha-256) from any address, so the two passwords are the only access control. Expanse's tests validate psql and libpq; other drivers and poolers are unverified.
Each replica's data directory is <mountPath>/pgdata. postgresql.conf is written once, at a replica's first bootstrap, so settings such as archive_mode can be added by hand on the primary and reloaded.
When a node fails
When the primary's node is lost, a surviving replica is promoted live and the VIP moves to it. Open connections break and must be re-established; an application retry loop against the same VIP picks up the new primary.
No acknowledged write is lost. synchronous_standby_names = 'ANY 1 (*)' holds each commit until at least one standby has it, so the promoted replica already has every write a client saw succeed. Expanse's VM tests run a tracked writer and pgbench through a hard primary kill and find every acknowledged transaction afterwards. The guarantee covers one standby: a second standby lagging at the same moment may not have every write.
The old primary, once back, rejoins as a standby on its own: it finds that another replica holds the primary lease, wipes its diverged data and re-clones from the new primary with a full pg_basebackup. A primary cut off by a network partition never acknowledges a write, and rejoins the same way when the network heals.
Limits
- Each rejoin is a full copy, not a
pg_rewind. - WAL archiving and a restore procedure are not configured by the block.
- Validated with
psql/libpq only.
Source
- docs/DATABASE.md: the Expanse guide this page follows.
- nix/blocks/db/postgres: the type's identity and JSON Schema.