Backups and Restore

Backups and restore

The /config mount contains application state. On the SQLite image that includes the database, logs, cookies, and metadata. Back it up as one unit. The /downloads mount contains media and can use a separate schedule according to its size and value.

On the PostgreSQL image, /config still holds logs, cookies, metadata, and in-app dumps, but the live database lives in the PostgreSQL volume. Back up both.

Create a consistent SQLite backup

For a simple filesystem backup, stop the container before copying config:

docker compose stop pinchflat-ngx
cp -a ./config ./config-backup-YYYY-MM-DD
docker compose start pinchflat-ngx

Adjust the service name and paths to match your Compose file. Backup software may use an atomic filesystem or volume snapshot instead, but the snapshot must include the SQLite database and its WAL files from the same point in time.

Do not treat a copy of only pinchflat.db taken from a running WAL-mode database as a complete backup.

PostgreSQL in-app dumps

The PostgreSQL image can create custom-format pg_dump backups from Settings > PostgreSQL Backups. The SQLite image shows that section as unavailable.

1. Open Settings and select PostgreSQL Backups.
2. Set Backups to Keep (1–100, default 7) and save if you change it.
3. Click Create and Download Backup.

Credentials come from the running app's DATABASE_URL. Pinchflat-ngx passes them to pg_dump through PostgreSQL's PG* environment variables, never as command-line arguments or rendered UI text.

Completed dumps are stored under /config/extras/backups unless POSTGRES_BACKUP_PATH points somewhere else. Keep that path on a persistent volume. Failed or cancelled dumps are written as temporary .partial files and removed; stale partial files are cleaned up before a later backup. After a successful dump, older completed files beyond the retention count are deleted.

Filenames use a UTC timestamp through microsecond precision: pinchflat-ngx-postgres-YYYYMMDD-HHMMSS-ffffff-<id>.dump.

These dumps are PostgreSQL database state only. They do not include downloaded media, /config secrets other than the dump files themselves, or the PostgreSQL server volume. Pinchflat-ngx does not restore a dump automatically and does not convert SQLite to PostgreSQL.

Restore a PostgreSQL dump

1. Stop Pinchflat-ngx.
2. Provision a compatible PostgreSQL 18 database that is not in use by a running Pinchflat-ngx instance.
3. Restore with matching PG* connection environment (or a protected .pgpass file):

pg_restore --clean --if-exists --no-owner --no-privileges \
  --dbname="$PGDATABASE" /config/extras/backups/pinchflat-ngx-postgres-YYYYMMDD-HHMMSS-ffffff-<id>.dump

Review the target before using --clean. Start Pinchflat-ngx afterward so its normal migration check can run. Restore downloaded media separately from your media backup.

Restore a SQLite config backup

1. Stop the container with docker compose down.
2. Move the current config directory aside instead of overwriting it.
3. Restore the complete backup to the path mounted at /config.
4. Confirm its ownership and permissions.
5. Start the same Pinchflat-ngx image version that created the backup.
6. Run docker compose up -d and inspect container health and logs.

Verify several sources, media paths, Settings, and Settings > Diagnostics before deleting the old config directory.

Test restores

Periodically restore into an isolated container with a different host port and copied or read-only media storage. Never point a restore test at the active config directory.