High availability

Ask for more than one copy, and the platform runs a primary with replicas.

You declareThe platform generates

compose.production.yaml

services:
  postgres:
    x-stackgres:
      instances: 3 # (1)!
      replication:
        mode: async # (2)!

1. One primary and two replicas.
2. The default. A write is confirmed before the replicas have it.

Generated on every release. You never write this file or see it.

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: '0'
  labels:
    com.docker.compose.project: my-app
    com.docker.compose.service: postgres
  name: postgres
  namespace: my-app
spec:
  profile: production # (1)!
  postgres:
    version: '16'
    extensions:
    - name: pg_trgm
    - name: vector
  instances: 3 # (2)!
  replication:
    mode: async # (3)!

1. Each copy runs on a different node.
2. One primary and two replicas.
3. How a write is confirmed.

Behavior	Detail
Automatic failover	If the primary fails, a replica takes over in seconds. Nobody intervenes
Two addresses	postgres always reaches the primary. postgres-replicas reaches the replicas, read only
One node each	With the production profile, two copies never share a node
What a failover can lose	With async, the last confirmed writes may be lost. sync confirms a write when a replica has it

Your application keeps connecting to postgres. Send reads to postgres-replicas only if you want to. Open connections drop during a failover, and your application reconnects.

Three copies need three nodes

With the production profile, each copy needs its own node, and each one has its own disk, CPU, and memory. A cluster with fewer nodes leaves the extra copies waiting.