Backups

A backup is a folder under [backups].dir named after the time it was taken in UTC, such as data/backups/20261016-030000/, holding:

File	Contents
db.dump	the whole database, from pg_dump in its custom format, without owners or privileges
media.tar.gz	the media folder
manifest.json	when it was taken, why, the core version, the sizes and any note

A backup does not include the modules folder, the module files folder, gansey.toml, .env, the signing key or the pinned hub key. Copy those separately, and copy the backups folder off the machine: Gansey keeps backups on the same disk as the site.

When backups are taken

Reason	When
nightly	every night at [backups].hour UTC while the server runs, unless [backups].nightly is off
pre-update	before every core update is installed
pre-restore	before every restore
manual	from Settings → Backups or gansey backup now

After each new backup the oldest are removed until [backups].keep remain (at least one). Every reason counts towards that number. A site without a database takes no backups.

[backups]
dir = "./data/backups"
keep = 14
nightly = true
hour = 3   # UTC

The client tools

Backups run the Postgres client tools pg_dump and pg_restore, and tar for the media folder. They must be on the PATH of the user the site runs as, and pg_dump and pg_restore must match the database server's major version. gansey doctor reports whether they are found, and the dashboard shows a warning when pg_dump is missing. The container image ships the tools for Postgres 17.

From the command line

gansey backup now --note "before the redesign"
gansey backup list
gansey backup restore 20261016-030000

backup list prints each backup, newest first, with its time, sizes, reason and note. Settings → Backups does the same in the admin, and can also delete a backup; it needs the manage_site capability.

Restoring

Restoring a backup:

1. takes a pre-restore safety backup, so the restore itself can be undone;
2. loads db.dump into the configured database with pg_restore --clean --if-exists, replacing what is there;
3. unpacks media.tar.gz over the media folder. Files that are not in the archive are left where they are.

The server keeps running during a restore and sees the restored data straight away, but pages it rendered before the restore stay in its page cache. Restart the service afterwards, with --migrate, which also brings a database restored from an older version up to the running one.