Step 3: Postgres across locations
New line, in development. Installed on a four-node test cluster built from shc next
b43f0c168(ce5db649eb) on 2026-10-08: three nodes in locationhome, one infar. The output below is that run’s, trimmed, except the path-install refusal, which is a 2026-10-03 run’s.
Step 2’s Postgres is one server. Here you write an app with one primary and two standbys that stream from it. The three copies are not interchangeable, since member 1 takes writes and the others follow it, so they are a group, not replicas. Each member gets its own data volume and a location.
pgha/ app.yaml vars.yaml compose.yaml bin/member.sh initdb/10-replication.shname: pghaversion: "16"title: Postgres with streaming replicasdescription: One primary and numbered streaming standbys, as a members groupcategory: developmentlicense: id: PostgreSQL
vars: password@secret!: the postgres superuser password replPassword@secret!: the password standbys use to stream from member 1password: "ref+vault://pgha_password?autogen" # made on first install, kept in the vaultreplPassword: "ref+vault://pgha_repl_password?autogen"services:{% members "db", default=3, max=5 as m %} db-{{ m.n }}: # db-1, db-2, db-3 image: postgres:16-alpine entrypoint: ["sh", "/opt/pgha/member.sh"] environment: MEMBER: "{{ m.n }}" # the member's number, stable for its life MEMBER_LOCATION: "{{ m.location }}" # the location --scale gave it POSTGRES_PASSWORD: "{{ vars.password }}" REPL_PASSWORD: "{{ vars.replPassword }}" PGDATA: /var/lib/postgresql/data/pgdata volumes: - data-{{ m.n }}:/var/lib/postgresql/data # one volume per member; SHC declares data-1..3 - ./bin:/opt/pgha:ro - ./initdb:/docker-entrypoint-initdb.d:ro expose: - "5432" healthcheck: test: ["CMD", "pg_isready", "-U", "postgres"] interval: 10s retries: 12 deploy: resources: limits: cpus: "0.5" memory: 256M{% endmembers %}The members block is the whole group: SHC renders its body once per member. Nothing in it says which member is the primary; the app decides that from MEMBER.
#!/bin/sh# Member 1 is the primary. Every other member, on its first start, clones# member 1 with pg_basebackup -R and then runs as a streaming standby.set -euif [ "$MEMBER" != 1 ] && [ ! -s "$PGDATA/PG_VERSION" ]; then until pg_isready -q -h db-1 -U postgres; do sleep 2; done mkdir -p "$PGDATA" PGPASSWORD="$REPL_PASSWORD" pg_basebackup -h db-1 -U replicator \ -D "$PGDATA" -R -X stream -C -S "member_$MEMBER" chmod 0700 "$PGDATA"fiexec docker-entrypoint.sh postgres -c wal_level=replica -c hot_standby=on#!/bin/sh# pgha/initdb/10-replication.sh, executable: the image runs it once, when member 1 initialises its dataset -eupsql -v ON_ERROR_STOP=1 -U postgres -c "create role replicator with replication login password '$REPL_PASSWORD'"echo "host replication replicator all scram-sha-256" >>"$PGDATA/pg_hba.conf"A standby reaches the primary as db-1, the service name, because members are ordinary services of one deployment. This app has no failover: if member 1 is lost, promoting a standby is your step. Patroni-style failover is the app’s work, not the group’s.
Install it from a repository
Section titled “Install it from a repository”With members requested outside the source node’s location, a directory install is held to that node and cannot satisfy the placement. The earlier run reported:
$ shc install /root/tutorial/pgha -s pgha -t rig -e prod --scale db=2@home,1@farshc: [X409179PLCPND] rig/pgha/prod is pending, no node fits it now: home02 outside_fence: outside fence node:home01 at deploy:rig:pgha:prod; home01 outside_fence: --scale puts db-3 ordinal 0 in location:incus/far; ...A directory exists on one node only, so a path install fences its deployment to that node (shc constraint ls shows the constraint, recorded through packageLocality and the admission gate). A member asked for in far then has nowhere to go. Serve the app from a repository instead: an index.yaml naming a .app archive (the directory, tarred and gzipped) and its sha256 digest, over HTTP.
Make both scripts executable before creating the archive. Replace the example repository URL and digest below with your own. The digest shown is that of the archive this run packed from the files on this page; an archive you pack yourself has its own.
chmod +x pgha/bin/member.sh pgha/initdb/10-replication.sh# index.yaml on the repository's web serverapi_version: v2apps: - name: pgha description: Postgres, one primary and numbered streaming standbys as a members group (SHC-1390 tutorial step 3) category: development versions: - version: "16" archive: pgha-16.app digest: sha256:55f1cc327d0d04b8cc45da39b3ab41bcd1a0c9f0f08bc6ba491d072cc4eaabba$ shc repo add rig http://repo.example.com:8099/index.yaml -t rig # once per tenant$ shc repo sync rig -t rig # after each new archive$ shc install pgha -s pgha -t rig -e prod --scale db=2@home,1@farinstalling stack "pgha"pgha: startingpgha: runningpgha: db-1 runningpgha: db-2 runningpgha: db-3 runninginstalled deployment "pgha"$ shc ls -t rig -e prodSTACK TENANT ENV APP STATUS NODESpgha rig prod pgha running far01, home01, home02The older spelling --scale db=home:2,far:1 is refused (X400225SCLOLD).
--scale db=2@home,1@far asks for two members in home and one in far. The cluster’s locations are paths under the provider (incus/home, incus/far), and home names the leaf. Members keep their numbers for life. Scaling with counts per location keeps each member where it is: --scale db=3@home,2@far adds members 4 and 5 and leaves 1 to 3 in place. A plain count does not: --scale db=5 keeps members 1 to 3 and their volumes but clears every member’s location (ce core/pod/members.go, ResolveMembers). See Groups: Locations.
Check the replication
Section titled “Check the replication”$ shc exec -s pgha -t rig -e prod -S db-1 -- psql -U postgres -tAc "select application_name, state, sync_state from pg_stat_replication order by 1"walreceiver|streaming|asyncwalreceiver|streaming|async$ shc exec -s pgha -t rig -e prod -S db-1 -- psql -U postgres -tAc "select slot_name, active from pg_replication_slots order by 1"member_2|tmember_3|t$ shc exec -s pgha -t rig -e prod -S db-1 -- psql -U postgres -tAc "create table if not exists notes (id serial primary key, body text); insert into notes (body) values ('written on member 1 at ' || now()) returning body"CREATE TABLEwritten on member 1 at 2026-10-08 01:01:21.816571+00INSERT 0 1$ shc exec -s pgha -t rig -e prod -S db-3 -- psql -U postgres -tAc "select body from notes order by id desc limit 1"written on member 1 at 2026-10-08 01:01:21.816571+00$ shc exec -s pgha -t rig -e prod -S db-3 -- psql -U postgres -tAc "insert into notes (body) values ('x')"ERROR: cannot execute INSERT in a read-only transactionWhat SHC wrote, and where it runs
Section titled “What SHC wrote, and where it runs”Member 3’s service in the rendered compose.yaml, trimmed (a 2026-10-03 render; the fabric address differs from run to run):
db-3: environment: MEMBER: "3" MEMBER_LOCATION: incus/far POSTGRES_PASSWORD: <the value> networks: __shc_fabric: {ipv4_address: 10.128.2.137} default: aliases: [prod.db-3.pgha] # <environment>.<service>.<stack> volumes: - /var/lib/shc/deployments/rig/pgha/prod/mounts/data-3:/var/lib/postgresql/data - /var/lib/shc/deployments/rig/pgha/prod/files/bin:/opt/pgha:ro - /var/lib/shc/deployments/rig/pgha/prod/files/initdb:/docker-entrypoint-initdb.d:roBeside it SHC wrote one replica project per member, replicas/db-1-r0 to db-3-r0, labelled with the member’s group, number and pod (shc.group: db, shc.member: "3", shc.pod: db-3).
In this run each member ran on a node of its own: db-1 on home01, db-2 on home02, db-3 on far01. A repository install passes each member’s admission binding to replicaPlacer; the render finishes its project for that node, and that node’s runner starts it (SHC-1426). Placement prefers different nodes when they fit. shc doctor check pods.replica-projects reports whether a node runs replica projects.
An update keeps each member on the node its live assignment row names (heldReplicas, SHC-1628), and a failed-over member is finished on its new node from the leader’s stored render (SHC-1616). See Groups: where members run for what renders where. shc ls names every node the deployment runs on, and shc status -s pgha -t rig says which location each member holds.
On a node without a volume provider, each data-N is a directory under the deployment’s mounts/. A provider may provision a block volume instead. A replica with a local volume is pinned to its node (ce core/placement/movability.go): SHC does not move a member and leave its data behind.
Remove it
Section titled “Remove it”$ shc uninstall pgha -t rig -e prod -yuninstalling stack "pgha"pgha: uninstalling stack "pgha" on node far01, which holds itpgha: uninstalling stack "pgha" on node home01, which holds itpgha: uninstalling stack "pgha" on node home02, which holds itpgha: taking the safety backup of stack "pgha"pgha: taking stack "pgha" out of every node's service VIP tablepgha: tearing down stack "pgha"pgha: removing the copy of stack "pgha" on node far01pgha: removing the copy of stack "pgha" on node home02uninstalled deployment "pgha"pgha: removed with the deployment: config lanEnforcement