Quick start
You need Docker, and nothing else. pgb is a small script around docker run. It keeps your settings in a .env file in one folder, and every pgb command uses the .env of the folder you run it in.
-
Install
pgb.Terminal window curl -fsSL https://raw.githubusercontent.com/iotabyt/pgbackup-r2/main/scripts/install.sh | shIf
~/.local/binisn’t on yourPATH, the installer prints the line to add for your shell. See Install pgb for details.Terminal window $d = Join-Path $HOME .pgb; New-Item -ItemType Directory -Force $d, (Split-Path $PROFILE) | Out-Null; irm https://raw.githubusercontent.com/iotabyt/pgbackup-r2/main/scripts/pgb.ps1 -OutFile (Join-Path $d pgb.ps1); if ("$(Get-Content -Raw $PROFILE -ErrorAction Ignore)" -notmatch 'function pgb ') { Add-Content $PROFILE "function pgb { & '$(Join-Path $d pgb.ps1)' @args }" }; . $PROFILE -
Make a folder for one database, with a
.env.Terminal window mkdir acme-backupscd acme-backupspgb initpgb initwrites a commented.envand an emptyout/folder. On Linux and macOS,.envis readable only by you. It never overwrites an existing.env. -
Make a key pair.
Terminal window pgb keygenThis prints a public key and a private key. Nothing is written to disk. Save the private key in your password manager now. If you lose it, nobody can open your backups, including you. Put the public key in
.envasAGE_RECIPIENTS=age1…. On your laptop, also uncommentAGE_IDENTITY=and paste the private key there, forverifyanddrill. See Keys and security. -
Fill in the rest of
.env. Only the 7 lines at the top are needed. Everything under “Optional” has a sensible default.Terminal window PG_MAJOR=17 # your server's major versionDATABASE_URL=postgresql://user:password@host:5432/acmeS3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.comS3_BUCKET=acme-db-backupsAWS_ACCESS_KEY_ID=...AWS_SECRET_ACCESS_KEY=...AGE_RECIPIENTS=age1...- Bucket and token: Set up R2 walks through creating them. Any other S3-compatible storage works too.
PG_MAJORmust match your server: runSHOW server_version;. See Postgres versions.- More than one app in a bucket? Uncomment
S3_PREFIXand give each app its own, likeS3_PREFIX=acme. DATABASE_URLmust be a direct, non-pooled connection.- A database on this machine can use
localhost, whichpgbhandles. - A database in Docker Compose needs
PGB_NETWORK, as in App on a VPS.
- A database on this machine can use
-
Check the setup.
Terminal window pgb doctor✓ Docker is running✓ .env found in /home/ama/acme-backups✓ Settings: everything a backup needs is set (storage: https://<account-id>.r2.cloudflarestorage.com)✓ Database: connected to postgresql://***@db:5432/acme, PostgreSQL 17.2✓ Bucket: s3://acme-db-backups/acme/ is writable (wrote and deleted a test file)✓ Keys: AGE_IDENTITY opens what is encrypted to AGE_RECIPIENTS⚠ This bucket has never been drilled.Run `pgb drill`.All checks passed.A ⚠ is worth a look but isn’t a failure. This one goes away after step 6.
Every ✗ comes with a fix underneath. Troubleshooting explains each message.
-
Back up, then prove it works.
Terminal window pgb backuppgb verifypgb drillbackupcounts every table’s rows, then dumps, encrypts and uploads.verifydownloads the latest backup, checks it and decrypts it. It takes a few seconds and needs no database.drillrestores the backup into a throwaway Postgres and compares every table’s row count with the manifest. It removes the database afterwards, whatever happens.
PASS acme/2026-11-18T020000Z.dump.age (48.2 MB, restored in 21.4s)37 tables and 1,284,903 rows match the manifest -
Back up every night. On a machine that’s always on and can reach the database:
Terminal window pgb nightly start # backs up at BACKUP_AT, default 02:00 UTCpgb nightly statusOn a server, leave
AGE_IDENTITYout of.env, and runverifyanddrillfrom your laptop instead. For a managed database with no server of your own, see Managed databases.
Set up R2: create the bucket and the token, step by step.
pgbackup-r2 is an open-source tool from Iotabyt. MIT licensed.