dj-dbbackup 0.1.0

Reusable Django app for PostgreSQL backup, restore, and preview seeding via S3.

dj-dbbackup

dj-dbbackup is a reusable Django app for PostgreSQL backup, restore, and preview-database seeding using S3-compatible object storage.

It started as Ionisium's internal dbbackup app, then was extracted so multiple Django projects can share the same workflow.

Features

• backup_db management command for timestamped PostgreSQL SQL dumps
• restore_db management command for restoring a named dump from S3
• seed_db management command for "restore only if the database is still empty"
• list_backups and delete_backup management commands
• S3 bucket bootstrap on first use
• Configurable connection overrides and host aliases
• Retention cleanup and optional latest.sql alias for preview deployments

Installation

pip install dj-dbbackup

Add the app to Django:

INSTALLED_APPS = [
    ...,
    "dj_dbbackup",
]

Configuration

Preferred setting names:

Setting	Description
DJ_DBBACKUP_BUCKET	Required bucket name used for backup storage.
DJ_DBBACKUP_ENV	Backup namespace, defaults to settings.CURRENT_ENV and then LOCAL.
DJ_DBBACKUP_AWS_REGION	S3 region, defaults to settings.AWS_S3_REGION_NAME and then us-east-1.
DJ_DBBACKUP_PG_DUMP_BIN	Optional absolute path to pg_dump.
DJ_DBBACKUP_PSQL_BIN	Optional absolute path to psql.
DJ_DBBACKUP_CONNECTION_OVERRIDES	Optional dict merged into DATABASES["default"].
DJ_DBBACKUP_HOST_ALIASES	Optional dict mapping logical DB hosts to actual hosts.
DJ_DBBACKUP_UNSUPPORTED_SETTINGS	Dump SET statements stripped during restore. Defaults to ("transaction_timeout",).
DJ_DBBACKUP_EMPTY_TABLE_EXCLUDES	Optional iterable of table names ignored by seed_db when checking emptiness.

Legacy Ionisium-style names such as DB_BACKUP_S3_BUCKET are still accepted for compatibility.

Minimal example:

DJ_DBBACKUP_BUCKET = "myapp-db-backups"
DJ_DBBACKUP_ENV = "DEV"
DJ_DBBACKUP_CONNECTION_OVERRIDES = {"HOST": "db"}

Commands

Create a backup:

python manage.py backup_db --latest-alias latest.sql --keep-count 5

Useful options:

• --env DEV
• --db-host host.docker.internal
• --filename-prefix preview-seed
• --latest-alias latest.sql
• --keep-count 5

Restore a backup:

python manage.py restore_db DEV-20260309120000.sql --env DEV
python manage.py restore_db latest.sql --env DEV

Seed only if the database is empty:

python manage.py seed_db latest.sql --env DEV

List or delete backups:

python manage.py list_backups --env DEV
python manage.py delete_backup latest.sql --env DEV

Preview deployment pattern

One common workflow is:

1. Scheduled job in DEV runs backup_db --latest-alias latest.sql --keep-count 5.
2. PR preview containers run seed_db latest.sql --env DEV.
3. Migrations run after the restore completes.

That keeps preview databases reproducible without project-specific shell restore logic.

Requirements

• PostgreSQL client tools available in the runtime image
• AWS credentials or another supported boto3 credential source
• Access to s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket, and optionally s3:CreateBucket

Packaging

Build a distribution:

python -m build

Validate the built metadata:

python -m twine check dist/*

Publishing is handled by GitHub Actions with PyPI Trusted Publishing. The exact one-time PyPI setup and tag-based release process are documented in docs/RELEASING.md.