A self-hosted web app for managing backups and restores of PostgreSQL, MySQL/MariaDB, MongoDB, SQL Server and file directories. Manage multiple connections, schedule backups, keep encrypted copies in the cloud and track results in one place.
Website: https://vinhnotes.github.io/db-backup-manager/
- Features
- Screenshots
- Quick start with Docker Compose
- Supported databases
- Configuration and deployment
- Users and permissions
- Cloud storage and encryption
- Notifications, restore testing and monitoring
- Operating procedure
- Development and testing
- Limitations
- Contributing
- Security and private data
- License
- Manage multiple database connections and file directories from a web UI; test each connection before saving.
- Manual or cron-scheduled backups, retention management, archive upload/download and SHA-256 verification.
- Restore into a new database or directory; configure a separate restore account per connection.
- Restore testing, manual or after each scheduled backup, with results shown next to each backup.
- Offsite storage via rclone: Google Drive, OneDrive, Dropbox, S3/R2/MinIO, B2, SFTP, WebDAV and other supported backends. Encrypted with age before upload, with separate cloud retention.
- Notifications via Telegram, Slack, Discord, SMTP or webhook; a
/metricsendpoint for Prometheus. - Automatic retries for failed backups/cloud uploads and catch-up of missed schedules when the app restarts.
- User management, per-connection/per-database permissions and an activity log; customizable name, logo and schedule timezone.
- HTTPS with an auto-generated or your own certificate. The container runs as a non-root user, supports a read-only root filesystem and needs neither the Docker socket nor the Portainer API.
- UI in English, Vietnamese and Japanese.
Backups: every backup is verified with SHA-256 and shows its restore test result.
Schedules: cron schedules with next run time and retention.
Add connection: test the connection before saving, with an optional separate restore account.
Screenshots of the real app running with demo data.
- Docker Engine or Docker Desktop with Docker Compose v2.
- A database reachable from the container, or a mounted directory for file backups.
- Write access to the metadata and backup directories. The container runs as UID/GID
999:999.
After cloning the repository, run the following from the repository root. Compose builds the image from source; no registry account is needed.
cp .env.example .env
chmod 600 .env
docker network lsEdit .env and set at least:
ADMIN_USER=admin
ADMIN_PASSWORD=REPLACE_WITH_A_STRONG_UNIQUE_PASSWORD
POSTGRES_NETWORK=your-existing-database-networkADMIN_PASSWORD must be 12–72 bytes long. POSTGRES_NETWORK is the name of the actual Docker network your database container uses. If there is no shared network yet, create one with docker network create db-backup, set POSTGRES_NETWORK=db-backup and attach your database container to it. Despite the name POSTGRES_NETWORK, the network can be used for any database type.
With the default paths ./data and ./backups, create the directories with the right ownership on a Linux host:
sudo install -d -o 999 -g 999 -m 700 ./data ./backups
docker compose up -d --build
docker compose psOpen https://localhost:8088, accept or trust the self-signed certificate generated on first run, and sign in with the account set in .env. If the app runs on a remote server, see access via SSH tunnel.
Under Databases → Add connection, choose the database type, enter the connection details, then click Test connection and Save. For a database on the same Docker network, use the service/container name as the host. For file directories, see Files.
Run a manual backup and test a restore before setting up schedules. To diagnose startup errors:
docker compose logs --tail=100 db-backup-managerOptional variables are listed in .env.example. To deploy with Portainer or push the image to your own registry, see the deployment guide.
Choose the Database type when adding a connection. Each backup remembers its database type and can only be restored to a server of the same type.
| Type | Backup method | Downloaded file | Restore |
|---|---|---|---|
| PostgreSQL | pg_dump --format=custom, verified with pg_restore --list |
.dump |
CREATE DATABASE + pg_restore --single-transaction --no-owner |
| MySQL / MariaDB | mariadb-dump --single-transaction --routines --triggers --events, gzip-compressed, checked for the -- Dump completed line |
.sql.gz |
CREATE DATABASE + mariadb client; DEFINER is stripped so objects belong to the restore account |
| MongoDB | mongodump --db --archive --gzip, archive header checked |
.archive.gz |
Refused if the target database exists, then mongorestore --nsFrom/--nsTo |
| SQL Server | BACKUP DATABASE … WITH COPY_ONLY, CHECKSUM (+ COMPRESSION on non-Express editions) and RESTORE VERIFYONLY |
.bak |
RESTORE DATABASE … WITH MOVE to new files in the default data directory |
| Files (directory) | The mounted directory is packed into a tar.gz, then the whole archive is read back to verify it | .tar.gz |
Extracted into a new directory inside the restore directory; never overwrites |
Uploads accept the format of the selected server (MySQL also accepts uncompressed .sql). Passwords never appear on the command line: client tools read them from a temporary 0600 file in /tmp, deleted right after use.
The image ships the MariaDB 11.8 client, which works with MySQL 5.7/8.x and MariaDB 10.x/11.x. SSL mode prefer uses TLS when the server supports it (without certificate verification); verify-full verifies both certificate and hostname.
CREATE USER 'backup_user'@'%' IDENTIFIED BY 'REPLACE_WITH_STRONG_BACKUP_PASSWORD';
GRANT SELECT, SHOW VIEW, TRIGGER, EVENT, LOCK TABLES ON *.* TO 'backup_user'@'%';
-- Optional, for restore: create new databases with full rights on them
CREATE USER 'restore_user'@'%' IDENTIFIED BY 'REPLACE_WITH_DIFFERENT_RESTORE_PASSWORD';
GRANT ALL PRIVILEGES ON *.* TO 'restore_user'@'%';Backing up routines on MySQL 8 also requires SHOW_ROUTINE (or global SELECT) if the user is not the definer. Non-InnoDB tables (MyISAM) are not consistent while the database is being written to, because --single-transaction only applies to InnoDB.
The Authentication database field is authSource (default admin). Leave the username empty if MongoDB has authentication disabled. Connections target a single host/port; mongodb+srv:// URIs (Atlas) and custom replica set options are not supported yet.
db.getSiblingDB("admin").createUser({ user: "backup_user", pwd: "…", roles: ["backup"] })
// Optional, for restore:
db.getSiblingDB("admin").createUser({ user: "restore_user", pwd: "…", roles: ["restore", "readAnyDatabase"] })Backing up a single database does not include users/roles defined in that database.
SQL Server has no remote dump tool: BACKUP DATABASE writes the .bak file on the SQL Server machine. Each SQL Server connection therefore needs a shared directory between SQL Server and this container, declared with two paths:
- Path on SQL Server: the directory as SQL Server sees it, e.g.
/var/opt/mssql/backuporD:\Backup. - Path in this container: the same directory mounted into the manager container, e.g.
/mssql-backup.
The manager writes the .bak there, moves it into BACKUP_DIR, then deletes it from the shared directory. On restore, the manager copies the backup into the shared directory (mode 0644) for SQL Server to read, and deletes it afterwards. Example on a single Docker host:
services:
mssql:
volumes:
- mssql-backup:/var/opt/mssql/backup
db-backup-manager:
group_add:
- "10001" # mssql group: SQL Server creates .bak files with mode 0640
volumes:
- mssql-backup:/mssql-backup
volumes:
mssql-backup:Permission requirements (tested with SQL Server 2022 on Linux):
- SQL Server (user
mssql, UID/GID 10001) creates.bakfiles with mode0640, so the manager container (UID 999) must belong to group 10001 (group_add) to read them. - The directory must be writable by both sides, e.g.
chmod 0777, or2775with group 10001. Do not use the sticky bit (1777): the manager would be unable to delete files created by SQL Server. - On separate machines, use an SMB/NFS share mounted on both sides with equivalent permissions. Test connection checks the login and write access to the directory inside the container, but only the first backup confirms that both paths point to the same place.
CREATE LOGIN backup_user WITH PASSWORD = 'REPLACE_WITH_STRONG_BACKUP_PASSWORD';
-- In each database to back up:
CREATE USER backup_user FOR LOGIN backup_user;
ALTER ROLE db_backupoperator ADD MEMBER backup_user;
-- To list database sizes (optional):
GRANT VIEW ANY DEFINITION TO backup_user;
-- Optional, for restore:
CREATE LOGIN restore_user WITH PASSWORD = 'REPLACE_WITH_DIFFERENT_RESTORE_PASSWORD';
ALTER SERVER ROLE dbcreator ADD MEMBER restore_user;Backups use COPY_ONLY, so they do not disturb existing differential/log backup chains. RESTORE VERIFYONLY only runs when the backup account has CREATE DATABASE permission; otherwise verification relies on BACKUP … WITH CHECKSUM. A restored database keeps the users/owner stored in the backup; grant application permissions after checking it.
Back up a file directory, such as a web app's upload folder, with the same schedules, retention, cloud storage, notifications and restore testing as databases. Each Files connection is one directory. To back up several directories, create several connections.
The container can only read directories mounted into it. Add volumes to docker-compose.yml:
volumes:
- /var/www/app/uploads:/sources/uploads:ro # source directory, read-only
- ./restore:/restore # restore directory (optional)Then add a Files connection: Source folder /sources/uploads, Restore folder /restore (leave empty if you don't need restores).
- The container runs as UID 999: source files must be readable by this UID (default
644/755permissions usually are). The restore directory must be writable by UID 999, e.g.chown 999:999 ./restore. - Backups keep the directory structure, permissions (without setuid/setgid), modification times and symlinks. Ownership (UID/GID) is not kept. Sockets, devices and pipes are skipped.
- Restore always creates a new subdirectory
/restore/<target name>and refuses if it already exists. After checking it, copy the files back yourself, e.g.rsync -a /path/restore/<name>/ /var/www/app/uploads/. - Uploaded or cloud-downloaded archives are validated first: absolute paths,
.., hardlinks and devices are rejected. Symlinks are created last so no file is ever written through a symlink. - Each backup packs the entire directory (not incremental). Suitable for directories up to a few tens of GB. Very large directories may require a higher
JOB_TIMEOUT. - Files being written during a backup may be saved only partially. A file that shrinks while being read fails the backup, which is then retried. Schedule file backups right after database backups so both copies are close in time.
- The source directory must not contain (or be inside)
BACKUP_DIR, and must not be the same as the restore directory.
Find the Docker network name and the DNS alias/service of your existing PostgreSQL. Do not expose the PostgreSQL port to the Internet. The manager must be able to reach the host/port of each connection; for PostgreSQL in Docker, use the same external network and the container's DNS alias.
Create a backup user with a PostgreSQL admin account. Example (replace the password before running):
CREATE ROLE backup_user LOGIN PASSWORD 'REPLACE_WITH_STRONG_BACKUP_PASSWORD';
GRANT pg_read_all_data TO backup_user;
GRANT CONNECT ON DATABASE app_db TO backup_user;pg_read_all_data does not bypass Row Level Security. If the database uses RLS, large objects, extensions or special ACLs, the DBA must grant appropriate permissions and test backups for each database. Do not grant superuser by default. To compute the size of all databases, the user needs CONNECT on each managed database (or suitable monitoring privileges).
An optional restore account, separate from the backup account:
CREATE ROLE restore_user LOGIN CREATEDB PASSWORD 'REPLACE_WITH_DIFFERENT_RESTORE_PASSWORD';
GRANT CONNECT ON DATABASE postgres TO restore_user;Restored objects are owned by the restore account (--no-owner --no-privileges). Extensions that need superuser or special configuration may make the restore fail. Grant application permissions after the DBA has verified the target data.
On the machine running the app, in the project directory:
cp .env.example .env
chmod 600 .envSet ADMIN_PASSWORD and POSTGRES_NETWORK in .env, then sign in and go to Databases → Add connection. Enter a display name, host, port, username, password, maintenance database (default postgres) and SSL mode. Click Test connection, then Save. You can save multiple servers and pick a connection to view its databases; each backup or schedule is tied to the selected connection. "All databases" applies to that server.
The host is resolved from the server/container running the manager. localhost inside the container does not point to your workstation. Connections are stored in SQLite and passwords are encrypted with the connections.key file next to the metadata file. Back up both the metadata and the key file together to be able to restore your configuration. Do not delete the key file while saved connections exist. Viewers have read-only access; admins manage connections. A connection with running/queued jobs cannot be edited or deleted; remove its schedules before deleting the connection. Archives and history are kept when a connection is deleted.
Connections created in the UI are used for listing databases, backups, schedules and restores. Under Databases → Add/Edit connection, enter a separate Restore account and Restore password for that server; leave the account empty to disable restores. The account needs LOGIN, CREATEDB and CONNECT on the maintenance database. Test connection verifies both the backup connection and the CREATEDB permission of the restore account. The check does not guarantee that every extension in an archive can be restored.
In Backups, filter by server then database; uploads attach the archive to the selected server. Click restore on an archive, choose a target server with restore configured (it may differ from the source server), enter a new database name, type it again to confirm and confirm you trust the archive. Existing databases are never overwritten. Archives of deleted servers remain available to download or restore to another server. Backup and restore passwords are encrypted; leave a password empty when editing to keep the stored value, or choose to clear it.
All database connection settings (host, account, password, restore, SSL) are managed only in the web UI; .env no longer holds database credentials. Variables such as PGHOST, PGUSER, PGPASSWORD, RESTORE_PGUSER… are ignored if still set.
.env variables:
| Variable | Meaning |
|---|---|
ADMIN_USER, ADMIN_PASSWORD |
Admin account. ADMIN_PASSWORD is required (12–72 bytes, use a strong password) and remains the admin password until it is changed in the web UI; see Admin password |
VIEWER_PASSWORD |
Optional; a read-only viewer account (all connections, no downloads); must differ from the admin password |
POSTGRES_NETWORK |
Required name of an existing external Docker network (docker network ls); no default |
PG_MAJOR |
Client version in the image, default 18; must be >= the server major version |
DATA_DIR, BACKUP_DIR |
Host directories for metadata and archives; absolute paths recommended on a VM |
TZ |
Default schedule timezone (Asia/Ho_Chi_Minh). Admins can change it in the UI (account menu at top right → Change schedule timezone); the UI value takes precedence |
JOB_TIMEOUT |
Per-job timeout, default 2h |
MAX_UPLOAD_BYTES |
Default 10737418240 (10 GiB) |
RCLONE_BINARY |
Optional rclone path; defaults to rclone in PATH (included in the image) |
The image runs as user postgres (UID/GID 999:999). Create new directories with matching ownership, e.g. for the paths below (also update both variables in .env):
sudo install -d -o 999 -g 999 -m 700 /opt/db-backup-manager/data /opt/backups/dbDo not grant access to the archive directory to users who don't need it. If you use the default ./data and ./backups, also create them with the right ownership before starting. Do not use chmod 777.
docker compose build
docker compose up -d
docker compose ps
docker compose logs --tail=100 db-backup-managerCompose only publishes 127.0.0.1:8088:8080, uses a read-only root filesystem, drops Linux capabilities and does not mount the Docker socket. The healthcheck only checks the backend/SQLite; database status is shown separately on the dashboard.
On your workstation:
ssh -N -L 8088:127.0.0.1:8088 ubuntu@SERVER_IPOpen https://localhost:8088 and sign in with the account set in .env.
The Docker image runs HTTPS by default (TLS_MODE=self-signed). On first start, the server generates a self-signed certificate (ECDSA P-256, valid for 10 years) and stores it in DATA_DIR/tls/ (cert.pem, key.pem), so redeploying keeps the same certificate. Requests over http:// are redirected to https:// (same port). Browsers warn the first time because the certificate is not CA-signed: choose Advanced → Proceed (or import cert.pem on your machine to remove the warning).
The certificate is always valid for localhost, 127.0.0.1 and the container hostname. If you access the server by IP or domain name, add it to TLS_HOSTS (comma-separated), e.g. TLS_HOSTS=192.0.2.10,backup.example.com. When TLS_HOSTS changes, or the certificate has less than 30 days left, the server regenerates it on startup.
TLS_MODE |
Meaning |
|---|---|
self-signed |
Default in Docker. Generates and keeps a certificate. |
file |
Use your own certificate: mount the files into the container and set TLS_CERT_FILE, TLS_KEY_FILE. |
off |
Plain HTTP, e.g. behind an HTTPS reverse proxy (then also set COOKIE_SECURE=true). |
The session cookie automatically gets Secure when TLS is on; COOKIE_SECURE is only needed to override it. Running locally with make run stays on HTTP unless TLS_MODE is set.
See the full guide in deploy/README.md: pass your repository via IMAGE when pushing/deploying the image, create the stack from deploy/docker-compose.portainer.yml; it uses named volumes, so no manual directory creation or chown is needed.
The admin from .env (ADMIN_USER) always has full access. Other accounts are created in the UI: user menu at top right → Manage users (#/users).
- Administrator: full access like the
.envadmin — connections, cloud destinations, users, all databases. - User: only sees connections, databases, backups, schedules and jobs within the granted scope. Each permission row is Connection (or all) × Database (empty = all) × Level:
- View: view backups, schedules, jobs.
- Operate: run backups, download, upload, manage schedules, delete backups, push to cloud.
- Backups/schedules for "All databases" and restores (into the target connection) require Operate on all databases of that connection.
- Managing connections and cloud destinations, and pulling files from the cloud, is limited to administrators; browsing cloud files requires View on the entire connection.
- Users change their own password in Profile & password. The
.envadmin can also change it there; the new password is stored in the metadata and persists even ifADMIN_PASSWORDchanges or the app restarts.
ADMIN_PASSWORD in .env is the admin's default password, not just a first-run value:
| Situation | Admin password used to sign in |
|---|---|
| Never changed in the web UI | ADMIN_PASSWORD from .env. Edit .env and run docker compose up -d to change it |
| Changed in Profile & password | The new password (stored in metadata). ADMIN_PASSWORD is ignored, even after editing .env or restarting |
After running reset-admin-password |
Back to ADMIN_PASSWORD from .env |
Even when ignored, ADMIN_PASSWORD is still required (12–72 bytes), otherwise the server won't start. A password changed in the web UI lives in data/metadata.db: restoring metadata from an old backup also restores the admin password from that point in time.
The reset command removes the password set in the web UI so that ADMIN_PASSWORD from .env takes effect again. No restart needed; open admin sessions are signed out.
docker compose exec db-backup-manager db-backup-manager reset-admin-passwordIf you don't remember ADMIN_PASSWORD either: change it in .env, run docker compose up -d so the container picks up the new value, then run the reset command above.
Outside Docker: METADATA_DB=data/metadata.db ./bin/db-backup-manager reset-admin-password. Portainer: open the container's Console and run db-backup-manager reset-admin-password.
The Docker image includes rclone, built from a pinned source version with dependencies verified via the Go checksum database. When running locally, install rclone in PATH or set RCLONE_BINARY.
- A backup completes (manual, or scheduled with a cloud destination selected) → an Upload to cloud job is created.
- The job verifies the archive's SHA-256, encrypts it with age into a temporary file in
BACKUP_DIR, uploads it withrclone copyto, checks the size on the cloud, then deletes the temporary file. - Cloud path:
<folder>/<connection name>/<database>/<database>_<YYYYMMDDTHHMMSSZ>_<id>.dump.age. - Cloud retention (per destination,
0= keep forever) runs with the cleanup job and always keeps the latest copy of each database. Local retention does not affect cloud copies.
Go to Cloud storage → Add destination:
-
Google Drive — web OAuth: choose Google Drive → Sign in with Google OAuth → Connect Google Drive, sign in/grant access, then click Save. No rclone needed on your workstation. An administrator configures the OAuth Client once, as described below. Edit the destination and click Reconnect Google Drive when the token is no longer valid.
-
Manual rclone config — Google Drive / OneDrive / Dropbox (OAuth): on a machine with a browser, run
rclone config→n→ choosedrive/onedrive/dropboxand sign in. For Google Drive, thedrive.filescope is recommended. Then runrclone config show <remote-name>and paste the output into the rclone config field. Tokens are refreshed automatically; the new token is encrypted and saved after each run. -
S3 / R2 / MinIO / Wasabi: paste directly, e.g.:
type = s3 provider = AWS access_key_id = AKIA... secret_access_key = ... region = ap-southeast-1
The target folder starts with the bucket name, e.g.
my-bucket/db-backups. Use an access key scoped to the backup bucket only.
The rclone config (including tokens) is encrypted with AES-GCM using connections.key and is never returned to the browser. local/alias/crypt… remotes and the ssh option are rejected. Click Test to write, read and delete a test file on the cloud.
The app uses Google's OAuth 2.0 for Web Server Applications. rclone still runs on the server to transfer files and refresh access tokens. The server does not need to be reachable from the Internet; both the server and the browser need outbound access to Google.
-
In Google Cloud Console, enable the Google Drive API for the project. Configure the Google Auth Platform (Audience / Data Access), then create an OAuth Client of type Web application.
-
Register an Authorized redirect URI that exactly matches
GOOGLE_OAUTH_REDIRECT_URL, including scheme, hostname, port and the path/api/destinations/google/callback. Do not use a LAN IP as the callback; uselocalhostover an SSH tunnel.localhostand127.0.0.1are different hostnames and must match the registered URL. -
Add three variables to
.env(Docker Compose already passes them into the container), e.g. with the default Docker HTTPS on host port 8088:GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret GOOGLE_OAUTH_REDIRECT_URL=https://localhost:8088/api/destinations/google/callback
Keep
.envprivate and never commit the Client Secret. Restart/recreate the container after changing the configuration. When running the binary directly, pass these variables through the process environment. -
Open a tunnel from your workstation:
ssh -N -L 8088:127.0.0.1:8088 user@server
Open https://localhost:8088 in the browser, accept/trust the internal certificate if self-signed, sign in to the app and connect Google Drive. The server-side port in the example is the published Docker port (
127.0.0.1:8088→ container8080). If the local port is taken, change the local port, the callback URL and the Google registration to match.If the app runs over HTTP: set
TLS_MODE=off,COOKIE_SECURE=falseand the callbackhttp://localhost:8088/api/destinations/google/callback. If the binary listens on another port, change the tunnel target accordingly. No extra tunnel is needed for rclone's port 53682. -
Choose the access scope in the form:
- Only files created by this app (
drive.file, default): limits access to files this OAuth Client may access. Suitable for new backups. - Entire Drive (
drive): use when you need folders or older backups created by another OAuth Client (e.g. rclone's default client). This scope allows reading/editing every Drive file; Google may require app verification depending on your deployment. Switching clients and usingdrive.filedoes not grant access to files created by the old client.
- Only files created by this app (
-
Once Google reports success, close the Google window, return to the form, click Test if needed, then Save. The new grant does not replace the saved config until you click Save. When reconnecting an existing Drive destination, the app keeps the configured
root_folder_idandteam_drive. Select the right existing folder (or a Folder ID via manual rclone config) when you need to browse existing backups.
The authorization session waits up to 10 minutes; the pending result is kept for up to 30 minutes, bound to the admin's login session, and lost on server restart. Testing a destination does not consume the OAuth result; a successful save does. Tokens and the Client Secret are never returned to the browser; the Drive config is encrypted with connections.key like a manual rclone config. Keeping the Client ID/Secret alongside the token lets rclone keep refreshing after a server restart.
If the Audience is External and the Publishing status is still Testing, Drive refresh tokens expire after 7 days, even with frequent backups. Switch to In production and reconnect to avoid the Testing limit; this does not require exposing the backup server publicly. Tokens can still be revoked or expire under Google/Workspace policies. On invalid_grant, open the cloud destination and reconnect. Web OAuth makes re-authorization convenient; it does not remove Google's expiry policies.
| Public key (recommended) | Passphrase | |
|---|---|---|
| Algorithm | age X25519 + ChaCha20-Poly1305 | age scrypt + ChaCha20-Poly1305 |
| Stored on the server | Public key only | Passphrase (encrypted with connections.key) |
| If the server/cloud is compromised | Backups still cannot be decrypted | An attacker who owns the server can decrypt |
| Needed to restore | Private key (AGE-SECRET-KEY-1…) |
Passphrase |
- Click Generate new key pair to create keys: the private key is shown only once (copy it or download the
.txt); the server does not store it. You can also runage-keygen -o key.txtyourself and paste only the public key. Multiple public keys (one per line) can be entered for backup keys. - Store the private key/passphrase separately from the server and the cloud account (password manager, safe…). Lose the key = lose the backups.
- Changing keys only applies to subsequent uploads; older files still need the old key.
- age authenticates every data chunk: a file tampered with on the cloud fails to decrypt instead of producing wrong data.
-
In the UI: Cloud storage → Browse & download, select a file, choose the connection to attach it to and enter the private key (kept in RAM only until the job finishes). The decrypted copy appears in the backup list with the source "From cloud", then restore as usual. Works on a fresh server too (just add the cloud destination again).
-
Manually (if the server is lost):
rclone copy gdrive:db-backups/Production/app_db/app_db_20261102T020000Z_1a2b3c4d.dump.age . age -d -i key.txt app_db_20261102T020000Z_1a2b3c4d.dump.age > app_db.dump # passphrase: age -d app_db_...dump.age > app_db.dump pg_restore --list app_db.dump createdb app_db_restored && pg_restore --no-owner -d app_db_restored app_db.dump
Admins go to Notifications (Account menu) → Add channel, choose a type, fill in the configuration and click Send test before saving. Each channel has its own events and message language (Tiếng Việt, English, 日本語):
| Event | When it is sent |
|---|---|
| Job failed | Backup, scheduled backup, restore, restore test, cloud upload/download or cleanup failed. Backups and cloud uploads only notify after the final retry. |
| Schedule missed | An enabled schedule is 15 minutes past its run time with no job created (stuck scheduler, stopped container…). Each missed run is reported once; failed jobs already have their own "failed" notification. |
| No recent backup | An enabled schedule has had no successful backup for longer than BACKUP_MAX_AGE (default 24h; or one schedule interval + JOB_TIMEOUT if longer, e.g. ~26h for daily, ~7 days for weekly). Also catches jobs that keep running but keep failing. Reported once until a backup succeeds. |
| Backup unusually small | A new backup is smaller than the previous one of the same database by more than BACKUP_SHRINK_PERCENT (default 50%). Skipped when the previous backup is under 1 MiB. |
| Connection lost | Every 5 minutes, each connection is checked (like the Test connection button). Reported after 2 consecutive failures (~10 minutes), and once more when it recovers. Webhooks receive event connection_down / connection_up. |
| Cloud unreachable | Every 30 minutes, a small file is written/read on each cloud destination. Reported after 2 consecutive failures and on recovery (destination_down / destination_up). |
| Disk almost full | Free space on the BACKUP_DIR volume is below DISK_ALERT_PERCENT (default 10%), checked every 10 minutes; reported again once free space is above the threshold + 2% (disk_low / disk_ok). |
| Restore requested | As soon as someone requests a restore, including who, which backup and the target database. |
| Repeated failed logins | An IP address fails to sign in 10 times and is locked out for 15 minutes. Behind a reverse proxy, all requests may carry the proxy's IP. |
| Job completed | Successful backups, restores and restore tests. Can be noisy. |
| Type | Configuration |
|---|---|
| Telegram | Bot token from @BotFather and Chat ID (groups look like -100…) |
| Slack / Discord | Incoming webhook URL (https://…) |
| Webhook | URL receiving a JSON POST (event, title, text, connection, database, job…). Optional secret: header X-DBBM-Signature: sha256=<HMAC-SHA256 of the body> |
| SMTP server, STARTTLS (587) / SSL (465) / unencrypted, optional account, sender, up to 20 recipients |
Tokens, webhook URLs and SMTP passwords are encrypted with AES-GCM like connection passwords and are never returned by the API; leave them empty when editing to keep them. Delivery failures are recorded in the activity log (notifier.failed) and the dbbm_notification_failures_total metric.
| Variable | Default | Meaning |
|---|---|---|
JOB_RETRIES |
2 |
Number of retries for failed backups / cloud uploads (0–10). While waiting, the job is "Queued" with the previous error. |
JOB_RETRY_DELAY |
2m |
Delay before the first retry, doubled after each attempt. |
DISK_ALERT_PERCENT |
10 |
Send "Disk almost full" when free space falls below this percentage. 0 = off. |
BACKUP_SHRINK_PERCENT |
50 |
Send "Backup unusually small" when a new backup shrinks by more than this percentage. 0 = off. |
BACKUP_MAX_AGE |
24h |
Send "No recent backup" when there has been no successful backup for this long. 0 = off. |
CATCH_UP_MISSED |
true |
On startup, each schedule that missed a run while stopped runs once (several missed runs still produce a single backup). |
A restart while a job is waiting to retry marks it as failed, like other queued jobs.
A restore test proves a backup can be restored, which checksums and pg_restore --list cannot. Steps: verify the checksum → restore into a new database named dbbm_verify_<random> using the restore account → open the database and count tables/collections → drop the temporary database (even if the restore fails or hits JOB_TIMEOUT). The manager checks that the temporary name doesn't exist before creating it, so it never drops a pre-existing database.
- Manual: the flask button on each backup; choose a test server (same database type, restore enabled).
- Automatic: when creating a schedule, enable Test restore after every backup and choose a test server.
- Results appear next to the backup (Restore OK / Restore failed, hover for details) and are sent to notification channels.
A restore test uses the test server's CPU, RAM and disk, and needs free space equal to the restored database. For large databases, point it at a staging server rather than production. Extra permissions for the restore account: PostgreSQL can drop databases it owns; MySQL needs DROP; MongoDB the restore role (without dropDatabase, the manager drops each collection); SQL Server dbcreator. On SQL Server, if the restore account cannot read the restored database, the result only confirms the database is ONLINE. If dropping the temporary database fails, the job reports an error with its name so you can drop it manually.
Set METRICS_TOKEN (at least 16 characters) to enable GET /metrics; when unset, the endpoint returns 404. Scrape config:
scrape_configs:
- job_name: db-backup-manager
authorization:
credentials: "<METRICS_TOKEN>"
static_configs:
- targets: ["db-backup-manager:8080"]| Metric | Labels | Meaning |
|---|---|---|
dbbm_backup_last_success_timestamp_seconds |
connection, database | When the last successful backup job finished |
dbbm_backup_last_failure_timestamp_seconds |
connection, database | When the last failed backup job finished |
dbbm_backup_last_duration_seconds |
connection, database | Duration of the last successful backup |
dbbm_backup_last_timestamp_seconds, dbbm_backup_last_size_bytes, dbbm_backups, dbbm_backups_bytes |
connection, database | Stored backups |
dbbm_verify_last_timestamp_seconds, dbbm_verify_last_success |
connection, database | Result of the last restore test |
dbbm_schedule_stale |
connection, database | 1 when a schedule missed its run without creating a job |
dbbm_destination_up |
destination | 1 when the last cloud destination check (every 30 minutes) succeeded, 0 on failure |
dbbm_connection_up |
connection | 1 when the last connection check (every 5 minutes) succeeded, 0 on failure |
dbbm_jobs |
kind, status | Number of jobs in history; dbbm_queue_length queued jobs |
dbbm_offsite_last_upload_timestamp_seconds |
destination | Last cloud upload |
dbbm_backup_disk_free_bytes, dbbm_backup_disk_size_bytes |
Disk space of BACKUP_DIR |
|
dbbm_notification_failures_total |
Failed notifications since startup |
Example alerts:
groups:
- name: db-backup
rules:
- alert: BackupTooOld
expr: time() - dbbm_backup_last_success_timestamp_seconds > 26 * 3600
- alert: BackupFailing
expr: dbbm_backup_last_failure_timestamp_seconds > dbbm_backup_last_success_timestamp_seconds
- alert: RestoreTestFailed
expr: dbbm_verify_last_success == 0
- alert: BackupDiskLow
expr: dbbm_backup_disk_free_bytes / dbbm_backup_disk_size_bytes < 0.1- Check that the dashboard shows Connected and lists the databases you need to back up.
- Run a manual backup and watch the job in History; only
completedjobs produce a backup that can be downloaded/restored. - Create a schedule, e.g.
0 2 * * *(daily at 02:00), with 14-day retention. - Add at least one notification channel and enable automatic restore testing for important schedules. Automatic tests confirm a backup can be restored; you should still periodically restore an archive into a new database and check business data from the application (rows, extensions, permissions).
- Enable a cloud destination for backup schedules (see Cloud storage); periodically try downloading and decrypting a copy from the cloud. Metadata (
DATA_DIR) is not uploaded automatically: back it up separately. To copy SQLite safely, stop the manager before copying the wholeDATA_DIR, or use the SQLite online backup API; don't copy onlymetadata.dbwhile WAL is active. - Archives are only listed when they have metadata. Do not add/rename files under
BACKUP_DIRby hand; use Upload to import archives. A crash may leave.partialfiles or archives without metadata; only clean up orphaned files while the manager is stopped and after checking the metadata.
A restore that fails after the database was created leaves the target database in place for the DBA to inspect. Databases are never dropped automatically (except that restore tests always drop the temporary dbbm_verify_… database they created). To retry, use a new name or have the DBA drop the failed database after verification.
Requires Go >= 1.26, Node >= 22 and the client tools for the database types you use in PATH: pg_dump/pg_restore, mariadb-dump/mariadb, mongodump/mongorestore. SQL Server needs no client tools.
cd web
npm ci
npm run build
cd ..
# Export the required variables; the local binary does not load .env.
export ADMIN_PASSWORD='SET_A_STRONG_LOCAL_PASSWORD'
make runAfter signing in, add a local database connection under Databases → Add connection. The backend listens on 127.0.0.1:8080 by default. The built UI is served at http://127.0.0.1:8080. For React development, run cd web && npm run dev; Vite proxies /api to the backend.
make test
make buildOpt-in integration tests with a throwaway PostgreSQL, never production:
docker run -d --name dbbackup-test -e POSTGRES_PASSWORD=integration-only-password \
-p 127.0.0.1:55439:5432 postgres:18-bookworm
# Wait: docker exec dbbackup-test pg_isready -U postgres
TEST_PGPORT=55439 go test -race -v ./...
docker rm -fv dbbackup-testOr run them automatically with sh scripts/integration.sh (creates/removes the test container and picks a free port).
Tests create randomly named databases and clean up after themselves; they check real data after restore, rejection of existing targets, checksums, upload/download, deletion and scheduler callbacks. Unit tests cover viewer permissions, sessions/CSRF, restore confirmation, cron, retention, pgpass and job state recovery after restart.
- Manages multiple connections, but runs a single manager replica per metadata/backup directory pair. Database names for jobs must start with a letter or
_, followed by letters/digits/_/-, up to 63 characters. - The scheduler uses the timezone chosen by the admin in the UI (defaulting to
TZ); changes apply immediately without a restart. The UI shows timestamps in the browser's timezone, labeled with the scheduler timezone. - No support yet for PITR/WAL, volume snapshots, incremental file backups, overwrite restores or managing globals/roles through the UI. Upload directory backups are supported via Files connections.
pg_dumpsaves a single database. Roles/tablespaces must be backed up separately withpg_dumpall --globals-only, stored and protected separately since they may contain sensitive information. Logical dumps do not provide point-in-time recovery (PITR). See PostgreSQL pg_dump.pg_restore --listchecks the archive's table of contents and SHA-256 detects changes since creation/upload; neither proves data correctness or source trustworthiness. Restoring an archive may execute SQL controlled by its source; only use trusted archives. See PostgreSQL pg_restore.- Client and server versions need not match, but the dump client must not be older than the server, and archives from a newer client may not be readable by an older one. Restoring to an older server requires separate DBA assessment.
Issues and pull requests for bug fixes, documentation, translations or new features are welcome. For larger changes, open an issue first to discuss the scope and approach before writing code.
When reporting a bug, include the version or commit, deployment method, database type/version, steps to reproduce, expected result and logs with private information redacted. For feature requests, describe the use case and the desired behavior.
- Fork the repository and create a branch for your change.
- Keep changes focused; add documentation and tests that match the changed behavior.
- Run
make test. If you change the frontend, runcd web && npm ci && npm run build. If you change PostgreSQL backup/restore, also runsh scripts/integration.shwith Docker and the PostgreSQL client inPATH. - Open a pull request describing the problem, the change and how it was tested. Call out anything not tested against a real database.
Do not put passwords, tokens, encryption keys, metadata, backup data or private infrastructure addresses in issues, pull requests or test fixtures. Use the example.com domain and fake data for examples.
cmd/server/ Server entry point and CLI
internal/manager/ API, connections, backup/restore, scheduling, cloud and tests
web/ React + TypeScript UI
scripts/ Docker image build/push and PostgreSQL integration tests
deploy/ Compose, environment template and Portainer guide
Dockerfile Builds the frontend, backend and client tools
docker-compose.yml Runs the app from source
.env.example Configuration template for Docker Compose
Makefile Development and test commands
The repository only ships sample configuration. Supply accounts, passwords, OAuth settings and the Docker network yourself via the environment or a local .env file; enter database, cloud and notification details in the UI. When pushing/deploying the image, provide your own repository via IMAGE; no private registry is preconfigured.
The .gitignore and .dockerignore rules exclude local environment files, private keys/certificates, rclone configs, AWS/SSH/Docker credentials, metadata and backup archives at their default locations. When customizing paths or adding config files, check them before committing. Files already tracked by Git are not removed by adding ignore rules.
Connection passwords and cloud configs are encrypted with the connections.key file next to the metadata. Back up both the metadata and this key to be able to restore your configuration. Local backups are not age-encrypted automatically; age encryption applies before upload to the cloud. Protect access to the server, the data directory and the decryption keys.
Only restore archives from trusted sources. Checksum and format checks do not replace verifying data after a restore. Read the operating procedure and limitations before using this for important data.
If a secret has been exposed, revoke or rotate it; removing it from the current version does not remove it from Git history. When reporting a security issue, do not post secrets, real data or sensitive exploit details in a public issue; use the hosting platform's private reporting channel if the repository has it enabled.
This project is released under the MIT license.



