A backup and an export
A backup copies a deployment’s volumes into the cluster’s backup repository,
and the app says which volumes matter. Add a backup.yaml to notes on
home01 and replace its app.yaml with this one, which adds two hooks.
include: - pgdataname: notesversion: "1.0.0"title: Notesdescription: A Postgres that keeps notescategory: databaselicense: id: PostgreSQLvars: password@secret!: the postgres user's passwordhooks: post_install: - schema pre_backup: - stop: [postgres] post_backup: - start: [postgres]include lists the volumes worth backing up. A backup copies pgdata, and a
move must carry it. A volume the file doesn’t list is scratch, never backed
up. See backup.yaml.
pre_backup stops postgres before the backup copies the volume and
post_backup starts it again, so the copy is of a database at rest
(Lifecycle hooks).
shc update reads the app again, so placed takes the new files.
$ shc update placedupdating deployment "placed"[placed] Healthy 1/1✔ postgres healthysource: /usr/share/shc/apps/notesplaced: changed: app package apppkg-v1:9f7e48404c4daf470cf8941aa2505cca26c45cdefb8077c1ebf2ea4cd18ec700 -> apppkg-v1:2b75857dd2114aaabfac43cdb1905c03c25cfc0f45b890b0fd62aa76e61e431e read from /usr/share/shc/apps/notesthe rollout of prod/placed/prod to v1:sha256:760d7bf5b3077b4c8edc2fe6f7df54a60276c60bdf683603907d6bbc880b4743 finishedshc init made the repository’s key and sealed it in the vault, but it set
no repository. Here the repository is a directory on home01’s disk. On a
cluster of several nodes each node opens its own repository at that path, so
a backup stays on the disk of the node that took it.
$ shc config set backup.repo /var/backups/shc/repo --scope globalKEY VALUE SCOPEbackup.repo /var/backups/shc/repo globalGive placed a row to keep, back it up under the name kept and check
the backup by that name.
$ shc exec -s placed -S postgres -- psql -U postgres -c "insert into notes values ('kept by the backup')"INSERT 0 1$ shc backup create placed --name kept[placed] Complete 3/3✔ validate the request✔ back up✔ record the backup✔ created backup "20261106T174709Z_576448b494ed0d0b" named "kept"$ shc backup ls -s placedID STATUS SIZE BYTES TIMESTAMP POINT IN TIME ENCRYPTION NAME TENANT STACK ENVIRONMENT DATA SCOPE LOCATION20261106T174709Z_576448b494ed0d0b completed 29731350 2026-11-06 17:47:27 assured restic kept prod placed prod unknown restic:/var/backups/shc/repo:33803feda92f87820c999d82d21e597b7c6892e1fd06ce01b4d67df88c596bff$ shc backup verify kept -s placed✔ checked backup "20261106T174709Z_576448b494ed0d0b": the snapshot is present in the repository; its sealed container's member table accounts for all 29731350 bytes the repository records; its in-repo manifest reads back and names this backup; it holds 1 data subject: pgdata, totalling 29703680 bytes; 1 declared by the deployment; 29714432 bytes total including deployment metadata not proven: the archive's bytes were not read back, only its manifest; `--deep` reads the whole snapshot out of the repository; no restore was performed: this run did not replay the archive onto a stack, so it proves neither the restore path, which resolves the target, sets mount ownership and runs post_restore hooks, nor that the restored application startsNow lose the row and bring it back.
$ shc exec -s placed -S postgres -- psql -U postgres -c 'delete from notes'DELETE 1$ shc backup restore kept -s placed --yes✔ restored backup "20261106T174709Z_576448b494ed0d0b" into stack "placed" in environment prod, 1 volume replayed; pre-restore safety backup "20261106T174735Z_cabef2ba18f1a0c0"$ shc exec -s placed -S postgres -- psql -U postgres -tAc 'select body from notes'kept by the backupA mirror copies every backup repository onto a second provider, append-only,
so losing one provider loses no backup. The vault names that provider under
backup/copy_repo, and this cluster names none, so the run says so and
copies nothing.
$ shc backup mirrorbackup mirror runs as operation fbe8ef34-6e09-4ced-b14a-bfc5e6120e18✔ skipped: the vault declares no second provider, backup/copy_repo is absentA backup brings back whole volumes. An export hands over what the app
chooses, in its own format, and its jobs run against the running deployment.
This exporter writes the notes table as SQL and reads it back.
jobs: export: - name: dump context: container image: postgres:16-alpine environment: PGPASSWORD: "{{ vars.password }}" command: pg_dump -h postgres -U postgres -t notes --clean --if-exists -f /output/notes.sql volumes: - "@output:/output" import: - name: load context: container image: postgres:16-alpine environment: PGPASSWORD: "{{ vars.password }}" command: psql -h postgres -U postgres -v ON_ERROR_STOP=1 -q -o /dev/null -f /input/notes.sql volumes: - "@input:/input"The file’s name, notes, is the exporter’s name. Each job runs in a new
container on the deployment’s network, where postgres is the service.
@output is the directory the export packs into its artifact, and @input
is that directory unpacked again for the import. See
Writing an exporter.
$ shc update placedupdating deployment "placed"[placed] Healthy 1/1✔ postgres healthysource: /usr/share/shc/apps/notesplaced: changed: app package apppkg-v1:2b75857dd2114aaabfac43cdb1905c03c25cfc0f45b890b0fd62aa76e61e431e -> apppkg-v1:3b904b6d8a98c4e8bb1b97622f78c755846bcb7b7f1e6be673b594b3fe9362c1 read from /usr/share/shc/apps/notesthe rollout of prod/placed/prod to v1:sha256:f32e4f615236a5e945d8b62edac2158b806cddd67382fdc36022e0e82e14fdd3 finished$ shc export notes -s placed --output-dir /var/lib/shc/import/notesexport runs as operation 8650486d-9622-4abb-ab90-686b517de758[placed] Complete 1/1✔ dump✔ exported "notes" from stack "placed" to /var/lib/shc/import/notes/2311174ed444c2c3.exp$ shc exec -s placed -S postgres -- psql -U postgres -c 'delete from notes'DELETE 1$ shc import notes -s placed -i /var/lib/shc/import/notesimport runs as operation a85f4537-718d-4a4c-bebe-1c8186cd2a38[placed] Complete 1/1✔ load✔ imported "notes" into stack "placed"$ shc exec -s placed -S postgres -- psql -U postgres -tAc 'select body from notes'kept by the backupThe export went into /var/lib/shc/import, the directory an import reads
from. Given a directory, the import reads the newest artifact this exporter
made of placed.
Keep placed for the vapp and node-failure pages.
Read Underneath the backup before going on; it reads what this page left running.
Next: Nextcloud on Postgres.