Database settings
The following databases are supported by this application:
SQLite
MySQL
PostgreSQL
MongoDB
…and any other that you might implement
By default, DBBackup will try to use your database settings in DATABASES
to handle the database, but some databases require custom options so you might
want to use different parameters for backups. That’s why we included a
DBBACKUP_CONNECTORS
setting; it follows the form of the django DATABASES
setting:
DBBACKUP_CONNECTORS = {
'default': {
'USER': 'backupuser',
'PASSWORD': 'backuppassword',
'HOST': 'replica-for-backup'
}
}
This configuration will allow you to use a replica with a different host and user, which is a great practice if you don’t want to overload your main database.
DBBackup uses Connectors
for creating and restoring backups; below you’ll see
specific parameters for the built-in ones.
Common
All connectors have the following parameters:
CONNECTOR
Absolute path to a connector class by default is:
dbbackup.db.sqlite.SqliteConnector
for'django.db.backends.sqlite3'
dbbackup.db.mysql.MysqlDumpConnector
fordjango.db.backends.mysql
dbbackup.db.postgresql.PgDumpConnector
fordjango.db.backends.postgresql
dbbackup.db.postgresql.PgDumpGisConnector
fordjango.contrib.gis.db.backends.postgis
dbbackup.db.mongodb.MongoDumpConnector
fordjango_mongodb_engine
All supported built-in connectors are described in more detail below.
Following database wrappers from django-prometheus
module are supported:
django_prometheus.db.backends.postgresql
fordbbackup.db.postgresql.PgDumpBinaryConnector
django_prometheus.db.backends.sqlite3
fordbbackup.db.sqlite.SqliteConnector
django_prometheus.db.backends.mysql
fordbbackup.db.mysql.MysqlDumpConnector
django_prometheus.db.backends.postgis
fordbbackup.db.postgresql.PgDumpGisConnector
EXCLUDE
Tables to exclude from backup as list. This option may be unavailable for connectors when making snapshots.
EXTENSION
Extension of backup file name, default 'dump'
.
Command connectors
Some connectors use a command line tool as a dump engine, mysqldump
for
example. These kinds of tools have common attributes:
DUMP_CMD
Path to the command used to create a backup; default is the appropriate
command supposed to be in your PATH, for example: 'mysqldump'
for MySQL.
This setting is useful only for connectors using command line tools (children
of dbbackup.db.base.BaseCommandDBConnector
)
RESTORE_CMD
Same as DUMP_CMD
but used when restoring.
DUMP_PREFIX and RESTORE_PREFIX
String to include as prefix of dump or restore command. It will be added with a space between the launched command and its prefix.
DUMP_SUFFIX and RESTORE_SUFFIX
String to include as suffix of dump or restore command. It will be added with a space between the launched command and its suffix.
ENV, DUMP_ENV and RESTORE_ENV
Environment variables used during command running, default are {}
. ENV
is used for every command, DUMP_ENV
and RESTORE_ENV
override the
values defined in ENV
during the dedicated commands.
USE_PARENT_ENV
Specify if the connector will use its parent’s environment variables. By
default it is True
to keep PATH
.
SQLite
SQLite uses by default dbbackup.db.sqlite.SqliteConnector
.
SqliteConnector
It is in pure Python and copies the behavior of .dump
command for creating a
SQL dump.
SqliteCPConnector
You can also use dbbackup.db.sqlite.SqliteCPConnector
for making a
simple raw copy of your database file, like a snapshot.
In-memory database aren’t dumpable with it.
MySQL
MySQL uses by default dbbackup.db.mysql.MysqlDumpConnector
. It uses
mysqldump
and mysql
for its job.
PostgreSQL
Postgres uses by default dbbackup.db.postgresql.PgDumpConnector
, but
we advise you to use dbbackup.db.postgresql.PgDumpBinaryConnector
. The
first one uses pg_dump
and pqsl
for its job, creating RAW SQL files.
The second uses pg_restore
with binary dump files.
They can also use psql
for launching administration command.
SINGLE_TRANSACTION
When doing a restore, wrap everything in a single transaction, so errors cause a rollback.
This corresponds to --single-transaction
argument of psql
and
pg_restore
.
Default: True
DROP
With PgDumpConnector
, it includes tables dropping statements in dump file.
PgDumpBinaryConnector
drops at restoring.
This corresponds to --clean
argument of pg_dump
and pg_restore
.
Default: True
IF_EXISTS
Use DROP … IF EXISTS commands to drop objects in --clean
mode of pg_dump
.
Default: False
PostGIS
Set in dbbackup.db.postgresql.PgDumpGisConnector
, it does the same as
PostgreSQL but launches CREATE EXTENSION IF NOT EXISTS postgis;
before
restore database.
PSQL_CMD
Path to psql
command used for administration tasks like enable PostGIS
for example, default is psql
.
PASSWORD
If you fill this settings PGPASSWORD
environment variable will be used
with every commands. For security reason, we advise to use .pgpass
file.
ADMIN_USER
Username used for launch action with privileges, extension creation for example.
ADMIN_PASSWORD
Password used for launch action with privileges, extension creation for example.
SCHEMAS
Specify schemas for database dumps by using a pattern-matching option, including both the selected schema and its contained objects. If not specified, the default behavior is to dump all non-system schemas in the target database. This feature is exclusive to PostgreSQL connectors, and users can choose multiple schemas for a customized dump.
MongoDB
MongoDB uses by default dbbackup.db.mongodb.MongoDumpConnector
. it
uses mongodump
and mongorestore
for its job.
For AuthEnabled MongoDB Connection, you need to add one custom option AUTH_SOURCE
in your DBBACKUP_CONNECTORS
.
DBBACKUP_CONNECTORS = {
'default': {
...
'AUTH_SOURCE': 'admin',
}
}
Or in DATABASES
one:
DATABASES = {
'default': {
...
'AUTH_SOURCE': 'admin',
}
}
OBJECT_CHECK
Validate documents before inserting in database (option --objcheck
in command line), default is True
.
DROP
Replace objects that are already in database, (option --drop
in command line), default is True
.
Custom connector
Creating your connector is easy; create a children class from
dbbackup.db.base.BaseDBConnector
and create _create_dump
and
_restore_dump
. If your connector uses a command line tool, inherit it from
dbbackup.db.base.BaseCommandDBConnector
Connecting a Custom connector
Here is an example, on how to easily connect a custom connector that you have created or even that you simply want to reuse:
DBBACKUP_CONNECTOR_MAPPING = {
'transaction_hooks.backends.postgis': 'dbbackup.db.postgresql.PgDumpGisConnector',
}
Obviously instead of dbbackup.db.postgresql.PgDumpGisConnector
you can
use the custom connector you have created yourself and transaction_hooks.backends.postgis
is simply the database engine name you are using.