Add push/pull methods to ImpulseDB for S3 sync

  ImpulseDB now accepts an optional s3_manager parameter, enabling
  push() to back up the local database to S3 with a timestamp, and
  pull() to restore the latest backup from S3. S3Manager gains a
  restore_database() method (the counterpart to the existing
  backup_database()), and S3Backend exposes the same as a convenience
  wrapper.

Author: darmendariz

impulse/collection/database.py

@@ -7,15 +7,19 @@
 import sqlite3
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import TYPE_CHECKING, Dict, List, Optional
 from contextlib import contextmanager
 
+if TYPE_CHECKING:
+    from impulse.collection.s3_manager import S3Manager
+
 
 class ImpulseDB:
     """Manages SQLite database for replay tracking (raw and parsed)."""
 
-    def __init__(self, db_path: str = "./impulse.db"):
+    def __init__(self, db_path: str = "./impulse.db", s3_manager: "Optional[S3Manager]" = None):
         self.db_path = Path(db_path)
+        self.s3_manager = s3_manager
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
         self.init_database()
         print(f"Database initialized: {self.db_path}")
@@ -613,3 +617,42 @@ def get_full_stats(self) -> Dict:
             'raw': self.get_stats(),
             'parsed': self.get_parse_stats()
         }
+
+    # =========================================================================
+    # S3 Sync
+    # =========================================================================
+
+    def push(self, s3_prefix: str = "database-backups") -> Dict:
+        """
+        Back up the local database to S3.
+
+        Creates a timestamped copy under s3_prefix so previous backups are
+        preserved. Requires s3_manager to be set on this instance.
+
+        Args:
+            s3_prefix: S3 prefix for backups (default: "database-backups")
+
+        Returns:
+            Dict with backup info (s3_key, size_bytes, success, ...)
+        """
+        if self.s3_manager is None:
+            raise RuntimeError("push() requires an s3_manager. Pass one to ImpulseDB().")
+        return self.s3_manager.backup_database(str(self.db_path), s3_prefix)
+
+    def pull(self, s3_prefix: str = "database-backups") -> bool:
+        """
+        Replace the local database with the latest backup from S3.
+
+        Downloads the most recent timestamped backup and overwrites the local
+        file at self.db_path. Subsequent queries will use the restored data
+        automatically. Requires s3_manager to be set on this instance.
+
+        Args:
+            s3_prefix: S3 prefix where backups are stored (default: "database-backups")
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if self.s3_manager is None:
+            raise RuntimeError("pull() requires an s3_manager. Pass one to ImpulseDB().")
+        return self.s3_manager.restore_database(str(self.db_path), s3_prefix)

impulse/collection/s3_manager.py

@@ -301,6 +301,33 @@ def backup_database(self, db_path: str, s3_prefix: str = "database-backups") ->
 
         return result
 
+    def restore_database(self, local_path: str, s3_prefix: str = "database-backups") -> bool:
+        """
+        Restore the latest database backup from S3.
+
+        Backups are stored with timestamps in their key names, so lexicographic
+        sort gives chronological order and the last entry is the most recent.
+
+        Args:
+            local_path: Where to write the restored database file
+            s3_prefix: S3 prefix where backups are stored
+
+        Returns:
+            True if successful, False otherwise
+        """
+        keys = self.list_objects(prefix=s3_prefix)
+        if not keys:
+            print(f"✗ No database backups found at s3://{self.s3_bucket_name}/{s3_prefix}/")
+            return False
+
+        latest_key = sorted(keys)[-1]
+        success = self.download_file(latest_key, local_path)
+        if success:
+            print(f"✓ Database restored from s3://{self.s3_bucket_name}/{latest_key}")
+        else:
+            print(f"✗ Database restore failed")
+        return success
+
     def get_storage_stats(self, prefix: str = "") -> Dict:
         """
         Get storage statistics for objects with given prefix.

impulse/collection/storage.py

@@ -302,3 +302,16 @@ def backup_database(self, db_path: str, backup_prefix: str = "database-backups")
             Dict with backup info
         """
         return self.s3_manager.backup_database(db_path, backup_prefix)
+
+    def restore_database(self, local_path: str, backup_prefix: str = "database-backups") -> bool:
+        """
+        Convenience method to restore the latest database backup from S3.
+
+        Args:
+            local_path: Where to write the restored database file
+            backup_prefix: S3 prefix where backups are stored
+
+        Returns:
+            True if successful, False otherwise
+        """
+        return self.s3_manager.restore_database(local_path, backup_prefix)