Data and database
Some apps keep state in two places: files and a database, or a database plus a separate file store. Both parts must come from the same backup point. This page explains why, and how to do it.
Several volumes
Section titled “Several volumes”A RestoreCheck lists every volume in restoredVolumes. A Restore or RestoreTest restores
one source per volume in one attempt, and the check pod mounts them all. The sourcePVC values tie
the two together. See Volumes and scratch space.
The checks for apps with several volumes are checks/nextcloud/restorecheck.yaml, checks/wordpress/restorecheck.yaml,
checks/jellyfin/restorecheck.yaml and checks/pihole/restorecheck.yaml.
The problem
Section titled “The problem”The timeline shows how two backups taken at different times drift apart.
On restore the file exists but the DB row is missing, because the files are newer than the DB. Swap the order and the DB row exists but the file is missing.
Symptoms seen in the apps:
- Nextcloud: broken file lists and “file not found” in the UI.
- WordPress: broken images (DB newer than files), or orphan uploads (DB older than files).
- Jellyfin: media items show as missing, and metadata is wrong.
- Pi-hole: lists in the DB that are not applied, or missing DNS records.
- n8n: credentials that cannot be decrypted (key mismatch, not drift).
(Source: the caveats in each checks/<app>/README.md.)
- Restore the whole app group from one backup point.
- A Velero namespace backup is one point. Restoring it gives one consistent set.
- VolSync and Kopiur work per PVC. List every PVC of the app as a source of one
RestoreorRestoreTest. Take the backups at the same time, or accept the skew and check it. ARestoreTestwithafterBackupwaits until every source has a new backup.
- Restore all volumes of the app in one attempt. One source per PVC, one check that mounts them all.
- Quiesce the database, or rely on crash recovery. Pick one:
- Crash-consistent copy, WAL recovery on boot. Tested with Postgres 17. The copy of a live database recovered on boot, and the SQL check passed. Not tested under heavy write load.
- Pre-backup flush hook. Flush or checkpoint the database before the snapshot. Not tested in this project.
- SQLite-in-volume apps (gitea, grafana, home-assistant, vaultwarden, uptime-kuma): take the backup with the app stopped, or with a consistent snapshot. Their check READMEs name the SQLite file as the main risk.
- Write checks that cross-reference. A DB row must point to a file that exists, and the file must match the row.
- Each restored workload holds its PVC alone. Scale restored workloads to 0 before the check pod mounts the PVCs (RWO). See Best practices.
Worked example: Nextcloud
Section titled “Worked example: Nextcloud”Files plus Postgres, two PVCs.
- Volumes:
htmlat/var/www/html,pgdataat/var/lib/postgresql/data. - Files:
/var/www/html/data. The rows that say which files exist and their sizes are inoc_filecachein Postgres. - Restore: two sources,
htmlandpgdata, in oneRestoreorRestoreTest. Example: examples/kopiur/restoretest.yaml. - Repair if drift happens:
occ files:scancan fix listings but may drop or duplicate entries. - Check (
checks/nextcloud/restorecheck.yaml):occ statusshows installed,occ integrity:check-corepasses, and the canaryoc_filecache.sizeequals the file size on disk. - The check runs Postgres as a native sidecar: an init container with
restartPolicy: Always. The check rewritesdbhostto127.0.0.1inconfig.php. - Open issue:
pdo_pgsqlin the image is assumed, not verified.
Worked example: WordPress
Section titled “Worked example: WordPress”Files plus MariaDB, two PVCs.
- Volumes:
htmlat/var/www/html,mysqlat/var/lib/mysql. - DB rows (
wp_posts) reference uploads inwp-content/uploads. - Restore: two sources,
htmlandmysql, in one attempt. - Check: MariaDB ping. The canary post’s content equals the sha256 of the uploaded canary file.
- Not checked: front-end render, plugin-generated tables.
Other apps with two volumes
Section titled “Other apps with two volumes”- Jellyfin: config (
library.db,jellyfin.db) and media. Restore both from one backup point. If media is too large, restore config only. Then the check covers the database only. - Pi-hole:
gravity.dband/etc/dnsmasq.d. The config must match the FTL version. Check the canary adlist row, the canary line incustom.list, and that dnsmasq config parses.
