Skip to content
SHC Docs

Step 3: Postgres across locations

New line, in development. Installed on a four-node test cluster built from shc next b43f0c168 (ce 5db649eb) on 2026-10-08: three nodes in location home, one in far. 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.sh
pgha/app.yaml
name: pgha
version: "16"
title: Postgres with streaming replicas
description: One primary and numbered streaming standbys, as a members group
category: development
license:
id: PostgreSQL
vars:
password@secret!: the postgres superuser password
replPassword@secret!: the password standbys use to stream from member 1
pgha/vars.yaml
password: "ref+vault://pgha_password?autogen" # made on first install, kept in the vault
replPassword: "ref+vault://pgha_repl_password?autogen"
pgha/compose.yaml
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.

pgha/bin/member.sh
#!/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 -eu
if [ "$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"
fi
exec 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 data
set -eu
psql -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.

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:

Terminal window
$ shc install /root/tutorial/pgha -s pgha -t rig -e prod --scale db=2@home,1@far
shc: [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.

Terminal window
chmod +x pgha/bin/member.sh pgha/initdb/10-replication.sh
# index.yaml on the repository's web server
api_version: v2
apps:
- 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
Terminal window
$ 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@far
installing stack "pgha"
pgha: starting
pgha: running
pgha: db-1 running
pgha: db-2 running
pgha: db-3 running
installed deployment "pgha"
$ shc ls -t rig -e prod
STACK TENANT ENV APP STATUS NODES
pgha rig prod pgha running far01, home01, home02

The 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.

Terminal window
$ 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|async
walreceiver|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|t
member_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 TABLE
written on member 1 at 2026-10-08 01:01:21.816571+00
INSERT 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 transaction

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:ro

Beside 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.

Terminal window
$ shc uninstall pgha -t rig -e prod -y
uninstalling stack "pgha"
pgha: uninstalling stack "pgha" on node far01, which holds it
pgha: uninstalling stack "pgha" on node home01, which holds it
pgha: uninstalling stack "pgha" on node home02, which holds it
pgha: taking the safety backup of stack "pgha"
pgha: taking stack "pgha" out of every node's service VIP table
pgha: tearing down stack "pgha"
pgha: removing the copy of stack "pgha" on node far01
pgha: removing the copy of stack "pgha" on node home02
uninstalled deployment "pgha"
pgha: removed with the deployment: config lanEnforcement

Next: Step 4: an app that uses Postgres through a plug.