Add Django Signals support for backup and restore operations (#614)

This PR implements Django Signals support for the django-dbbackup package, allowing users to hook into backup and restore operations for both database and media files. The implementation adds 8 new signals that are sent before and after each operation type.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Archmonger <[email protected]>

Author: Copilot

CHANGELOG.md

@@ -18,6 +18,7 @@ Don't forget to remove deprecated code on each major release!
 
 - Implement new `SqliteBackupConnector` to backup SQLite3 databases using the `.backup` command (safe to execute on databases with active connections).
 - Verified full Windows compatibility via new CI workflows.
+- Add Django Signals support for backup and restore operations. New signals include `pre_backup`, `post_backup`, `pre_restore`, `post_restore`, `pre_media_backup`, `post_media_backup`, `pre_media_restore`, and `post_media_restore`.
 
 ### Changed
 

dbbackup/management/commands/dbbackup.py

@@ -6,6 +6,7 @@
 
 from ... import settings, utils
 from ...db.base import get_connector
+from ...signals import pre_backup, post_backup
 from ...storage import StorageError, get_storage
 from ._base import BaseDbBackupCommand, make_option
 
@@ -115,6 +116,15 @@ def _save_new_backup(self, database):
         Save a new backup file.
         """
         self.logger.info("Backing Up Database: %s", database["NAME"])
+
+        # Send pre_backup signal
+        pre_backup.send(
+            sender=self.__class__,
+            database=database,
+            connector=self.connector,
+            servername=self.servername,
+        )
+
         # Get backup, schema and name
         filename = self.connector.generate_filename(self.servername)
 
@@ -146,3 +156,13 @@ def _save_new_backup(self, database):
             self.write_to_storage(outputfile, self.path)
         else:
             self.write_local_file(outputfile, self.path)
+
+        # Send post_backup signal
+        post_backup.send(
+            sender=self.__class__,
+            database=database,
+            connector=self.connector,
+            servername=self.servername,
+            filename=filename,
+            storage=self.storage,
+        )

dbbackup/management/commands/dbrestore.py

@@ -3,12 +3,14 @@
 """
 
 import io
+
 from django.conf import settings
 from django.core.management.base import CommandError
 from django.db import connection
 
 from ... import utils
 from ...db.base import get_connector
+from ...signals import post_restore, pre_restore
 from ...storage import StorageError, get_storage
 from ._base import BaseDbBackupCommand, make_option
 
@@ -18,6 +20,9 @@ class Command(BaseDbBackupCommand):
     content_type = "db"
     no_drop = False
     pg_options = ""
+    input_database_name = None
+    database_name = None
+    database = None
 
     option_list = BaseDbBackupCommand.option_list + (
         make_option("-d", "--database", help="Database to restore"),
@@ -118,6 +123,16 @@ def _restore_backup(self):
 
         self.logger.info(f"Restoring: {input_filename}")
 
+        # Send pre_restore signal
+        pre_restore.send(
+            sender=self.__class__,
+            database=self.database,
+            database_name=self.database_name,
+            filename=input_filename,
+            servername=self.servername,
+            storage=self.storage,
+        )
+
         if self.decrypt:
             unencrypted_file, input_filename = utils.unencrypt_file(input_file, input_filename, self.passphrase)
             input_file.close()
@@ -153,3 +168,14 @@ def _restore_backup(self):
         self.connector.drop = not self.no_drop
         self.connector.pg_options = self.pg_options
         self.connector.restore_dump(input_file)
+
+        # Send post_restore signal
+        post_restore.send(
+            sender=self.__class__,
+            database=self.database,
+            database_name=self.database_name,
+            filename=input_filename,
+            servername=self.servername,
+            connector=self.connector,
+            storage=self.storage,
+        )

dbbackup/management/commands/mediabackup.py

@@ -8,6 +8,7 @@
 from django.core.management.base import CommandError
 
 from ... import utils
+from ...signals import pre_media_backup, post_media_backup
 from ...storage import StorageError, get_storage, get_storage_class
 from ._base import BaseDbBackupCommand, make_option
 
@@ -104,6 +105,13 @@ def backup_mediafiles(self):
         """
         Create backup file and write it to storage.
         """
+        # Send pre_media_backup signal
+        pre_media_backup.send(
+            sender=self.__class__,
+            servername=self.servername,
+            storage=self.storage,
+        )
+
         # Check for filename option
         if self.filename:
             filename = self.filename
@@ -127,3 +135,11 @@ def backup_mediafiles(self):
             self.write_to_storage(tarball, self.path)
         else:
             self.write_local_file(tarball, self.path)
+
+        # Send post_media_backup signal
+        post_media_backup.send(
+            sender=self.__class__,
+            filename=filename,
+            servername=self.servername,
+            storage=self.storage,
+        )

dbbackup/management/commands/mediarestore.py

@@ -5,6 +5,7 @@
 import tarfile
 
 from ... import utils
+from ...signals import pre_media_restore, post_media_restore
 from ...storage import get_storage, get_storage_class
 from ._base import BaseDbBackupCommand, make_option
 
@@ -79,6 +80,14 @@ def _restore_backup(self):
         input_filename, input_file = self._get_backup_file(servername=self.servername)
         self.logger.info("Restoring: %s", input_filename)
 
+        # Send pre_media_restore signal
+        pre_media_restore.send(
+            sender=self.__class__,
+            filename=input_filename,
+            servername=self.servername,
+            storage=self.storage,
+        )
+
         if self.decrypt:
             unencrypted_file, input_filename = utils.unencrypt_file(input_file, input_filename, self.passphrase)
             input_file.close()
@@ -103,3 +112,11 @@ def _restore_backup(self):
                 continue  # Skip directories
             name = media_file_info.path
             self._upload_file(name, media_file)
+
+        # Send post_media_restore signal
+        post_media_restore.send(
+            sender=self.__class__,
+            filename=input_filename,
+            servername=self.servername,
+            storage=self.storage,
+        )

dbbackup/signals.py

@@ -0,0 +1,24 @@
+"""
+Django signals for dbbackup operations.
+
+These signals allow users to hook into the backup and restore process
+to perform custom actions before and after backup/restore operations.
+"""
+
+import django.dispatch
+
+# Database backup signals
+pre_backup = django.dispatch.Signal()
+post_backup = django.dispatch.Signal()
+
+# Database restore signals
+pre_restore = django.dispatch.Signal()
+post_restore = django.dispatch.Signal()
+
+# Media backup signals
+pre_media_backup = django.dispatch.Signal()
+post_media_backup = django.dispatch.Signal()
+
+# Media restore signals
+pre_media_restore = django.dispatch.Signal()
+post_media_restore = django.dispatch.Signal()

docs/mkdocs.yml

@@ -6,6 +6,7 @@ nav:
     - Databases: databases.md
     - Storage: storage.md
     - Commands: commands.md
+    - Signals: signals.md
     - Integration: integration.md
   - About:
     - Changelog: changelog.md

docs/src/dictionary.txt

@@ -40,3 +40,5 @@ dumpable
 schemas
 redistributions
 whitespace
+pre
+post