dbagent-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dbagent-cli
-Version: 0.3.0
-Summary: Enterprise AI Database Copilot & Autonomous Data Agent (CLI)
+Version: 0.3.1
+Summary: Enterprise AI Database Copilot with Long-Term Change Recovery (CLI)
 Author: Santhosh Gupta
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/dbagent/__init__.py

@@ -2,5 +2,5 @@
 DB-Agent: Universal Database Introspection and Script Generation AI Agent (CLI).
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 __author__ = "Santhosh Gupta"

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/dbagent/agent/pipeline.py

@@ -25,6 +25,7 @@ from dbagent.sql.validator import SQLValidator
 from dbagent.execution.cost import QueryCostEstimator, QueryComplexity
 from dbagent.execution.cache import QueryResultCache
 from dbagent.semantic.dictionary import BusinessDictionary
+from dbagent.execution.recovery import RecoveryManager, RowSnapshotRecoveryStrategy, RecoveryStatus
 from dbagent.agent.confidence import ConfidenceEvaluator, ConfidenceScore
 from dbagent.agent.conversation import ConversationContext
 from dbagent.agent.error_classifier import ErrorClassifier
@@ -45,6 +46,11 @@ class PipelineResult:
     needs_confirmation: bool = False
     is_cached: bool = False
     cache_age_seconds: float = 0.0
+    # Long-term Change Recovery
+    change_id: Optional[str] = None
+    recovery_status: Optional[str] = None
+    recovery_message: Optional[str] = None
+    expires_at: Optional[str] = None
     # Conversational chat response
     is_chat: bool = False
     message: str = ""
@@ -100,6 +106,7 @@ class QueryPipeline:
         confirm_callback: Optional[Callable[[str, List[str]], bool]] = None,
         choice_callback: Optional[Callable[[str, List[str]], Optional[str]]] = None,
         conversation_context: Optional[ConversationContext] = None,
+        recovery_manager: Optional[RecoveryManager] = None,
     ):
         self.connector = connector
         self.generator = ScriptGenerator(llm)
@@ -115,6 +122,7 @@ class QueryPipeline:
         self.dictionary = BusinessDictionary()
         self.result_cache = QueryResultCache()
         self.audit_logger = AuditLogger()
+        self.recovery_mgr = recovery_manager or RecoveryManager()
         self.conversation = conversation_context or ConversationContext()
 
         # Database identifier
@@ -272,10 +280,44 @@ class QueryPipeline:
         elif self.mode == OperationMode.ADMIN:
             should_execute = True
 
-        # --- 11. Execute with Error Retry ---
+        # --- 11. Pre-Write Recovery Snapshot Capture & Execution ---
+        snapshot_data = None
+        target_table_name = exact[0] if exact else (sub_schema.tables[0].name if sub_schema.tables else "unknown")
+        table_model = sub_schema.get_table(target_table_name) if sub_schema else None
+
+        if should_execute and result.query_type in ("write", "ddl") and table_model:
+            can_snap, snap, snap_err = RowSnapshotRecoveryStrategy.capture_pre_write_snapshot(
+                connector=self.connector,
+                table_model=table_model,
+                sql=result.sql,
+                operation=result.query_type.upper(),
+            )
+            if can_snap and snap:
+                snapshot_data = snap
+
         if should_execute:
             self._execute_with_retry(result, augmented_prompt, sub_schema)
 
+        # --- Record ChangeSet / Recovery Record for successful write operations ---
+        if result.success and result.query_type in ("write", "ddl"):
+            affected = len(snapshot_data.get("rows", [])) if snapshot_data else 1
+            meta = self.recovery_mgr.create_change_record(
+                database=self.db_name,
+                sql=result.sql,
+                table_name=target_table_name,
+                operation=result.query_type.upper(),
+                affected_rows=affected,
+                snapshot_data=snapshot_data,
+                user=self.user_id,
+            )
+            result.change_id = meta["change_id"]
+            result.recovery_status = meta["recovery_status"]
+            result.expires_at = meta["expires_at"]
+            if meta["recovery_status"] == RecoveryStatus.AVAILABLE.value:
+                result.recovery_message = f"Available until {meta['expires_at']} ({self.recovery_mgr.retention_days} days retention)"
+            else:
+                result.recovery_message = "Not available (unsupported operation or missing primary key)"
+
         # --- 12. Sensitive Data Masking ---
         if result.success and self.mask_sensitive_data and result.rows:
             result.rows = SensitiveDataMasker.mask_row_set(result.columns, result.rows)

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/dbagent/cli.py

@@ -36,6 +36,14 @@ from dbagent.security.modes import OperationMode
 from dbagent.security.audit import AuditLogger
 from dbagent.security.masking import SensitiveDataMasker
 from dbagent.execution.changeset import ChangeSetManager
+from dbagent.execution.recovery import (
+    RecoveryManager,
+    RowSnapshotRecoveryStrategy,
+    RecoveryStatus,
+    ConflictPolicy,
+    RollbackPreview,
+    RollbackResult,
+)
 from dbagent.semantic.dictionary import BusinessDictionary
 from dbagent.semantic.templates import TemplateManager
 from dbagent.ui.visualizer import ResultVisualizer
@@ -59,6 +67,7 @@ app = typer.Typer(
 
 config_mgr = ConfigManager()
 cache_mgr = SchemaCacheManager()
+recovery_mgr = RecoveryManager()
 change_mgr = ChangeSetManager()
 dict_mgr = BusinessDictionary()
 template_mgr = TemplateManager()
@@ -169,6 +178,16 @@ def _display_pipeline_result(result: PipelineResult, show_sql: bool = True) -> N
 
         if result.retries > 0:
             console.print(f"[dim](Auto-corrected after {result.retries} retry(ies))[/dim]")
+
+        # Display recovery info for write changes
+        if result.change_id:
+            console.print(f"\n[bold green]✓ Change committed successfully[/bold green]")
+            console.print(f"  * Change ID: [bold white]{result.change_id}[/bold white]")
+            if result.recovery_status == "AVAILABLE":
+                console.print(f"  * Recovery: [bold cyan]{result.recovery_message}[/bold cyan]")
+                console.print(f"  * Rollback command: [bold]db-agent rollback {result.change_id}[/bold]\n")
+            else:
+                console.print(f"  * Recovery: [yellow]{result.recovery_message or result.recovery_status}[/yellow]\n")
     elif result.needs_confirmation and not result.was_executed:
         if result.sql:
             print_code(result.sql, "sql", f"Generated {result.query_type.upper()} Query")
@@ -931,22 +950,34 @@ def schema_status_command(
 def changes_command(
     limit: int = typer.Option(20, "--limit", "-l", help="Number of change sets to show"),
 ):
-    """List recorded write change sets."""
+    """List recorded write change sets and recovery availability."""
     print_banner()
-    sets = change_mgr.list_change_sets(limit=limit)
-    if not sets:
+    records = recovery_mgr.list_changes(limit=limit)
+    if not records:
         print_info("No recorded write change sets found.")
         return
 
-    table = Table(title="[bold cyan]Recorded Write ChangeSets[/bold cyan]", show_header=True, header_style="bold cyan")
-    table.add_column("ChangeSet ID", style="bold white")
+    table = Table(title="[bold cyan]Recorded Write ChangeSets & Recovery Status[/bold cyan]", show_header=True, header_style="bold cyan")
+    table.add_column("Change ID", style="bold white")
     table.add_column("Timestamp", style="dim")
     table.add_column("Operation", style="yellow")
     table.add_column("Table", style="cyan")
-    table.add_column("Affected Rows", justify="right")
+    table.add_column("Rows", justify="right")
+    table.add_column("Recovery Status", style="bold")
+    table.add_column("Expires", style="dim")
 
-    for s in sets:
-        table.add_row(s.change_set_id, s.timestamp, s.operation, s.table_name, str(s.affected_rows))
+    for s in records:
+        st = s.get("recovery_status", "AVAILABLE")
+        st_style = "[green]AVAILABLE[/green]" if st == "AVAILABLE" else ("[yellow]EXPIRED[/yellow]" if st == "EXPIRED" else f"[dim]{st}[/dim]")
+        table.add_row(
+            s.get("change_id", ""),
+            s.get("executed_at", ""),
+            s.get("operation", ""),
+            s.get("table_name", ""),
+            str(s.get("affected_rows", 0)),
+            st_style,
+            s.get("expires_at", "-"),
+        )
 
     console.print(table)
 
@@ -955,64 +986,165 @@ def changes_command(
 
 @app.command(name="changes-show")
 def changes_show_command(
-    change_set_id: str = typer.Argument(..., help="ChangeSet ID (e.g. CS-20260828-001)"),
+    change_id: str = typer.Argument(..., help="Change ID (e.g. CHG-20260828-001)"),
 ):
     """Show details and before-snapshot of a recorded ChangeSet."""
     print_banner()
-    cs = change_mgr.get_change_set(change_set_id)
-    if not cs:
-        print_error(f"ChangeSet '{change_set_id}' not found.")
+    meta = recovery_mgr.get_change_record(change_id)
+    if not meta:
+        print_error(f"Change record '{change_id}' not found.")
         raise typer.Exit(1)
 
-    console.print(f"\n[bold cyan]ChangeSet: {cs.change_set_id}[/bold cyan]")
-    console.print(f"  * Database: {cs.database} | Timestamp: {cs.timestamp}")
-    console.print(f"  * Operation: [{cs.operation}] on Table `{cs.table_name}` ({cs.affected_rows} rows)")
-    print_code(cs.sql, "sql", "Executed Statement")
+    console.print(f"\n[bold cyan]Change Record: {meta['change_id']}[/bold cyan]")
+    console.print(f"  * Database: {meta.get('database')} | Executed: {meta.get('executed_at')}")
+    console.print(f"  * Operation: [{meta.get('operation')}] on Table `{meta.get('table_name')}` ({meta.get('affected_rows')} rows)")
+    console.print(f"  * Recovery Status: [bold green]{meta.get('recovery_status')}[/bold green] (Expires: {meta.get('expires_at')})")
+    if meta.get("rollback_of"):
+        console.print(f"  * Rollback Of: [bold yellow]{meta['rollback_of']}[/bold yellow]")
+    print_code(meta.get("sql", ""), "sql", "Executed Statement")
 
-    if cs.before_snapshot:
-        console.print(f"\n[bold yellow]Before-Snapshot ({len(cs.before_snapshot)} rows captured for recovery):[/bold yellow]")
-        cols = list(cs.before_snapshot[0].keys())
-        print_results_table(cols, cs.before_snapshot, title="Before Snapshot")
+    snap = recovery_mgr.get_snapshot(change_id)
+    if snap and "rows" in snap and snap["rows"]:
+        rows_disp = [r.get("before", {}) for r in snap["rows"][:20]]
+        if rows_disp and rows_disp[0]:
+            console.print(f"\n[bold yellow]Captured Before-Snapshot ({len(snap['rows'])} rows captured):[/bold yellow]")
+            cols = list(rows_disp[0].keys())
+            print_results_table(cols, rows_disp, title="Snapshot Sample (First 20)")
 
 
 # ---- rollback ----
 
 @app.command(name="rollback")
 def rollback_command(
-    change_set_id: str = typer.Argument(..., help="ChangeSet ID to roll back"),
+    change_id: Optional[str] = typer.Argument(None, help="Change ID to roll back (e.g. CHG-20260828-001) or use --last"),
     db: Optional[str] = typer.Option(None, "--db", "-d", help="Database connection URL or profile name"),
-    force: bool = typer.Option(False, "--force", "-f", help="Bypass confirmation"),
+    preview: bool = typer.Option(False, "--preview", "-p", help="Preview rollback and detect conflicts without executing"),
+    force: bool = typer.Option(False, "--force", "-f", help="Bypass confirmation and overwrite conflicts"),
+    policy: str = typer.Option("skip", "--conflict-policy", help="Conflict resolution policy: skip, abort, force"),
+    last: bool = typer.Option(False, "--last", "-l", help="Roll back the most recent committed change"),
+    mode: str = typer.Option("CONFIRM", "--mode", help="Operation mode (SAFE, READ_ONLY, CONFIRM, ADMIN)"),
 ):
-    """Generate and execute recovery rollback SQL for a ChangeSet."""
+    """Safely revert and recover committed database modifications with conflict protection."""
     print_banner()
-    cs = change_mgr.get_change_set(change_set_id)
-    if not cs:
-        print_error(f"ChangeSet '{change_set_id}' not found.")
+
+    target_id = change_id
+    if last or target_id == "--last":
+        records = recovery_mgr.list_changes(limit=1)
+        if not records:
+            print_error("No recorded change sets available to roll back.")
+            raise typer.Exit(1)
+        target_id = records[0]["change_id"]
+
+    if not target_id:
+        records = recovery_mgr.list_changes(limit=10)
+        if not records:
+            print_info("No recorded change sets found.")
+            raise typer.Exit(0)
+        console.print("[bold cyan]Recent Change Sets:[/bold cyan]")
+        for r in records:
+            console.print(f"  * [bold white]{r['change_id']}[/bold white] ({r.get('executed_at')}) -> [{r.get('operation')}] on {r.get('table_name')} ({r.get('affected_rows')} rows)")
+        target_id = Prompt.ask("\nEnter Change ID to roll back")
+
+    meta = recovery_mgr.get_change_record(target_id)
+    if not meta:
+        print_error(f"Change record '{target_id}' not found.")
+        raise typer.Exit(1)
+
+    if meta.get("recovery_status") == RecoveryStatus.EXPIRED.value:
+        print_error(f"Rollback rejected: Recovery snapshot for {target_id} has EXPIRED ({meta.get('expires_at')}).")
+        raise typer.Exit(1)
+
+    if meta.get("recovery_status") == RecoveryStatus.UNAVAILABLE.value:
+        print_error(f"Rollback unavailable: Operation was executed without long-term recovery snapshot.")
+        raise typer.Exit(1)
+
+    snap = recovery_mgr.get_snapshot(target_id)
+    if not snap:
+        print_error(f"Recovery snapshot corrupted or missing checksum verification for '{target_id}'.")
+        raise typer.Exit(1)
+
+    db_url = resolve_db_url(db or meta.get("database"))
+    connector = create_connector(db_url)
+
+    # Concurrency & Conflict Preview
+    with console.status("[bold cyan]Evaluating row eligibility & detecting conflicts...[/bold cyan]"):
+        prev = RowSnapshotRecoveryStrategy.preview_recovery(connector, meta, snap)
+
+    console.print(f"\n{prev.format_summary()}\n")
+
+    if not prev.can_proceed:
+        connector.close()
         raise typer.Exit(1)
 
-    stmts = change_mgr.generate_rollback_sql(cs)
-    if not stmts:
-        print_warning(f"No recovery snapshot available to roll back ChangeSet '{change_set_id}'.")
+    # If preview only, stop here
+    if preview:
+        console.print("[dim]Preview complete. Use 'db-agent rollback " + target_id + "' to execute recovery.[/dim]\n")
+        connector.close()
         return
 
-    full_sql = "\n".join(stmts)
-    console.print(f"\n[bold cyan]Generated Rollback SQL for {change_set_id}:[/bold cyan]")
-    print_code(full_sql, "sql", "Rollback Operations")
+    # Check Safe Mode
+    if mode.upper() in ("SAFE", "READ_ONLY"):
+        print_error(f"Rollback execution blocked in {mode.upper()} mode. Rollback requires write permission. Run with --preview to inspect.")
+        connector.close()
+        raise typer.Exit(1)
+
+    # Conflict Policy enforcement
+    pol_enum = ConflictPolicy(policy.upper()) if policy.upper() in ConflictPolicy.__members__ else ConflictPolicy.SKIP
+    if force:
+        pol_enum = ConflictPolicy.FORCE
+
+    if prev.conflicts_detected > 0 and pol_enum == ConflictPolicy.ABORT:
+        print_error(f"Rollback aborted: {prev.conflicts_detected} concurrency conflict(s) detected with policy=ABORT.")
+        connector.close()
+        raise typer.Exit(1)
 
-    if not force and not Confirm.ask("Execute these rollback statements on the database?"):
+    if not force and not Confirm.ask(f"Execute rollback for {target_id} ({prev.rows_eligible} rows eligible)?", default=False):
         console.print("[dim]Rollback cancelled.[/dim]")
+        connector.close()
         return
 
-    db_url = resolve_db_url(db or cs.database)
-    with console.status("[bold cyan]Executing rollback...[/bold cyan]"):
-        try:
-            connector = create_connector(db_url)
-            for stmt in stmts:
-                connector.execute_query(stmt)
-            connector.close()
-            print_success(f"Rollback completed successfully for {change_set_id}!")
-        except Exception as e:
-            print_error(f"Rollback execution failed: {str(e)}")
+    with console.status("[bold cyan]Executing rollback recovery...[/bold cyan]"):
+        res = RowSnapshotRecoveryStrategy.execute_recovery(connector, meta, snap, policy=pol_enum)
+        connector.close()
+
+    # Record rollback audit chain
+    recovery_mgr.create_change_record(
+        database=meta.get("database", "database"),
+        sql=f"-- Rollback of {target_id}",
+        table_name=meta.get("table_name", "unknown"),
+        operation="ROLLBACK",
+        affected_rows=res.restored_count,
+        snapshot_data=None,
+        rollback_of=target_id,
+    )
+
+    console.print(f"\n{res.format_summary()}\n")
+
+
+# ---- recovery ----
+
+@app.command(name="recovery")
+def recovery_command(
+    action: str = typer.Argument("list", help="Action: list, cleanup, status"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Number of records to list"),
+):
+    """Manage database recovery snapshots, retention, and storage."""
+    print_banner()
+    if action == "list":
+        changes_command(limit=limit)
+    elif action == "cleanup":
+        with console.status("[bold cyan]Cleaning up expired recovery snapshots...[/bold cyan]"):
+            cleaned = recovery_mgr.cleanup_expired()
+        print_success(f"Recovery cleanup complete. Removed {cleaned} expired snapshot file(s).")
+    elif action == "status":
+        st = recovery_mgr.get_storage_status()
+        console.print(f"\n[bold cyan]Recovery Storage & Retention Status:[/bold cyan]")
+        console.print(f"  * Total Change Records: [bold white]{st['total_change_records']}[/bold white]")
+        console.print(f"  * Storage Used: [bold green]{st['storage_used_mb']} MB[/bold green] ({st['storage_used_bytes']:,} bytes)")
+        console.print(f"  * Retention Period: [bold]{st['retention_days']} days[/bold]")
+        console.print(f"  * Storage Directory: [dim]{st['directory']}[/dim]\n")
+    else:
+        print_error(f"Unknown recovery action '{action}'. Supported: list, cleanup, status")
 
 
 # ---- define ----

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/dbagent/connectors/base.py

@@ -69,7 +69,18 @@ class BaseConnector(ABC):
         """
         pass
 
+    def get_recovery_capabilities(self) -> Dict[str, bool]:
+        """Returns map of supported recovery strategies."""
+        return {
+            "transaction_rollback": True,
+            "row_snapshot": True,
+            "database_snapshot": False,
+            "point_in_time_recovery": False,
+            "long_term_recovery": True,
+        }
+
     @abstractmethod
     def close(self) -> None:
         """Close any open connections."""
         pass
+

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/dbagent/connectors/relational.py

@@ -473,6 +473,17 @@ class RelationalConnector(BaseConnector):
         except Exception as e:
             return [], [], str(e)
 
+    def get_recovery_capabilities(self) -> Dict[str, bool]:
+        is_sqlite = self.engine.dialect.name.lower() == "sqlite"
+        return {
+            "transaction_rollback": True,
+            "row_snapshot": True,
+            "database_snapshot": is_sqlite,
+            "point_in_time_recovery": False,
+            "long_term_recovery": True,
+        }
+
     def close(self) -> None:
         if self._engine:
             self._engine.dispose()
+

{dbagent_cli-0.3.0 → dbagent_cli-0.3.1}/dbagent/execution/changeset.py

@@ -1,15 +1,25 @@
 """
 Change Set & Recovery Tracker.
-Captures snapshots of rows modified/deleted by write operations and stores them in ~/.dbagent/changesets/
-Enables auditable inspection (db-agent changes show <id>) and recovery rollback (db-agent rollback <id>).
+Stores persistent Change Records with rollback snapshots, metadata, and checksums in ~/.dbagent/recovery/
+Provides backward-compatible ChangeSetManager and links to RecoveryManager.
 """
 
 import json
 import time
 import uuid
+import hashlib
 from pathlib import Path
 from typing import Dict, Any, List, Optional, Tuple
 
+from dbagent.execution.recovery import (
+    RecoveryManager,
+    RecoveryStatus,
+    ConflictPolicy,
+    RollbackPreview,
+    RollbackResult,
+    RowSnapshotRecoveryStrategy,
+)
+
 
 class ChangeSet:
     """Represents a recorded set of database modifications with recovery data."""
@@ -19,11 +29,13 @@ class ChangeSet:
         database: str,
         sql: str,
         table_name: str,
-        operation: str,  # UPDATE, DELETE, INSERT
+        operation: str,
         timestamp: str,
         affected_rows: int,
         before_snapshot: List[Dict[str, Any]],
-        status: str = "COMMITTED",
+        status: str = "AVAILABLE",
+        rollback_of: Optional[str] = None,
+        expires_at: Optional[str] = None,
     ):
         self.change_set_id = change_set_id
         self.database = database
@@ -34,6 +46,8 @@ class ChangeSet:
         self.affected_rows = affected_rows
         self.before_snapshot = before_snapshot
         self.status = status
+        self.rollback_of = rollback_of
+        self.expires_at = expires_at
 
     def to_dict(self) -> Dict[str, Any]:
         return {
@@ -46,31 +60,38 @@ class ChangeSet:
             "affected_rows": self.affected_rows,
             "before_snapshot": self.before_snapshot,
             "status": self.status,
+            "rollback_of": self.rollback_of,
+            "expires_at": self.expires_at,
         }
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "ChangeSet":
+        cid = data.get("change_id") or data.get("change_set_id")
+        ts = data.get("executed_at") or data.get("timestamp") or ""
+        st = data.get("recovery_status") or data.get("status") or "AVAILABLE"
         return cls(
-            change_set_id=data["change_set_id"],
-            database=data["database"],
-            sql=data["sql"],
-            table_name=data["table_name"],
-            operation=data["operation"],
-            timestamp=data["timestamp"],
+            change_set_id=cid,
+            database=data.get("database", "database"),
+            sql=data.get("sql", ""),
+            table_name=data.get("table_name", "unknown"),
+            operation=data.get("operation", "UPDATE"),
+            timestamp=ts,
             affected_rows=data.get("affected_rows", 0),
             before_snapshot=data.get("before_snapshot", []),
-            status=data.get("status", "COMMITTED"),
+            status=st,
+            rollback_of=data.get("rollback_of"),
+            expires_at=data.get("expires_at"),
         )
 
 
 class ChangeSetManager:
     """
-    Manages persistent ChangeSet history on disk in ~/.dbagent/changesets/.
+    Manages persistent ChangeSet history on disk in ~/.dbagent/recovery/.
     """
 
-    def __init__(self, storage_dir: Optional[Path] = None):
-        self.storage_dir = storage_dir or Path.home() / ".dbagent" / "changesets"
-        self.storage_dir.mkdir(parents=True, exist_ok=True)
+    def __init__(self, storage_dir: Optional[Path] = None, retention_days: int = 30):
+        self.recovery_mgr = RecoveryManager(storage_dir=storage_dir, retention_days=retention_days)
+        self.storage_dir = self.recovery_mgr.storage_dir
 
     def create_change_set(
         self,
@@ -80,58 +101,65 @@ class ChangeSetManager:
         operation: str,
         affected_rows: int,
         before_snapshot: List[Dict[str, Any]],
+        schema_checksum: Optional[str] = None,
+        rollback_of: Optional[str] = None,
     ) -> ChangeSet:
         """Generates a new ChangeSet and persists it to disk."""
-        date_str = time.strftime("%Y%m%d")
-        short_id = uuid.uuid4().hex[:6].upper()
-        cs_id = f"CS-{date_str}-{short_id}"
+        snapshot_dict = None
+        if before_snapshot:
+            snapshot_dict = {
+                "table": table_name,
+                "operation": operation,
+                "pk_columns": ["id"],
+                "rows": [{"pk": {"id": r.get("id")}, "before": r} for r in before_snapshot],
+            }
+
+        meta = self.recovery_mgr.create_change_record(
+            database=database,
+            sql=sql,
+            table_name=table_name,
+            operation=operation,
+            affected_rows=affected_rows,
+            snapshot_data=snapshot_dict,
+            schema_checksum=schema_checksum,
+            rollback_of=rollback_of,
+        )
 
-        cs = ChangeSet(
-            change_set_id=cs_id,
+        return ChangeSet(
+            change_set_id=meta["change_id"],
             database=database,
             sql=sql,
             table_name=table_name,
-            operation=operation.upper(),
-            timestamp=time.strftime("%Y-%m-%d %H:%M:%S"),
+            operation=operation,
+            timestamp=meta["executed_at"],
             affected_rows=affected_rows,
             before_snapshot=before_snapshot,
-            status="COMMITTED",
+            status=meta["recovery_status"],
+            rollback_of=rollback_of,
+            expires_at=meta["expires_at"],
         )
 
-        file_path = self.storage_dir / f"{cs_id}.json"
-        with open(file_path, "w", encoding="utf-8") as f:
-            json.dump(cs.to_dict(), f, indent=2)
-
-        return cs
-
     def get_change_set(self, change_set_id: str) -> Optional[ChangeSet]:
-        """Retrieves a ChangeSet by its ID."""
-        file_path = self.storage_dir / f"{change_set_id}.json"
-        if not file_path.exists():
-            return None
-        try:
-            with open(file_path, "r", encoding="utf-8") as f:
-                data = json.load(f)
-            return ChangeSet.from_dict(data)
-        except Exception:
+        meta = self.recovery_mgr.get_change_record(change_set_id)
+        if not meta:
             return None
+        snap = self.recovery_mgr.get_snapshot(change_set_id)
+        before_rows = []
+        if snap and "rows" in snap:
+            for r in snap["rows"]:
+                before_rows.append(r.get("before", {}))
+        meta["before_snapshot"] = before_rows
+        return ChangeSet.from_dict(meta)
 
     def list_change_sets(self, limit: int = 20) -> List[ChangeSet]:
-        """Lists recent change sets sorted newest first."""
+        records = self.recovery_mgr.list_changes(limit=limit)
         results = []
-        files = sorted(self.storage_dir.glob("CS-*.json"), reverse=True)
-        for f in files[:limit]:
-            try:
-                with open(f, "r", encoding="utf-8") as fp:
-                    results.append(ChangeSet.from_dict(json.load(fp)))
-            except Exception:
-                continue
+        for r in records:
+            results.append(ChangeSet.from_dict(r))
         return results
 
     def generate_rollback_sql(self, change_set: ChangeSet, primary_key: str = "id") -> List[str]:
-        """
-        Generates inverse SQL statements to restore the before_snapshot.
-        """
+        """Generates inverse SQL statements to restore the before_snapshot."""
         if not change_set.before_snapshot:
             return []