pgBuddy

A tiny web UI to back up and restore multiple PostgreSQL databases from a single Docker container. Backups are made with pg_dump / pg_restore, backup jobs are scheduled with an in-container cron, and you get an e-mail when a scheduled backup fails.

Quick start

git clone https://forgejo.hostlab.tech/suitdeer/pgbuddy.git
cd pgbuddy
docker compose up -d

Then open http://localhost:8080 and log in with admin / admin (change it in Settings).

Persistent data lives under ./data/:

• ./data/config/config.json — your config (DBs, jobs, auth, mail).
• ./data/config/rate.json — Login is rate-limited (10 attempts per 15 minutes per IP).
• ./data/backups/ — the generated dump files.

The container timezone (used by cron and dump timestamps) is set via the BACKUP_TIMEZONE env var (defaults to UTC; the bundled docker-compose.yml sets Europe/Berlin).

Pictures

A list of all your databases that are connected to pgBuddy.

---

If you click on "List Backups" you can see all the backups of one database. You can download, restore and delete each database backup if you want.

---

For each database connection you can create one or more automatic backup jobs (cron-jobs).

Components

• Web stack: plain PHP (server-rendered).
• Styling: Bootstrap 5.3 (local).
• Auth: single user (session login) with integrated rate-limiting.
• Adding a DB: a friendly Name + DB URL (host:port/dbname) + DB Username + DB Password.
• Jobs: configure cron schedules from the UI; a 1-minute cron runner inside the container executes due jobs. Each job can auto-delete older backups via a Keep retention setting.
• E-Mail: e-mail notification on job failure (via msmtp/SMTP).

Scheduling backups

Backup Jobs → + Add job: pick a database, a 5-field cron expression (e.g. 0 2 * * * = daily at 02:00), a format, and a Keep retention count:

• custom — pg_dump -Fc, restored with pg_restore.
• plain — pg_dump -Fp, restored with psql.
• Keep — number of newest backups to keep for the database; 0 keeps all. Older backups are pruned after each successful job run.

The container runs cron.php every minute; any job whose cron expression matches the current minute is executed. You can also Run now from the UI.

Backup / restore

Databases → Backups for a DB lets you:

• Backup now (ad-hoc),
• Download a dump,
• Restore (overwrites the target DB — pg_restore --clean --if-exists or psql -f),
• Delete a file.

E-mail on failure

1. In Settings, fill in the SMTP fields (host, port, user, password, From address) and a recipient, then tick Enable failure notifications. TLS is always enabled: port 465 uses implicit TLS (SMTPS), other ports use STARTTLS.
2. Use Send test e-mail to verify delivery.
3. A failed scheduled job sends an e-mail via msmtp using the settings stored in config.json (no env vars required).

Notes / limitations

• DB passwords are stored in config.json (the container-local config volume) — protect that volume.
• The cron runner matches jobs to the minute, so the shortest interval is 1 minute.
• Restore uses --clean --if-exists; review dumps before restoring into production.

Future features :)

• Upload/import an existing dump file to restore it into a database.

• Push backups to remote storage (S3, SFTP, WebDAV) after creation.

• Success notifications in addition to failure alerts (per-job opt-in).

  Could get out of hand (spam). Hmmm.

• Internationalization / multi-language UI.

  If some one want it, sure ;)

• Multi-user support with roles (admin / read-only viewer).

  If I have more free time perhaps in the distant future ;)

• API (token-authenticated JSON) for integration with external automation.

  I want to keep it simple but if it is requested I might implement it. Also distand future ;)

LICENSE

All contents of this project are protected by the AGPL3.0 LICENSE