Skip to content
SHC Docs

A simple Postgres

The nginx page installed a directory. This one names a catalogue app: postgres. The deployment name is db, so the app name and the deployment name are different.

home01
$ shc install postgres -s db
installing deployment "db"
[db] Healthy 1/1
✔ postgres-1 healthy
✔ installed deployment "db"
$ shc ls
STACK TENANT ENV APP STATUS NODE
db prod prod postgres running home01
web prod prod /root/learn/nginx running home01
$ shc exec -s db -S postgres-1 -- psql -U postgres -d postgres -tAc 'select version()'
PostgreSQL 16.14 - Percona Distribution on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.2.1 20250110 (Red Hat 14.2.1-12), 64-bit

shc exec runs a command inside a service. -s db selects the deployment; -S postgres-1 selects its first member service. The shipped app has one Postgres member.

A catalogue app is a directory too. SHC ships postgres on every node, and these are its files. You read them; you do not write them.

home01
$ ls -1 /usr/lib/shc/apps/postgres
app.yaml
backup.yaml
bin
clear-read-only.job.yaml
compose.yaml
database.vapp.yaml
database.vplug.yaml
database.vsocket.yaml
database.vvars.yaml
handover.job.yaml
icon.svg
migrations
pg-upgrade.job.yaml
pg-upgrade-stage.job.yaml
pmm.plug.yaml
postgres.exporter.yaml
postgres.socket.yaml
quiesce.job.yaml
README.md
resume.job.yaml
settle.job.yaml
switch-back.job.yaml
tests
vars.yaml

Its app.yaml declares the variables an install can set. @secret keeps a value in the vault, and ! makes a variable required:

home01
$ grep -A9 '^vars:' /usr/lib/shc/apps/postgres/app.yaml
vars:
postgres:
username@string: superuser username
password@secret: superuser password
database@string: initial database name
adopt@string: databases a consumer that moves its plug here from another provider may bind as they stand, space separated
hostAuthMethod@string: pg_hba auth method for host (TCP) connections; applied at first initdb only. Existing data dirs keep their pg_hba.conf
majorVersion@string: PostgreSQL MAJOR version this package ships; must be bumped in lockstep with images.postgres (the guard refuses to start if they disagree)
maxConnections@integer: 'max_connections for the server, from 25 to 10000; 0 (the default), or any value outside that range, leaves PostgreSQL''s own 100. Every app that plugs into this stack holds a pool of its own, so a busy shared stack needs more. Changing it restarts the server. At two or more members a formation starts with it, so a scale-up from one member keeps it; after that Patroni keeps max_connections in etcd, and changing the var on a running formation does not reach it'
synchronous:

Its vars.yaml gives them values. ref+vault://password?autogen makes a password and keeps it in the vault, which is why the install above asked for none:

home01
$ grep -A3 '^postgres:' /usr/lib/shc/apps/postgres/vars.yaml
postgres:
username: postgres
password: "ref+vault://password?autogen"
database: postgres

The files you write for your own apps on later pages take the same shape. See App definition and Variables.

Install another copy under a name of its own.

home01
$ shc install postgres -s db2
installing deployment "db2"
[db2] Healthy 1/1
✔ postgres-1 healthy
✔ installed deployment "db2"
$ shc ls
STACK TENANT ENV APP STATUS NODE
db prod prod postgres running home01
db2 prod prod postgres running home01
web prod prod /root/learn/nginx running home01
$ shc exec -s db2 -S postgres-1 -- psql -U postgres -d postgres -tAc 'select 1'
1

The app is the same; db2 has its own containers, its own volume and its own password in the vault.

Read Underneath the simple Postgres before going on; it reads what this page left running.

Next: A Postgres socket.