Connectors

Database connectors handle the database-specific dump and restore logic. The correct connector is selected automatically from DATABASES[alias]["ENGINE"], or you can specify one explicitly in database_connectors.

Protocol

class django_snapshots.connectors.protocols.DatabaseConnector(*args, **kwargs)

Interface for dumping and restoring a single database alias.

__init__(*args, **kwargs)

dump(db_alias: str, dest: Path) → dict[str, Any]

Dump the database to dest and return artifact metadata.

restore(db_alias: str, src: Path) → None

Restore the database from the dump file at src.

Auto-detection

django_snapshots.connectors.auto.get_connector_class(engine: str) → type

Return the connector class for engine (a DATABASES ENGINE string).

Falls back to DjangoDumpDataConnector for unrecognised engines.

django_snapshots.connectors.auto.get_connector_for_alias(db_alias: str) → DatabaseConnector

Return a connector instance for db_alias.

Checks SNAPSHOTS.database_connectors for an override first, then auto-detects from DATABASES[db_alias]["ENGINE"].

Engine mapping

ENGINE substring	Connector
sqlite3	SQLiteConnector
postgresql, postgis	PostgresConnector
mysql	MySQLConnector
(anything else)	DjangoDumpDataConnector

Built-in connectors

SQLiteConnector

Uses Python’s stdlib sqlite3 module. No external binaries required.

class django_snapshots.SQLiteConnector

Back up and restore SQLite databases using the stdlib sqlite3 module.

dump(db_alias: str, dest: Path) → dict[str, Any]

Dump the SQLite database for db_alias to a SQL script at dest.

restore(db_alias: str, src: Path) → None

Restore the SQLite database for db_alias from the SQL script at src.

PostgresConnector

Uses pg_dump and psql. Requires these binaries on PATH. The database password is passed via the PGPASSWORD environment variable.

class django_snapshots.PostgresConnector

Back up and restore PostgreSQL databases using pg_dump and psql.

dump(db_alias: str, dest: Path) → dict[str, Any]

Dump the PostgreSQL database to dest using pg_dump.

restore(db_alias: str, src: Path) → None

Restore the PostgreSQL database from src using psql.

MySQLConnector

Uses mysqldump and mysql. Requires these binaries on PATH. Works for both MySQL and MariaDB.

class django_snapshots.MySQLConnector

Back up and restore MySQL/MariaDB databases using mysqldump and mysql.

dump(db_alias: str, dest: Path) → dict[str, Any]

Dump the MySQL/MariaDB database to dest using mysqldump.

restore(db_alias: str, src: Path) → None

Restore the MySQL/MariaDB database from src using mysql.

DjangoDumpDataConnector

Uses Django’s built-in dumpdata and loaddata management commands. Works with any database backend and requires no external binaries. This is the automatic fallback for unrecognised engines.

Note

dumpdata / loaddata use Django’s JSON serialisation format, which does not preserve all database-native types (e.g. custom PostgreSQL types). For production PostgreSQL or MySQL, prefer the native connectors.

class django_snapshots.DjangoDumpDataConnector

Back up and restore using dumpdata / loaddata.

dump(db_alias: str, dest: Path) → dict[str, Any]

Dump all data for db_alias to a JSON file at dest.

Returns metadata dict with format key.

restore(db_alias: str, src: Path) → None

Restore all data for db_alias from the JSON dump at src.

Writing a custom connector

Implement dump() and restore() on any class. Register it in settings:

from pathlib import Path
from typing import Any

class OracleConnector:
    def dump(self, db_alias: str, dest: Path) -> dict[str, Any]:
        # Run expdp, return metadata dict
        return {"format": "dmp"}

    def restore(self, db_alias: str, src: Path) -> None:
        # Run impdp
        pass

# In Django settings:
SNAPSHOTS = {
    "DATABASE_CONNECTORS": {"default": OracleConnector()},
}