Backup and Restore

Postgram supports PostgreSQL logical backups via the CLI with optional GPG encryption. The Admin Backup tab is the supported restore path for a normal Docker installation.

What this page covers

How to create reliable backups and restore into a fresh database for migration or recovery.

Core workflow

1. For the CLI path, provide the database connection URL. The CLI uses local pg_dump when available and otherwise its Docker Compose fallback:

export PGM_DATABASE_URL='postgresql://<user>:<password>@<host>:<port>/<database>'
export PGM_BACKUP_PASSPHRASE='<choose-a-strong-passphrase>'
pgm backup --encrypt --output /tmp/postgram-backups/ --json

For the default Docker Compose installation, use Admin → Backup unless you already have the required database connection URL available to the CLI.

2. Keep the resulting archive and passphrase separately. To inspect an encrypted archive locally, decrypt a copy:

gpg --batch --yes --pinentry-mode loopback \
  --passphrase "$PGM_BACKUP_PASSPHRASE" \
  -o /tmp/postgram-backups/restore.dump \
  -d /tmp/postgram-backups/<backup-file>.dump.gpg

3. Restore through Admin → Backup. It validates the archive, restores into a new database, runs health checks, and leaves the current database intact until you explicitly approve switch-over.

Notes

• Encrypted backups use PGM_BACKUP_PASSPHRASE; losing it makes the encrypted archive unusable.
• The archive contains application data. Treat it as sensitive, and back up the postgram_secrets Docker volume separately: database backups do not include the installation keys needed for provider secrets or admin MFA factors.
• Use direct pg_restore only as an advanced operator workflow. Restoring over the current database bypasses the staged rollback path.