roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/persistence/database_manager.py

@@ -0,0 +1,492 @@
+"""Database infrastructure manager for SQLite persistence layer.
+
+This module handles database connection, initialization, and migrations.
+It separates database infrastructure concerns from the state management layer.
+"""
+
+import sqlite3
+import threading
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class DatabaseError(Exception):
+    """Base exception for database operations."""
+
+    pass
+
+
+class DatabaseManager:
+    """Manages SQLite database connections, initialization, and migrations."""
+
+    def __init__(self, db_path: str | Path | None = None):
+        """Initialize the database manager.
+
+        Args:
+            db_path: Path to SQLite database file. Defaults to ~/.roadmap/roadmap.db
+        """
+        if db_path is None:
+            db_path = Path.home() / ".roadmap" / "roadmap.db"
+
+        self.db_path = Path(db_path)
+        try:
+            self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            logger.error(
+                "database_directory_create_failed",
+                db_path=str(self.db_path),
+                error=str(e),
+                error_type=type(e).__name__,
+                severity="system_error",
+            )
+            raise DatabaseError(
+                f"Failed to create database directory for {self.db_path}: {e}"
+            ) from e
+
+        # Thread-local storage for connections
+        self._local = threading.local()
+
+        logger.info("Initializing database manager", db_path=str(self.db_path))
+        try:
+            self._init_database()
+        except sqlite3.Error as e:
+            logger.error(
+                "database_schema_init_failed",
+                db_path=str(self.db_path),
+                error=str(e),
+                error_type=type(e).__name__,
+                severity="system_error",
+            )
+            raise DatabaseError(
+                f"Failed to initialize database schema at {self.db_path}: {e}"
+            ) from e
+
+    def validate_read_write(self) -> None:
+        """Validate that the database is readable and writable."""
+        conn = self._get_connection()
+        try:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS db_health_check (
+                    id INTEGER PRIMARY KEY,
+                    checked_at TIMESTAMP
+                )
+                """
+            )
+            conn.execute(
+                "INSERT INTO db_health_check (checked_at) VALUES (?)",
+                (datetime.now(UTC).isoformat(),),
+            )
+            row_id = conn.execute("SELECT last_insert_rowid()").fetchone()[0]
+            conn.execute("DELETE FROM db_health_check WHERE id = ?", (row_id,))
+        except sqlite3.Error as e:
+            logger.error(
+                "database_read_write_failed",
+                db_path=str(self.db_path),
+                error=str(e),
+                error_type=type(e).__name__,
+                severity="system_error",
+            )
+            raise DatabaseError(
+                f"Database read/write check failed for {self.db_path}: {e}"
+            ) from e
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get thread-local database connection."""
+        if not hasattr(self._local, "connection"):
+            self._local.connection = sqlite3.connect(
+                str(self.db_path),
+                check_same_thread=False,
+                timeout=30.0,
+                isolation_level=None,  # Autocommit mode
+            )
+            # Register datetime adapter for Python 3.12+
+            sqlite3.register_adapter(datetime, lambda dt: dt.isoformat())
+            sqlite3.register_converter(
+                "TIMESTAMP", lambda val: datetime.fromisoformat(val.decode())
+            )
+
+            # Enable foreign keys and WAL mode for better performance
+            self._local.connection.execute("PRAGMA foreign_keys = ON")
+            self._local.connection.execute("PRAGMA journal_mode = WAL")
+            self._local.connection.execute("PRAGMA synchronous = NORMAL")
+            self._local.connection.row_factory = sqlite3.Row
+
+        return self._local.connection
+
+    @contextmanager
+    def transaction(self):
+        """Context manager for database transactions."""
+        conn = self._get_connection()
+        try:
+            conn.execute("BEGIN IMMEDIATE")
+            yield conn
+            conn.execute("COMMIT")
+        except Exception:
+            try:
+                conn.execute("ROLLBACK")
+            except sqlite3.OperationalError:
+                # Transaction might not be active
+                logger.debug(
+                    "rollback_failed_transaction_not_active", severity="operational"
+                )
+            raise
+
+    def _init_database(self):
+        """Initialize database schema."""
+        schema_sql = """
+        -- Projects table
+        CREATE TABLE IF NOT EXISTS projects (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            description TEXT,
+            status TEXT NOT NULL DEFAULT 'active',
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            metadata TEXT  -- JSON for additional data
+        );
+
+        -- Milestones table
+        CREATE TABLE IF NOT EXISTS milestones (
+            id TEXT PRIMARY KEY,
+            project_id TEXT NOT NULL,
+            title TEXT NOT NULL,
+            description TEXT,
+            status TEXT NOT NULL DEFAULT 'open',
+            due_date DATE,
+            progress_percentage REAL DEFAULT 0.0,
+            archived BOOLEAN DEFAULT 0,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            metadata TEXT,  -- JSON for additional data
+            FOREIGN KEY (project_id) REFERENCES projects (id) ON DELETE CASCADE
+        );
+
+        -- Issues table
+        CREATE TABLE IF NOT EXISTS issues (
+            id TEXT PRIMARY KEY,
+            project_id TEXT,
+            milestone_id TEXT,
+            title TEXT NOT NULL,
+            headline TEXT DEFAULT '',  -- Short summary for list views
+            description TEXT,  -- Full markdown content
+            status TEXT NOT NULL DEFAULT 'open',
+            priority TEXT NOT NULL DEFAULT 'medium',
+            issue_type TEXT NOT NULL DEFAULT 'task',
+            assignee TEXT,
+            estimate_hours REAL,
+            archived BOOLEAN DEFAULT 0,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            due_date DATE,
+            metadata TEXT,  -- JSON for additional data
+            FOREIGN KEY (project_id) REFERENCES projects (id) ON DELETE CASCADE,
+            FOREIGN KEY (milestone_id) REFERENCES milestones (id) ON DELETE SET NULL
+        );
+
+        -- Issue dependencies table
+        CREATE TABLE IF NOT EXISTS issue_dependencies (
+            issue_id TEXT NOT NULL,
+            depends_on_id TEXT NOT NULL,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (issue_id, depends_on_id),
+            FOREIGN KEY (issue_id) REFERENCES issues (id) ON DELETE CASCADE,
+            FOREIGN KEY (depends_on_id) REFERENCES issues (id) ON DELETE CASCADE
+        );
+
+        -- Issue labels table (many-to-many)
+        CREATE TABLE IF NOT EXISTS issue_labels (
+            issue_id TEXT NOT NULL,
+            label TEXT NOT NULL,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (issue_id, label),
+            FOREIGN KEY (issue_id) REFERENCES issues (id) ON DELETE CASCADE
+        );
+
+        -- Comments table
+        CREATE TABLE IF NOT EXISTS comments (
+            id TEXT PRIMARY KEY,
+            issue_id TEXT NOT NULL,
+            author TEXT NOT NULL,
+            content TEXT NOT NULL,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            metadata TEXT,  -- JSON for additional data
+            FOREIGN KEY (issue_id) REFERENCES issues (id) ON DELETE CASCADE
+        );
+
+        -- Sync base state (three-way merge baseline from last successful sync)
+        -- Note: issue_id does NOT have a foreign key constraint because sync baseline
+        -- can be saved before issues are persisted to the database (during sync operations)
+        CREATE TABLE IF NOT EXISTS sync_base_state (
+            issue_id TEXT PRIMARY KEY,
+            status TEXT NOT NULL,
+            assignee TEXT,
+            milestone TEXT,
+            description TEXT,
+            labels TEXT,  -- JSON array of label strings
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            synced_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+
+        -- Sync metadata (overall sync state)
+        CREATE TABLE IF NOT EXISTS sync_metadata (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+
+        -- File synchronization tracking
+        CREATE TABLE IF NOT EXISTS file_sync_state (
+            file_path TEXT PRIMARY KEY,
+            content_hash TEXT NOT NULL,
+            file_size INTEGER,
+            last_modified TIMESTAMP,
+            last_synced TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+
+        -- Indexes for performance
+        CREATE INDEX IF NOT EXISTS idx_sync_base_state_synced_at ON sync_base_state (synced_at);
+        CREATE INDEX IF NOT EXISTS idx_milestones_project_id ON milestones (project_id);
+        CREATE INDEX IF NOT EXISTS idx_issues_project_id ON issues (project_id);
+        CREATE INDEX IF NOT EXISTS idx_issues_milestone_id ON issues (milestone_id);
+        CREATE INDEX IF NOT EXISTS idx_issues_assignee ON issues (assignee);
+        CREATE INDEX IF NOT EXISTS idx_issues_status ON issues (status);
+        CREATE INDEX IF NOT EXISTS idx_comments_issue_id ON comments (issue_id);
+
+        -- Triggers for updated_at timestamps
+        CREATE TRIGGER IF NOT EXISTS update_projects_timestamp
+        AFTER UPDATE ON projects
+        BEGIN
+            UPDATE projects SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS update_milestones_timestamp
+        AFTER UPDATE ON milestones
+        BEGIN
+            UPDATE milestones SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS update_issues_timestamp
+        AFTER UPDATE ON issues
+        BEGIN
+            UPDATE issues SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS update_comments_timestamp
+        AFTER UPDATE ON comments
+        BEGIN
+            UPDATE comments SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+        END;
+        """
+
+        conn = self._get_connection()
+        conn.executescript(schema_sql)
+
+        logger.info("Database schema initialized")
+
+        # Run migrations
+        self._run_migrations()
+
+    def _migration_archive_columns(self, cursor) -> list[str]:
+        """Migration 1: add archived/archived_at to projects, milestones, issues."""
+        result = []
+        for table in ("projects", "milestones", "issues"):
+            cursor.execute(f"PRAGMA table_info({table})")  # noqa: S608
+            if "archived" not in [col[1] for col in cursor.fetchall()]:
+                result.append(
+                    f"ALTER TABLE {table} ADD COLUMN archived INTEGER DEFAULT 0;\n"
+                    f"ALTER TABLE {table} ADD COLUMN archived_at TIMESTAMP NULL;"
+                )
+        return result
+
+    def _migration_sync_base_state(self, cursor) -> list[str]:
+        """Migration 2: create sync_base_state table."""
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='sync_base_state'"
+        )
+        if cursor.fetchone():
+            return []
+        return [
+            """
+            CREATE TABLE sync_base_state (
+                issue_id TEXT PRIMARY KEY,
+                status TEXT NOT NULL,
+                assignee TEXT,
+                milestone TEXT,
+                description TEXT,
+                labels TEXT,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                synced_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            CREATE INDEX idx_sync_base_state_synced_at ON sync_base_state (synced_at);
+        """
+        ]
+
+    def _migration_issue_remote_links(self, cursor) -> list[str]:
+        """Migration 3: create issue_remote_links table."""
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='issue_remote_links'"
+        )
+        if cursor.fetchone():
+            return []
+        return [
+            """
+            CREATE TABLE issue_remote_links (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                issue_uuid TEXT NOT NULL,
+                backend_name TEXT NOT NULL,
+                remote_id TEXT NOT NULL,
+                linked_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                UNIQUE(issue_uuid, backend_name),
+                FOREIGN KEY (issue_uuid) REFERENCES issues (id) ON DELETE CASCADE
+            );
+            CREATE INDEX idx_issue_remote_links_backend ON issue_remote_links (backend_name);
+            CREATE INDEX idx_issue_remote_links_issue_uuid ON issue_remote_links (issue_uuid);
+        """
+        ]
+
+    def _migration_headline_column(self, cursor) -> list[str]:
+        """Migration 4: add headline column to issues table."""
+        cursor.execute("PRAGMA table_info(issues)")
+        issue_columns = (
+            [row[1] for row in cursor.fetchall()] if cursor.fetchone() else []
+        )
+        if "headline" in issue_columns:
+            return []
+        return ["ALTER TABLE issues ADD COLUMN headline TEXT DEFAULT '';"]
+
+    def _migration_sync_base_state_columns(self, cursor) -> list[str]:
+        """Migration 5: add headline and content columns to sync_base_state."""
+        cursor.execute("PRAGMA table_info(sync_base_state)")
+        columns = [row[1] for row in cursor.fetchall()] if cursor.fetchone() else []
+        if "headline" in columns or "content" in columns:
+            return []
+        return [
+            """
+            ALTER TABLE sync_base_state ADD COLUMN headline TEXT DEFAULT '';
+            ALTER TABLE sync_base_state ADD COLUMN content TEXT DEFAULT '';
+        """
+        ]
+
+    def _migration_sync_metrics(self, cursor) -> list[str]:
+        """Migration 6: create sync_metrics table."""
+        cursor.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='sync_metrics'"
+        )
+        if cursor.fetchone():
+            return []
+        return [
+            """
+            CREATE TABLE sync_metrics (
+                id TEXT PRIMARY KEY,
+                operation_id TEXT NOT NULL UNIQUE,
+                backend_type TEXT NOT NULL,
+                duration_seconds REAL NOT NULL DEFAULT 0.0,
+                metrics_json TEXT NOT NULL,  -- Full SyncMetrics.to_dict() as JSON
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            CREATE INDEX IF NOT EXISTS idx_sync_metrics_backend_type ON sync_metrics (backend_type);
+            CREATE INDEX IF NOT EXISTS idx_sync_metrics_created_at ON sync_metrics (created_at);
+            CREATE INDEX IF NOT EXISTS idx_sync_metrics_operation_id ON sync_metrics (operation_id);
+        """
+        ]
+
+    def _run_migrations(self):
+        """Run database migrations for schema updates."""
+        conn = self._get_connection()
+        cursor = conn.cursor()
+
+        migrations = (
+            self._migration_archive_columns(cursor)
+            + self._migration_sync_base_state(cursor)
+            + self._migration_issue_remote_links(cursor)
+            + self._migration_headline_column(cursor)
+            + self._migration_sync_base_state_columns(cursor)
+            + self._migration_sync_metrics(cursor)
+        )
+
+        for migration_sql in migrations:
+            try:
+                conn.executescript(migration_sql)
+                logger.info("applied_database_migration")
+            except Exception as e:
+                logger.warning(
+                    "migration_may_have_been_applied",
+                    error=str(e),
+                    severity="operational",
+                )
+
+        conn.commit()
+
+    def is_initialized(self) -> bool:
+        """Check if database is properly initialized."""
+        try:
+            conn = self._get_connection()
+            result = conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='projects'"
+            ).fetchone()
+            return result is not None
+        except Exception as e:
+            logger.error(
+                "Failed to check database initialization",
+                error=str(e),
+                severity="infrastructure",
+            )
+            return False
+
+    def close(self):
+        """Close database connections."""
+        if hasattr(self._local, "connection"):
+            self._local.connection.close()
+            delattr(self._local, "connection")
+
+    def vacuum(self):
+        """Optimize database."""
+        conn = self._get_connection()
+        conn.execute("VACUUM")
+        logger.info("Database vacuumed")
+
+    def database_exists(self) -> bool:
+        """Check if database file exists and has tables."""
+        if not self.db_path.exists():
+            return False
+
+        try:
+            conn = self._get_connection()
+            # Check if our main tables exist
+            tables = conn.execute("""
+                SELECT name FROM sqlite_master
+                WHERE type='table' AND name IN ('issues', 'milestones', 'projects')
+            """).fetchall()
+
+            # We should have at least our core tables
+            return len(tables) >= 3
+
+        except Exception as e:
+            logger.warning(
+                "Error checking database existence",
+                error=str(e),
+                severity="infrastructure",
+            )
+            return False
+
+    def is_safe_for_writes(self) -> tuple[bool, str]:
+        """Check if database is safe for write operations."""
+        try:
+            # Check database integrity
+            conn = self._get_connection()
+            try:
+                conn.execute("PRAGMA integrity_check").fetchone()
+            except sqlite3.DatabaseError as e:
+                return False, f"Database corruption detected: {e}"
+
+            return True, "Database ready for operations"
+
+        except Exception as e:
+            return False, f"Safety check failed: {e}"