v5.0.1 (fix #645) (#646)

Archmonger · web-flow · commit 0ed283d9ec2f · 2025-11-07T02:57:19.000-08:00
* Implement deprecation error for DBBACKUP_STORAGE and DBBACKUP_STORAGE_OPTIONS fix #645 * fix #642 * Add breaking changes notice to changelog (fix #643) * fix #641
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+<!--docs-top-start-->
+
 # Django DBBackup
 
 <p>
@@ -17,7 +19,7 @@
 
 This Django application provides management commands to help backup and restore your project database and media files with various storages such as Amazon S3, Dropbox, local file storage, or any Django-supported storage.
 
-## Features
+The main features include:
 
 -   Secure your backup with GPG signature and encryption.
 -   Archive with compression.
@@ -26,14 +28,18 @@ This Django application provides management commands to help backup and restore
 -   Set up automated backups with Crontab or Celery.
 -   Manually backup and restore via Django management commands.
 
-## Documentation
+<!--docs-top-end-->
 
 For more details, see the [official documentation](https://archmonger.github.io/django-dbbackup/).
 
+<!--docs-bottom-start-->
+
 ## Why use DBBackup?
 
 DBBackup gives you a simple yet robust interface to backup, encrypt, transmit, and restore your database and media.
 
 In a few words, it is a pipe between your Django project and your backups. It is written to be far more efficient than Django's [backup](https://docs.djangoproject.com/en/stable/ref/django-admin/#dumpdata)/[restore](https://docs.djangoproject.com/en/stable/ref/django-admin/#loaddata) commands by using your database's native/standard/best procedure(s) or tool(s) to perform backups.
 
 Ultimately, this helps simplify the task of "creating a backup" by removing the need for writing relational query commands, using complex tools, or creating scripts. Optionally, DBBackup can apply compression and/or encryption before transferring the data to nearly any storage system.
+
+<!--docs-bottom-end-->
diff --git a/dbbackup/__init__.py b/dbbackup/__init__.py
@@ -1,3 +1,3 @@
 """Management commands to help backup and restore a project database and media"""
 
-__version__ = "5.0.0"
+__version__ = "5.0.1"
diff --git a/dbbackup/settings.py b/dbbackup/settings.py
@@ -1,50 +1,42 @@
-# DO NOT IMPORT THIS BEFORE django.configure() has been run!
-
 import socket
 import tempfile
 
 from django.conf import settings
 
-DATABASES = getattr(settings, "DBBACKUP_DATABASES", list(settings.DATABASES.keys()))
+# Raise an exception if DBBACKUP_STORAGE or DBBACKUP_STORAGE_OPTIONS is used
+if hasattr(settings, "DBBACKUP_STORAGE") or hasattr(settings, "DBBACKUP_STORAGE_OPTIONS"):
+    raise RuntimeError(
+        "The settings DBBACKUP_STORAGE and DBBACKUP_STORAGE_OPTIONS have been "
+        "deprecated in favor of using Django Storages configuration. "
+        "Please refer to the documentation for more details."
+    )
 
-# Fake host
+DATABASES = getattr(settings, "DBBACKUP_DATABASES", list(settings.DATABASES.keys()))
 HOSTNAME = getattr(settings, "DBBACKUP_HOSTNAME", socket.gethostname())
-
-# Directory to use for temporary files
 TMP_DIR = getattr(settings, "DBBACKUP_TMP_DIR", tempfile.gettempdir())
 TMP_FILE_MAX_SIZE = getattr(settings, "DBBACKUP_TMP_FILE_MAX_SIZE", 10 * 1024 * 1024)
 TMP_FILE_READ_SIZE = getattr(settings, "DBBACKUP_TMP_FILE_READ_SIZE", 1024 * 1000)
-
-# Number of old backup files to keep
 CLEANUP_KEEP = getattr(settings, "DBBACKUP_CLEANUP_KEEP", 10)
 CLEANUP_KEEP_MEDIA = getattr(settings, "DBBACKUP_CLEANUP_KEEP_MEDIA", CLEANUP_KEEP)
 CLEANUP_KEEP_FILTER = getattr(settings, "DBBACKUP_CLEANUP_KEEP_FILTER", lambda x: False)
-
 MEDIA_PATH = getattr(settings, "DBBACKUP_MEDIA_PATH", settings.MEDIA_ROOT)
-
 DATE_FORMAT = getattr(settings, "DBBACKUP_DATE_FORMAT", "%Y-%m-%d-%H%M%S")
 FILENAME_TEMPLATE = getattr(
     settings,
     "DBBACKUP_FILENAME_TEMPLATE",
     "{databasename}-{servername}-{datetime}.{extension}",
 )
 MEDIA_FILENAME_TEMPLATE = getattr(settings, "DBBACKUP_MEDIA_FILENAME_TEMPLATE", "{servername}-{datetime}.{extension}")
-
 GPG_ALWAYS_TRUST = getattr(settings, "DBBACKUP_GPG_ALWAYS_TRUST", False)
 GPG_RECIPIENT = GPG_ALWAYS_TRUST = getattr(settings, "DBBACKUP_GPG_RECIPIENT", None)
-
 STORAGES_DBBACKUP_ALIAS = "dbbackup"
 DJANGO_STORAGES = getattr(settings, "STORAGES", {})
 storage: dict = DJANGO_STORAGES.get(STORAGES_DBBACKUP_ALIAS, {})
 STORAGE = storage.get("BACKEND", "django.core.files.storage.FileSystemStorage")
 STORAGE_OPTIONS = storage.get("OPTIONS", {})
-
 CONNECTORS = getattr(settings, "DBBACKUP_CONNECTORS", {})
 CUSTOM_CONNECTOR_MAPPING = getattr(settings, "DBBACKUP_CONNECTOR_MAPPING", {})
-
 DEFAULT_AUTO_FIELD = "django.db.models.AutoField"
-
-# Mail
 SEND_EMAIL = getattr(settings, "DBBACKUP_SEND_EMAIL", True)
 SERVER_EMAIL = getattr(settings, "DBBACKUP_SERVER_EMAIL", settings.SERVER_EMAIL)
 ADMINS = getattr(settings, "DBBACKUP_ADMIN", settings.ADMINS)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -75,6 +75,9 @@ extra:
     generator: false
     version:
         provider: mike
+    analytics:
+        provider: google
+        property: G-BFHSW4Q4YW
 
 extra_css:
     - assets/css/main.css
diff --git a/docs/src/configuration.md b/docs/src/configuration.md
@@ -79,6 +79,16 @@ Use a custom function if you need hierarchical prefixes (e.g. `year/month/`),
 or naming compatible with automatic life cycle / expiration rules of your
 object storage provider. `{datetime}` is rendered using `DBBACKUP_DATE_FORMAT`.
 
+Note on cleanup (--clean): the cleanup logic matches backup files to a
+database using the `{databasename}` value (the database alias/key from
+`settings.DATABASES` or `DBBACKUP_CONNECTORS`). If you rely on the
+`--clean` option to remove older database backups, ensure your
+`DBBACKUP_FILENAME_TEMPLATE` includes `{databasename}` so files can be
+correctly identified and filtered for deletion. When backing up a single
+database using the default `databasename` (often `default`) this may not be
+necessary, but it is required when you manage more than one database or use
+custom connector keys.
+
 ### DBBACKUP_MEDIA_FILENAME_TEMPLATE
 
 Same as `DBBACKUP_FILENAME_TEMPLATE`, but used for media backups.
@@ -113,9 +123,9 @@ python manage.py dbrestore --decrypt
 
 Requirements:
 
-- Install the python package python-gnupg: `pip install python-gnupg>=0.5.0`.
-- You need a GPG key. ([GPG manual](https://www.gnupg.org/gph/en/manual/c14.html))
-- Set the setting `DBBACKUP_GPG_RECIPIENT` to the name of the GPG key.
+-   Install the python package python-gnupg: `pip install python-gnupg>=0.5.0`.
+-   You need a GPG key. ([GPG manual](https://www.gnupg.org/gph/en/manual/c14.html))
+-   Set the setting `DBBACKUP_GPG_RECIPIENT` to the name of the GPG key.
 
 Note (Windows): The `gpg` executable must be installed and on your PATH for encryption/decryption. If it is absent, django-dbbackup still works; only encryption-related features are unavailable. The test suite will automatically skip encryption tests when `gpg` is not found.
 
diff --git a/docs/src/contributing.md b/docs/src/contributing.md
@@ -7,9 +7,9 @@ welcome. This guide explains how to develop, test, and propose changes.
 
 If you plan to make code changes to this repository, you will need to install the following dependencies first:
 
-- [Git](https://git-scm.com/downloads)
-- [Python 3.9+](https://www.python.org/downloads/)
-- [Hatch](https://hatch.pypa.io/latest/)
+-   [Git](https://git-scm.com/downloads)
+-   [Python 3.9+](https://www.python.org/downloads/)
+-   [Hatch](https://hatch.pypa.io/latest/)
 
 Once you finish installing these dependencies, you can clone this repository:
 
@@ -83,10 +83,10 @@ Track bugs, feature proposals, and questions via
 [GitHub Issues](https://github.com/Archmonger/django-dbbackup/issues). Open an
 issue if:
 
-- You have an improvement idea
-- You found a bug
-- You've got a question
-- More generally something seems wrong for you
+-   You have an improvement idea
+-   You found a bug
+-   You've got a question
+-   More generally something seems wrong for you
 
 ## Make a patch
 
diff --git a/docs/src/databases.md b/docs/src/databases.md
@@ -2,11 +2,11 @@
 
 The following databases are supported by this application:
 
-- SQLite
-- MySQL
-- PostgreSQL
-- MongoDB
-- ... and any other Django-supported database (via `DjangoConnector`)
+-   SQLite
+-   MySQL
+-   PostgreSQL
+-   MongoDB
+-   ... and any other Django-supported database (via `DjangoConnector`)
 
 By default DBBackup reuses connection details from `settings.DATABASES`.
 Sometimes you want different credentials or a different host (e.g. read-only
@@ -40,8 +40,6 @@ All connectors have the following parameters:
 | EXCLUDE   | List of table names to exclude from dump (may be unsupported for raw file copy snapshot approaches). Example below.                                                                                                                                                                                                                                                                                                                                                                | None                        |
 | EXTENSION | File extension used for the generated dump archive.                                                                                                                                                                                                                                                                                                                                                                                                                                | `dump`                      |
 
-All supported built-in connectors are described in more detail below. Following database wrappers from `django-prometheus` are supported: `django_prometheus.db.backends.postgresql` (-> `PgDumpBinaryConnector`), `django_prometheus.db.backends.sqlite3` (-> `SqliteBackupConnector`), `django_prometheus.db.backends.mysql` (-> `MysqlDumpConnector`), `django_prometheus.db.backends.postgis` (-> `PgDumpGisConnector`).
-
 Example for `EXCLUDE` usage:
 
 ```python
@@ -174,6 +172,15 @@ DATABASES = {
 | OBJECT_CHECK | Validate documents before inserting (`--objcheck`). | `True`  |
 | DROP         | Replace existing objects during restore (`--drop`). | `True`  |
 
+### Django-Prometheus
+
+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`
+
 ## Django Connector
 
 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.
@@ -190,24 +197,24 @@ 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
+-   **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
+-   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
 
-- **Performance**: Slower than native database tools for large datasets
-- **Database structure**: Only backs up data, not database schema, indices, or procedures
+-   **Performance**: Slower than native database tools for large datasets
+-   **Database structure**: Only backs up data, not database schema, indices, or procedures
 
 ### File Extension
 
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -3,13 +3,14 @@ hide:
     - navigation
 ---
 
-{% include-markdown "../../README.md" %}
+{% include-markdown "../../README.md"  start="<!--docs-top-start-->" end="<!--docs-top-end-->" %}
+{% include-markdown "../../README.md"  start="<!--docs-bottom-start-->" end="<!--docs-bottom-end-->" %}
 
 ## Other Resources
 
-* [GitHub repository](https://github.com/Archmonger/django-dbbackup)
-* [PyPI project](https://pypi.org/pypi/django-dbbackup/)
-* [Documentation](https://archmonger.github.io/django-dbbackup/)
-* [GitHub issues](https://github.com/Archmonger/django-dbbackup/issues)
-* [GitHub discussions](https://github.com/Archmonger/django-dbbackup/discussions)
-* [GitHub pull requests](https://github.com/Archmonger/django-dbbackup/pulls)
+-   [GitHub repository](https://github.com/Archmonger/django-dbbackup)
+-   [PyPI project](https://pypi.org/pypi/django-dbbackup/)
+-   [Documentation](https://archmonger.github.io/django-dbbackup/)
+-   [GitHub issues](https://github.com/Archmonger/django-dbbackup/issues)
+-   [GitHub discussions](https://github.com/Archmonger/django-dbbackup/discussions)
+-   [GitHub pull requests](https://github.com/Archmonger/django-dbbackup/pulls)
diff --git a/docs/src/installation.md b/docs/src/installation.md
@@ -1,6 +1,6 @@
 ---
 hide:
-  - navigation
+    - navigation
 ---
 
 ## Installing on your system
diff --git a/docs/src/integration.md b/docs/src/integration.md
@@ -1,8 +1,9 @@
 # Integration tutorials
 
 !!! note
-If you have a custom and/or interesting way of using DBBackup, do not
-hesitate to make a pull request.
+
+    If you have a custom and/or interesting way of using DBBackup, do not
+    hesitate to make a pull request.
 
 ## Django-Cron
 
diff --git a/tests/test_settings.py b/tests/test_settings.py
@@ -16,3 +16,35 @@ def test_admins_setting(self):
 
         # Check that ADMINS is set to DBBACKUP_ADMIN
         assert ["admin@example.com"] == dbbackup.settings.ADMINS
+
+    def test_deprecated_dbbackup_storage_raises(self):
+        """Importing dbbackup.settings raises if DBBACKUP_STORAGE is set."""
+        import importlib
+        import sys
+
+        # Ensure we import a fresh module so the check executes
+        original_settings = sys.modules["dbbackup.settings"]
+        del sys.modules["dbbackup.settings"]
+
+        try:
+            with self.assertRaises(RuntimeError):
+                with override_settings(DBBACKUP_STORAGE="some.storage.Backend"):
+                    importlib.import_module("dbbackup.settings")
+        finally:
+            sys.modules["dbbackup.settings"] = original_settings
+
+    def test_deprecated_dbbackup_storage_options_raises(self):
+        """Importing dbbackup.settings raises if DBBACKUP_STORAGE_OPTIONS is set."""
+        import importlib
+        import sys
+
+        # Ensure we import a fresh module so the check executes
+        original_settings = sys.modules["dbbackup.settings"]
+        del sys.modules["dbbackup.settings"]
+
+        try:
+            with self.assertRaises(RuntimeError):
+                with override_settings(DBBACKUP_STORAGE_OPTIONS={"option": True}):
+                    importlib.import_module("dbbackup.settings")
+        finally:
+            sys.modules["dbbackup.settings"] = original_settings

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`"""Management commands to help backup and restore a project database and media"""`
`2`	`2`
`3`		`-__version__ = "5.0.0"`
	`3`	`+__version__ = "5.0.1"`