Django DBBackup

Common errors

• ImproperlyConfigured: DBBACKUP_STORAGE setting has been removed in favor of Django's STORAGES setting.

  cause Using the deprecated `DBBACKUP_STORAGE` or `DBBACKUP_STORAGE_OPTIONS` settings in `settings.py`.
  fix Update your `settings.py` to use `STORAGES = {'dbbackup': {...}}` as per the documentation. For example, `STORAGES = {'dbbackup': {'BACKEND': 'django.core.files.storage.FileSystemStorage', 'OPTIONS': {'location': '/path/to/backups/'}}}`.

• dbbackup.db.exceptions.CommandConnectorError: Error running: pg_dump ... [Errno 2] No such file or directory: 'pg_dump'

  cause The `pg_dump` executable (or equivalent for other databases) is not found in the system's PATH where the Django application is running.
  fix Install the appropriate database client tools (e.g., `postgresql-client-common` or `postgresql-client` on Linux) in the environment where your Django app is running, and ensure they are discoverable in the system's PATH.

• CommandError: Error running: [u'dropdb', u'--username=dev', u'--host=localhost', u'mydatabase'] FATAL: database "mydatabase" does not exist or FATAL: permission denied for database "mydatabase"

  cause `dbrestore` attempts to drop and recreate the database, but the specified user lacks the necessary permissions, or the database doesn't exist to be dropped by the user.
  fix Ensure the database user configured in `settings.DATABASES` for the target database has `CREATEDB` privileges or is the owner of the database. Alternatively, use the `--no-drop` option for `dbrestore` (available since 4.2.1) if you want to avoid dropping tables.

• dbbackup.db.exceptions.CommandConnectorError: Restoring to a different database engine is not supported. Backup was for 'django.db.backends.postgresql', but you are restoring to a database using 'django.db.backends.sqlite3'.

  cause Attempting to restore a database backup created for one type of database (e.g., PostgreSQL) to a different type of database (e.g., SQLite). This check was introduced for data integrity.
  fix Restore the backup to a database with the same `ENGINE` as it was created from. For cross-database migrations, use Django's `dumpdata` and `loaddata` utilities.

Warnings

• breaking The legacy settings `DBBACKUP_STORAGE` and `DBBACKUP_STORAGE_OPTIONS` were removed in version 5.0.1.
  Fix: Migrate your storage configuration to use Django's standard `STORAGES` setting under the 'dbbackup' key. Refer to the official documentation's 'Storage' section for examples.
• gotcha By default, `dbrestore` prevents restoring a backup created for one database engine (e.g., PostgreSQL) to a different engine (e.g., SQLite) by checking metadata.
  Fix: Always restore backups to a database using the same engine they were created from. If you need to migrate between database types, use Django's `dumpdata` and `loaddata` commands.
• gotcha The `dbbackup` command relies on external database utilities like `pg_dump` (PostgreSQL) or `mysqldump` (MySQL) being available in the system's PATH where the command is executed.
  Fix: Ensure the necessary database client tools (e.g., `postgresql-client` for `pg_dump`) are installed and their executables are accessible in the PATH of the environment running `manage.py dbbackup`. In Docker, this often means installing them in the same container as your Django app or executing the backup from the database container itself.
• gotcha Configuring backup storage with the same configuration as your media files (e.g., `DEFAULT_FILE_STORAGE`) can risk exposing sensitive backups in public directories.
  Fix: Always configure `STORAGES['dbbackup']` with a dedicated and distinct storage location, preferably with restricted permissions, separate from your `MEDIA_ROOT`.

Install

• pip install django-dbbackup Install latest version

Imports

• dbbackup
  wrong:

  import dbbackup; dbbackup.some_function()

  correct:

  Django management commands are run via `python manage.py dbbackup`

  django-dbbackup is primarily designed to be interacted with via Django management commands (e.g., `dbbackup`, `dbrestore`, `mediabackup`), not direct Python imports for command execution. Direct imports are typically only for extending functionality like custom connectors or signal receivers.

Quickstart

1. Add 'dbbackup' to your `INSTALLED_APPS` in `settings.py`. 2. Configure a `STORAGES['dbbackup']` entry to define where your backups will be stored. It's recommended to use a dedicated directory, not your `MEDIA_ROOT`, to avoid accidental public exposure. 3. Run `python manage.py dbbackup` to create a database backup and `python manage.py mediabackup` for media files. Use `dbrestore` and `mediarestore` to restore.

import os
from pathlib import Path

# settings.py
BASE_DIR = Path(__file__).resolve().parent.parent

INSTALLED_APPS = [
    # ... other apps
    'dbbackup',
]

# Configure a storage backend for backups
# Using FileSystemStorage for local backups
DB_BACKUP_LOCATION = os.path.join(BASE_DIR, 'my_backups')
os.makedirs(DB_BACKUP_LOCATION, exist_ok=True)

STORAGES = {
    "dbbackup": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
        "OPTIONS": {
            "location": DB_BACKUP_LOCATION,
        },
    },
}

# Example of running commands (from your project root)
# Make a backup:
# python manage.py dbbackup --noinput
# python manage.py mediabackup --noinput

# Restore latest backup:
# python manage.py dbrestore --noinput
# python manage.py mediarestore --noinput