5.3.0 (#669)

Author: Archmonger

CHANGELOG.md

@@ -14,6 +14,10 @@ Don't forget to remove deprecated code on each major release!
 
 ## [Unreleased]
 
+- Nothing (yet)!
+
+## [5.3.0] - 2026-04-09
+
 ### Fixed
 
 - Fix compression when using `DjangoConnector`.
@@ -356,7 +360,8 @@ Don't forget to remove deprecated code on each major release!
 
 - Miscellaneous maintenance and minor bug fixes.
 
-[Unreleased]: https://github.com/Archmonger/django-dbbackup/compare/5.2.0...HEAD
+[Unreleased]: https://github.com/Archmonger/django-dbbackup/compare/5.3.0...HEAD
+[5.3.0]: https://github.com/Archmonger/django-dbbackup/compare/5.2.0...5.3.0
 [5.2.0]: https://github.com/Archmonger/django-dbbackup/compare/5.1.2...5.2.0
 [5.1.2]: https://github.com/Archmonger/django-dbbackup/compare/5.1.1...5.1.2
 [5.1.1]: https://github.com/Archmonger/django-dbbackup/compare/5.1.0...5.1.1

dbbackup/__init__.py

@@ -1,3 +1,3 @@
 """Management commands to help backup and restore a project database and media"""
 
-__version__ = "5.2.0"
+__version__ = "5.3.0"

docs/src/commands.md

@@ -8,12 +8,14 @@ restore the most recent matching backup.
 
 Use `python manage.py <command> --help` for full option details.
 
+---
+
 ## dbbackup
 
 Create a database backup (optionally compressed/encrypted) and upload it.
 
 ```bash
-$ ./manage.py dbbackup
+$ python manage.py dbbackup
 Backing Up Database: tmp.x0kN9sYSqk
 Backup size: 3.3 KiB
 Writing file to tmp-zuluvm-2016-07-29-100954.dump
@@ -30,7 +32,7 @@ python manage.py dbbackup --help
 Download the latest database backup (or a specified one) then restore it.
 
 ```bash
-$ ./manage.py dbrestore
+$ python manage.py dbrestore
 Restoring backup for database: tmp.x0kN9sYSqk
 Finding latest backup
 Restoring: tmp-zuluvm-2016-07-29-100954.dump
@@ -49,7 +51,7 @@ Create an archive (tar) of media files, optionally compress/encrypt, and upload
 it to backup storage.
 
 ```bash
-$ ./manage.py mediabackup
+$ python manage.py mediabackup
 Backup size: 10.0 KiB
 Writing file to zuluvm-2016-07-04-081612.tar
 ```
@@ -65,7 +67,7 @@ python manage.py mediabackup --help
 Restore media files: extract files from the archive and put them into media storage.
 
 ```bash
-$ ./manage.py mediarestore
+$ python manage.py mediarestore
 Restoring backup for media files
 Finding latest backup
 Reading file zuluvm-2016-07-04-082551.tar

docs/src/configuration.md

@@ -1,6 +1,8 @@
 # Configuration
 
-## General settings
+---
+
+## General
 
 ### DBBACKUP_DATABASES
 
@@ -102,7 +104,9 @@ default this is `settings.MEDIA_ROOT`.
 
 Default: `settings.MEDIA_ROOT`
 
-## Encrypting your backups
+---
+
+## Encryption
 
 Backups may contain personal or otherwise sensitive data. When storing them
 outside trusted infrastructure you should encrypt them. Keep your private
@@ -164,7 +168,9 @@ connector mapping.
 
 Default: `{}`
 
-## Email configuration
+---
+
+## Email
 
 ### DBBACKUP_SEND_EMAIL
 
@@ -194,18 +200,9 @@ Subject-line prefix for email messages sent by DBBackup.
 
 Default: `'[dbbackup] '`
 
-## Database configuration
-
-By default DBBackup uses values from `settings.DATABASES`. Use
-`DBBACKUP_CONNECTORS` (documented above) for backup specific overrides. See
-[Database settings](databases.md) for backend specific options.
-
-## Storage configuration
-
-You must configure a storage backend (`STORAGES['dbbackup']`) to persist
-backups. See [Storage settings](storage.md) for supported options.
+---
 
-## Custom metadata
+## Metadata
 
 ### DBBACKUP_BACKUP_METADATA_SETTER
 
@@ -254,3 +251,18 @@ def validate_restore(metadata):
 
 DBBACKUP_RESTORE_METADATA_VALIDATOR = validate_restore
 ```
+
+---
+
+## Database
+
+By default DBBackup uses values from `settings.DATABASES`. Use
+`DBBACKUP_CONNECTORS` (documented above) for backup specific overrides. See
+[Database settings](databases.md) for backend specific options.
+
+---
+
+## Storage
+
+You must configure a storage backend (`STORAGES['dbbackup']`) to persist
+backups. See [Storage settings](storage.md) for supported options.

docs/src/databases.md

@@ -8,6 +8,14 @@ The following databases are supported by this application:
 - MongoDB
 - ... and any other Django-supported database (via `DjangoConnector`)
 
+DBBackup uses “connector” classes to implement backend specific dump and
+restore logic. Each connector may expose additional settings documented
+below.
+
+---
+
+## Settings Overrides
+
 By default DBBackup reuses connection details from `settings.DATABASES`.
 Sometimes you want different credentials or a different host (e.g. read-only
 replica) just for backups. Use `DBBACKUP_CONNECTORS` for that purpose; it
@@ -26,9 +34,7 @@ DBBACKUP_CONNECTORS = {
 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 “connector” classes to implement backend specific dump and
-restore logic. Each connector may expose additional settings documented
-below.
+---
 
 ## Common Settings
 
@@ -50,8 +56,7 @@ DBBACKUP_CONNECTORS = {
 }
 ```
 
-Some connectors use a command line tool as a dump engine, `mysqldump` for
-example. These kinds of tools have common attributes:
+Additionally, some connectors within this repository use a command line tool as a dump engine, (`MysqlDumpConnector` for example). These kinds of connectors have additional common attributes:
 
 | Setting                      | Description                                                                                                                                                           | Default                                |
 | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
@@ -73,12 +78,20 @@ DBBACKUP_CONNECTORS = {
 }
 ```
 
-## Built-in Database Connectors
+---
+
+## Database Connectors
 
 These connectors are provided by default and are designed to work with specific database engines. They provide optimized backup and restore functionality.
 
 ### SQLite
 
+#### Settings
+
+SQLite connectors do not define any configurable settings beyond the common settings documented above.
+
+However, note that only the `SqliteConnector` supports the common `EXCLUDE` setting.
+
 #### SqliteBackupConnector
 
 The `dbbackup.db.sqlite.SqliteBackupConnector` makes a copy of the SQLite database file using the `.backup` command, which is safe to execute while the database has ongoing/active connections.
@@ -99,12 +112,20 @@ In-memory databases are **not** dumpable with it. Since it works by copying the
 
 ### MySQL
 
-MySQL defaults to `dbbackup.db.mysql.MysqlDumpConnector` which shells out to
-`mysqldump` for creation and `mysql` for restore.
+#### Settings
 
-### PostgreSQL
+MySQL connectors do not define any configurable settings beyond the common settings documented above.
+
+However, note that when the common `EXCLUDE` setting is configured in your Django database, each table name is passed to `mysqldump` as `--ignore-table=<database>.<table>`, so the values should be plain table
+names from the target database.
+
+#### MysqlDumpConnector
 
-All PostgreSQL connectors have the following settings:
+The `dbbackup.db.mysql.MysqlDumpConnector` creates a SQL dump with `mysqldump` and restores it by piping the dump into `mysql`.
+
+This is the default connector for MySQL databases.
+
+### PostgreSQL
 
 #### Settings
 
@@ -139,6 +160,15 @@ restoring the database.
 
 ### MongoDB
 
+#### Settings
+
+| Setting      | Description                                         | Default |
+| ------------ | --------------------------------------------------- | ------- |
+| OBJECT_CHECK | Validate documents before inserting (`--objcheck`). | `True`  |
+| DROP         | Replace existing objects during restore (`--drop`). | `True`  |
+
+#### MongoDumpConnector
+
 MongoDB uses by default `dbbackup.db.mongodb.MongoDumpConnector`. It
 uses `mongodump` and `mongorestore` for its job.
 
@@ -165,25 +195,25 @@ DATABASES = {
 }
 ```
 
-#### Settings
+### All Databases (Universal)
 
-| Setting      | Description                                         | Default |
-| ------------ | --------------------------------------------------- | ------- |
-| OBJECT_CHECK | Validate documents before inserting (`--objcheck`). | `True`  |
-| DROP         | Replace existing objects during restore (`--drop`). | `True`  |
+The Django connector (`dbbackup.db.django.DjangoConnector`) provides database-agnostic backup and restore functionality using Django's built-in `dumpdata` and `loaddata` management commands. This connector works with any Django-supported database backend.
 
-### Django-Prometheus
+Key features include:
 
-All supported built-in connectors are described in more detail below. Following database wrappers from `django-prometheus` are supported:
+- **Universal compatibility**: Works with any database backend supported by Django
+- **No external dependencies**: Uses Django's serialization system
+- **Model-level backups**: Preserves foreign key relationships and data integrity
+- **JSON format**: Creates human-readable backups in JSON format
 
-- `django_prometheus.db.backends.postgresql`
-- `django_prometheus.db.backends.sqlite3`
-- `django_prometheus.db.backends.mysql`
-- `django_prometheus.db.backends.postgis`
+The Django connector is ideal for:
 
-## Django Connector
+- Oracle databases (used by default)
+- Custom or third-party database backends not explicitly supported
+- Development environments where simplicity is preferred
+- Cases where external database tools are not available
 
-The Django connector (`dbbackup.db.django.DjangoConnector`) provides database-agnostic backup and restore functionality using Django's built-in `dumpdata` and `loaddata` management commands. This connector works with any Django-supported database backend.
+#### DjangoConnector
 
 This connector is automatically used for any unmapped database engines. If needed, you can explicitly configure it:
 
@@ -195,30 +225,21 @@ DBBACKUP_CONNECTORS = {
 }
 ```
 
-### Key Features
-
-- **Universal compatibility**: Works with any database backend supported by Django
-- **No external dependencies**: Uses Django's serialization system
-- **Model-level backups**: Preserves foreign key relationships and data integrity
-- **JSON format**: Creates human-readable backups in JSON format
-
-### When to Use
-
-The Django connector is ideal for:
-
-- Oracle databases (used by default)
-- Custom or third-party database backends not explicitly supported
-- Development environments where simplicity is preferred
-- Cases where external database tools are not available
-
-### Limitations
+#### Limitations
 
 - **Performance**: Slower than native database tools for large datasets
 - **Database structure**: Only provides backups of data; not database schema, indices, or procedures
 
-### File Extension
+### Django Prometheus (External)
+
+All supported built-in connectors are described in more detail below. Following database wrappers from `django-prometheus` are supported:
+
+- `django_prometheus.db.backends.postgresql`
+- `django_prometheus.db.backends.sqlite3`
+- `django_prometheus.db.backends.mysql`
+- `django_prometheus.db.backends.postgis`
 
-By default, backups use the `.json` extension.
+---
 
 ## Custom Connectors