Install
SQLBackup is a Python package and runs on Windows and Linux. Install it with pip:
# everything (S3 + SFTP + SQL Server extras)
pip install "sqlbackup[all]"
# or pick only what you need
pip install "sqlbackup[s3,sftp]"
Quick start
Five commands take you from nothing to a running, scheduled backup agent:
sqlbackup init # writes config.yaml
# set secrets as env vars, e.g. (PowerShell):
# $env:PG_PASSWORD = "..."
sqlbackup test # check DB + destination connectivity
sqlbackup backup --job pg_nightly_full
sqlbackup history # see what ran
sqlbackup run # start the scheduler (runs continuously)
Databases
List each database you want to protect. Use password_env to read the password from an environment variable instead of storing it on disk.
databases:
- name: prod_postgres
type: postgres # postgres | mysql | mariadb | sqlserver | mongodb
host: localhost
port: 5432
user: postgres
password_env: PG_PASSWORD
databases: [app]
Destinations
Define where backups are stored. Any S3-compatible provider works by adding an endpoint_url.
destinations:
- name: local_backups
type: local
path: D:\Backups
- name: amazon_s3
type: s3
bucket: my-backups
region: us-east-1
access_key_env: AWS_ACCESS_KEY_ID
secret_key_env: AWS_SECRET_ACCESS_KEY
Jobs & schedules
A job ties a database to destinations, a schedule, a backup type, and a retention policy. Schedules use standard 5-field cron.
jobs:
- name: pg_nightly_full
database: prod_postgres
backup_type: full # full | differential | log (SQL Server)
schedule: "0 2 * * *" # every day at 02:00
destinations: [local_backups, amazon_s3]
compress: true
encrypt: true
retention: { keep_last: 14, keep_days: 30 }
Prefer not to hand-write YAML? Use the interactive config builder to generate this.
Secrets & encryption
Backups are encrypted with AES-256-GCM when a job sets encrypt: true. The key is derived from a password you supply via an environment variable.
encryption:
password_env: SQLBACKUP_ENC_PASSWORD
Keep this password safe. If you lose it, encrypted backups cannot be recovered — there is no backdoor. Store it in a password manager or secrets vault. See the
security model.
Email alerts
Get notified when a backup fails (and optionally on success) over SMTP/TLS.
notifications:
email:
enabled: true
smtp_host: smtp.example.com
smtp_port: 587
use_tls: true
username: alerts@example.com
password_env: SMTP_PASSWORD
to_addrs: [ops@example.com]
on_failure: true
on_success: false
CLI reference
init
Write a starter config.yaml in the current directory.
test
Check connectivity to every configured database and destination.
backup --job NAME
Run a single backup job now, on demand.
restore
Download, decrypt, decompress and restore a backup. See below.
history
Show recent backup runs with status, size and timing.
status
Print the dashboard summary (health %, totals, attention list).
run
Start the continuous scheduler — fires jobs on their cron schedules.
Restoring a backup
Restore is a single command. SQLBackup finds the object, decrypts and verifies it, decompresses it, and restores into the database you name — usually a fresh one so you can verify before promoting.
sqlbackup restore --job pg_nightly_full --from amazon_s3 \
--key "pg_nightly_full/app/app_full_20260626_020000.dump.gz.enc" \
--database app_restored
Watch the full sequence in the interactive restore demo.