Metadata-Version: 2.4
Name: dj-dbbackup
Version: 0.1.0
Summary: Reusable Django app for PostgreSQL backup, restore, and preview seeding via S3.
Author: Ionisium
Project-URL: Homepage, https://github.com/dakixr/dj-dbbackup
Project-URL: Repository, https://github.com/dakixr/dj-dbbackup
Project-URL: Issues, https://github.com/dakixr/dj-dbbackup/issues
Keywords: django,postgresql,backup,restore,s3
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34
Requires-Dist: Django>=4.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-django>=4.8; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"

# 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

```bash
pip install dj-dbbackup
```

Add the app to Django:

```python
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:

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

## Commands

Create a backup:

```bash
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:

```bash
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:

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

List or delete backups:

```bash
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:

```bash
python -m build
```

Validate the built metadata:

```bash
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`.
