Blocks · Databases

db/postgres

PostgreSQL with live failover. PostgreSQL replicas on their own volumes, streaming replication, and live promotion behind one VIP.

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

postgres.yaml
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.

KeyDefaultMeaning
replicationPasswordrequiredPassword 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).
superuserPasswordrequiredPassword 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).
port5432Port 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.
databaseappDatabase created on the first primary at bootstrap.
sharedBuffers256MBshared_buffers.
maxWalSenders10max_wal_senders. Keep it above the replica count, with headroom for pg_basebackup during a rejoin.
maxReplicationSlots10max_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

All block types · Fields every block shares