oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/utils/storage/database.py

@@ -0,0 +1,1166 @@
+"""Database backend for storing and querying analysis results.
+
+This module provides a comprehensive database abstraction for persisting
+hardware reverse engineering session data including protocols, messages,
+and analysis results.
+
+Example:
+    >>> from oscura.utils.storage import DatabaseBackend, DatabaseConfig
+    >>>
+    >>> # SQLite (default, no dependencies)
+    >>> config = DatabaseConfig(url="sqlite:///analysis.db")
+    >>> db = DatabaseBackend(config)
+    >>>
+    >>> # PostgreSQL (optional)
+    >>> config = DatabaseConfig(
+    ...     url="postgresql://user:pass@localhost/oscura",
+    ...     pool_size=10
+    ... )
+    >>> db = DatabaseBackend(config)
+    >>>
+    >>> # Store analysis workflow
+    >>> project_id = db.create_project("CAN Bus RE", "Automotive reverse engineering")
+    >>> session_id = db.create_session(project_id, "can", {"bus": "HS-CAN"})
+    >>> protocol_id = db.store_protocol(session_id, "UDS", spec_json, confidence=0.9)
+    >>> db.store_message(protocol_id, timestamp=1.5, data=b"\\x02\\x10\\x01", decoded)
+    >>>
+    >>> # Query historical data
+    >>> protocols = db.find_protocols(name_pattern="UDS%", min_confidence=0.8)
+    >>> messages = db.query_messages(protocol_id, time_range=(0.0, 10.0))
+    >>> results = db.get_analysis_results(session_id, analysis_type="dpa")
+
+Architecture:
+    - SQLite by default (serverless, file-based)
+    - PostgreSQL optional (production deployments)
+    - Raw SQL fallback (no ORM dependencies)
+    - Connection pooling for performance
+    - Automatic schema migration
+    - Transaction support
+
+Database Schema:
+    projects: Project metadata and descriptions
+    sessions: Analysis sessions per project
+    protocols: Discovered protocols per session
+    messages: Decoded messages per protocol
+    analysis_results: DPA, timing, entropy, etc.
+
+References:
+    V0.6.0_COMPLETE_COMPREHENSIVE_PLAN.md: Phase 5 Feature 45
+    SQLite Documentation: https://www.sqlite.org/docs.html
+    PostgreSQL Documentation: https://www.postgresql.org/docs/
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# Optional PostgreSQL support
+try:
+    import psycopg2  # type: ignore[import-untyped]
+    from psycopg2.pool import SimpleConnectionPool  # type: ignore[import-untyped]
+
+    HAS_POSTGRES = True
+except ImportError:
+    psycopg2 = None
+    SimpleConnectionPool = None
+    HAS_POSTGRES = False
+
+
+logger = logging.getLogger(__name__)
+
+# SQL Schema constants for SQLite
+_SQL_CREATE_PROJECTS_SQLITE = """
+CREATE TABLE IF NOT EXISTS projects (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    metadata TEXT
+)
+"""
+
+_SQL_CREATE_SESSIONS_SQLITE = """
+CREATE TABLE IF NOT EXISTS sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id INTEGER NOT NULL,
+    session_type TEXT NOT NULL,
+    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    metadata TEXT,
+    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+)
+"""
+
+_SQL_CREATE_PROTOCOLS_SQLITE = """
+CREATE TABLE IF NOT EXISTS protocols (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    spec_json TEXT NOT NULL,
+    confidence REAL NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+)
+"""
+
+_SQL_CREATE_MESSAGES_SQLITE = """
+CREATE TABLE IF NOT EXISTS messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    protocol_id INTEGER NOT NULL,
+    timestamp REAL NOT NULL,
+    data TEXT NOT NULL,
+    decoded_fields TEXT,
+    FOREIGN KEY (protocol_id) REFERENCES protocols(id) ON DELETE CASCADE
+)
+"""
+
+_SQL_CREATE_ANALYSIS_SQLITE = """
+CREATE TABLE IF NOT EXISTS analysis_results (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    analysis_type TEXT NOT NULL,
+    results_json TEXT NOT NULL,
+    metrics TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+)
+"""
+
+# SQL Schema constants for PostgreSQL
+_SQL_CREATE_PROJECTS_POSTGRES = """
+CREATE TABLE IF NOT EXISTS projects (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    metadata JSONB
+)
+"""
+
+_SQL_CREATE_SESSIONS_POSTGRES = """
+CREATE TABLE IF NOT EXISTS sessions (
+    id SERIAL PRIMARY KEY,
+    project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    session_type TEXT NOT NULL,
+    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    metadata JSONB
+)
+"""
+
+_SQL_CREATE_PROTOCOLS_POSTGRES = """
+CREATE TABLE IF NOT EXISTS protocols (
+    id SERIAL PRIMARY KEY,
+    session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    spec_json JSONB NOT NULL,
+    confidence REAL NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+_SQL_CREATE_MESSAGES_POSTGRES = """
+CREATE TABLE IF NOT EXISTS messages (
+    id SERIAL PRIMARY KEY,
+    protocol_id INTEGER NOT NULL REFERENCES protocols(id) ON DELETE CASCADE,
+    timestamp REAL NOT NULL,
+    data TEXT NOT NULL,
+    decoded_fields JSONB
+)
+"""
+
+_SQL_CREATE_ANALYSIS_POSTGRES = """
+CREATE TABLE IF NOT EXISTS analysis_results (
+    id SERIAL PRIMARY KEY,
+    session_id INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    analysis_type TEXT NOT NULL,
+    results_json JSONB NOT NULL,
+    metrics JSONB,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+"""
+
+# Index creation statements
+_SQL_CREATE_INDEXES = [
+    "CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_id)",
+    "CREATE INDEX IF NOT EXISTS idx_protocols_session ON protocols(session_id)",
+    "CREATE INDEX IF NOT EXISTS idx_protocols_name ON protocols(name)",
+    "CREATE INDEX IF NOT EXISTS idx_messages_protocol ON messages(protocol_id)",
+    "CREATE INDEX IF NOT EXISTS idx_messages_timestamp ON messages(timestamp)",
+    "CREATE INDEX IF NOT EXISTS idx_analysis_session ON analysis_results(session_id)",
+]
+
+
+@dataclass
+class DatabaseConfig:
+    """Database configuration.
+
+    Attributes:
+        url: Database URL (sqlite:///path.db or postgresql://...)
+        pool_size: Connection pool size (PostgreSQL only)
+        timeout: Connection timeout in seconds
+        echo_sql: Log SQL statements for debugging
+
+    Example:
+        >>> # SQLite (default)
+        >>> config = DatabaseConfig(url="sqlite:///analysis.db")
+        >>>
+        >>> # PostgreSQL
+        >>> config = DatabaseConfig(
+        ...     url="postgresql://user:pass@localhost/oscura",
+        ...     pool_size=10,
+        ...     timeout=30.0
+        ... )
+    """
+
+    url: str = "sqlite:///oscura_analysis.db"
+    pool_size: int = 5
+    timeout: float = 30.0
+    echo_sql: bool = False
+
+
+@dataclass
+class Project:
+    """Project metadata.
+
+    Attributes:
+        id: Project ID (auto-assigned)
+        name: Project name
+        description: Project description
+        created_at: Creation timestamp
+        updated_at: Last update timestamp
+        metadata: Additional metadata
+
+    Example:
+        >>> project = Project(
+        ...     id=1,
+        ...     name="Automotive CAN",
+        ...     description="CAN bus protocol analysis",
+        ...     created_at=datetime.now(UTC),
+        ...     updated_at=datetime.now(UTC)
+        ... )
+    """
+
+    id: int | None = None
+    name: str = ""
+    description: str = ""
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Session:
+    """Analysis session.
+
+    Attributes:
+        id: Session ID (auto-assigned)
+        project_id: Parent project ID
+        session_type: Session type (blackbox, can, uart, etc.)
+        timestamp: Session timestamp
+        metadata: Session-specific metadata
+
+    Example:
+        >>> session = Session(
+        ...     id=1,
+        ...     project_id=1,
+        ...     session_type="blackbox",
+        ...     timestamp=datetime.now(UTC),
+        ...     metadata={"capture_file": "device.bin"}
+        ... )
+    """
+
+    id: int | None = None
+    project_id: int | None = None
+    session_type: str = ""
+    timestamp: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Protocol:
+    """Discovered protocol.
+
+    Attributes:
+        id: Protocol ID (auto-assigned)
+        session_id: Parent session ID
+        name: Protocol name
+        spec_json: Protocol specification as JSON
+        confidence: Confidence score (0.0-1.0)
+        created_at: Creation timestamp
+
+    Example:
+        >>> protocol = Protocol(
+        ...     id=1,
+        ...     session_id=1,
+        ...     name="IoT Protocol",
+        ...     spec_json={"fields": [...]},
+        ...     confidence=0.85
+        ... )
+    """
+
+    id: int | None = None
+    session_id: int | None = None
+    name: str = ""
+    spec_json: dict[str, Any] = field(default_factory=dict)
+    confidence: float = 0.0
+    created_at: datetime | None = None
+
+
+@dataclass
+class Message:
+    """Decoded message.
+
+    Attributes:
+        id: Message ID (auto-assigned)
+        protocol_id: Parent protocol ID
+        timestamp: Message timestamp
+        data: Raw message data (hex string)
+        decoded_fields: Decoded field values
+
+    Example:
+        >>> message = Message(
+        ...     id=1,
+        ...     protocol_id=1,
+        ...     timestamp=1.5,
+        ...     data="aa5501",
+        ...     decoded_fields={"id": 1, "counter": 0}
+        ... )
+    """
+
+    id: int | None = None
+    protocol_id: int | None = None
+    timestamp: float = 0.0
+    data: str = ""
+    decoded_fields: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AnalysisResult:
+    """Analysis result.
+
+    Attributes:
+        id: Result ID (auto-assigned)
+        session_id: Parent session ID
+        analysis_type: Analysis type (dpa, timing, entropy, etc.)
+        results_json: Analysis results as JSON
+        metrics: Computed metrics
+        created_at: Creation timestamp
+
+    Example:
+        >>> result = AnalysisResult(
+        ...     id=1,
+        ...     session_id=1,
+        ...     analysis_type="dpa",
+        ...     results_json={"recovered_key": "0x1234..."},
+        ...     metrics={"confidence": 0.95}
+        ... )
+    """
+
+    id: int | None = None
+    session_id: int | None = None
+    analysis_type: str = ""
+    results_json: dict[str, Any] = field(default_factory=dict)
+    metrics: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime | None = None
+
+
+@dataclass
+class QueryResult:
+    """Paginated query result.
+
+    Attributes:
+        items: Result items
+        total: Total number of results
+        page: Current page number (0-indexed)
+        page_size: Items per page
+
+    Example:
+        >>> result = QueryResult(
+        ...     items=[msg1, msg2, msg3],
+        ...     total=100,
+        ...     page=0,
+        ...     page_size=10
+        ... )
+        >>> print(f"Page 1/{result.total_pages}: {len(result.items)} items")
+    """
+
+    items: list[Any] = field(default_factory=list)
+    total: int = 0
+    page: int = 0
+    page_size: int = 100
+
+    @property
+    def total_pages(self) -> int:
+        """Calculate total number of pages.
+
+        Returns:
+            Number of pages (at least 1)
+        """
+        return max(1, (self.total + self.page_size - 1) // self.page_size)
+
+    @property
+    def has_next(self) -> bool:
+        """Check if there is a next page.
+
+        Returns:
+            True if more pages available
+        """
+        return self.page < self.total_pages - 1
+
+    @property
+    def has_prev(self) -> bool:
+        """Check if there is a previous page.
+
+        Returns:
+            True if previous pages exist
+        """
+        return self.page > 0
+
+
+class DatabaseBackend:
+    """Database backend for storing analysis results.
+
+    Supports SQLite (default) and PostgreSQL (optional).
+    Uses raw SQL for simplicity and graceful degradation.
+
+    Example:
+        >>> config = DatabaseConfig(url="sqlite:///analysis.db")
+        >>> db = DatabaseBackend(config)
+        >>>
+        >>> # Create project hierarchy
+        >>> proj_id = db.create_project("IoT RE", "Device protocol analysis")
+        >>> sess_id = db.create_session(proj_id, "blackbox", {"file": "capture.bin"})
+        >>> prot_id = db.store_protocol(sess_id, "IoT", {"fields": []}, 0.9)
+        >>>
+        >>> # Store messages
+        >>> db.store_message(prot_id, 0.0, b"\\xaa\\x55", {"id": 1})
+        >>>
+        >>> # Query
+        >>> protocols = db.find_protocols(min_confidence=0.8)
+        >>> messages = db.query_messages(prot_id, limit=10)
+    """
+
+    def __init__(self, config: DatabaseConfig | None = None) -> None:
+        """Initialize database backend.
+
+        Args:
+            config: Database configuration (default: SQLite)
+
+        Raises:
+            ValueError: If PostgreSQL URL but psycopg2 not installed
+            sqlite3.Error: If SQLite database creation fails
+        """
+        self.config = config or DatabaseConfig()
+        self._conn: Any = None
+        self._pool: Any = None
+
+        # Determine backend type
+        self._is_postgres = self.config.url.startswith("postgresql://")
+
+        if self._is_postgres and not HAS_POSTGRES:
+            raise ValueError(
+                "PostgreSQL URL specified but psycopg2 not installed. "
+                "Install with: pip install psycopg2-binary"
+            )
+
+        # Initialize connection/pool
+        self._init_connection()
+
+        # Create schema
+        self._create_schema()
+
+    def _init_connection(self) -> None:
+        """Initialize database connection or pool."""
+        if self._is_postgres:
+            # PostgreSQL connection pool
+            self._pool = SimpleConnectionPool(
+                1,
+                self.config.pool_size,
+                self.config.url,
+                connect_timeout=int(self.config.timeout),
+            )
+        else:
+            # SQLite connection
+            db_path = self.config.url.replace("sqlite:///", "")
+            Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+            self._conn = sqlite3.connect(
+                db_path,
+                timeout=self.config.timeout,
+                check_same_thread=False,
+            )
+            self._conn.row_factory = sqlite3.Row
+
+    def _get_connection(self) -> Any:
+        """Get database connection.
+
+        Returns:
+            Connection object (sqlite3.Connection or psycopg2.connection)
+        """
+        if self._is_postgres:
+            return self._pool.getconn()
+        return self._conn
+
+    def _return_connection(self, conn: Any) -> None:
+        """Return connection to pool (PostgreSQL only).
+
+        Args:
+            conn: Connection to return
+        """
+        if self._is_postgres:
+            self._pool.putconn(conn)
+
+    def _execute(self, sql: str, params: tuple[Any, ...] = ()) -> Any:
+        """Execute SQL statement.
+
+        Args:
+            sql: SQL statement
+            params: Query parameters
+
+        Returns:
+            Cursor after execution
+        """
+        conn = self._get_connection()
+        try:
+            cursor = conn.cursor()
+            if self.config.echo_sql:
+                logger.debug(f"SQL: {sql}")
+                logger.debug(f"Params: {params}")
+            cursor.execute(sql, params)
+            conn.commit()
+            return cursor
+        finally:
+            self._return_connection(conn)
+
+    def _fetchall(self, sql: str, params: tuple[Any, ...] = ()) -> list[Any]:
+        """Execute query and fetch all results.
+
+        Args:
+            sql: SQL query
+            params: Query parameters
+
+        Returns:
+            List of row dictionaries
+        """
+        conn = self._get_connection()
+        try:
+            cursor = conn.cursor()
+            if self.config.echo_sql:
+                logger.debug(f"SQL: {sql}")
+                logger.debug(f"Params: {params}")
+            cursor.execute(sql, params)
+
+            if self._is_postgres:
+                columns = [desc[0] for desc in cursor.description]
+                return [dict(zip(columns, row, strict=True)) for row in cursor.fetchall()]
+            else:
+                return [dict(row) for row in cursor.fetchall()]
+        finally:
+            self._return_connection(conn)
+
+    def _fetchone(self, sql: str, params: tuple[Any, ...] = ()) -> dict[str, Any] | None:
+        """Execute query and fetch one result.
+
+        Args:
+            sql: SQL query
+            params: Query parameters
+
+        Returns:
+            Row dictionary or None
+        """
+        results = self._fetchall(sql, params)
+        return results[0] if results else None
+
+    def _create_schema(self) -> None:
+        """Create database schema if not exists."""
+        tables = [
+            ("projects", _SQL_CREATE_PROJECTS_SQLITE, _SQL_CREATE_PROJECTS_POSTGRES),
+            ("sessions", _SQL_CREATE_SESSIONS_SQLITE, _SQL_CREATE_SESSIONS_POSTGRES),
+            ("protocols", _SQL_CREATE_PROTOCOLS_SQLITE, _SQL_CREATE_PROTOCOLS_POSTGRES),
+            ("messages", _SQL_CREATE_MESSAGES_SQLITE, _SQL_CREATE_MESSAGES_POSTGRES),
+            ("analysis_results", _SQL_CREATE_ANALYSIS_SQLITE, _SQL_CREATE_ANALYSIS_POSTGRES),
+        ]
+
+        for _, sqlite_sql, postgres_sql in tables:
+            self._execute(sqlite_sql if not self._is_postgres else postgres_sql)
+
+        # Create indexes
+        for idx_sql in _SQL_CREATE_INDEXES:
+            self._execute(idx_sql)
+
+    def create_project(
+        self, name: str, description: str = "", metadata: dict[str, Any] | None = None
+    ) -> int:
+        """Create new project.
+
+        Args:
+            name: Project name
+            description: Project description
+            metadata: Additional metadata
+
+        Returns:
+            Project ID
+
+        Example:
+            >>> db = DatabaseBackend()
+            >>> project_id = db.create_project("IoT RE", "Unknown device protocol")
+        """
+        metadata_json = json.dumps(metadata or {})
+        cursor = self._execute(
+            "INSERT INTO projects (name, description, metadata) VALUES (?, ?, ?)",
+            (name, description, metadata_json),
+        )
+        result: int = cursor.lastrowid
+        return result
+
+    def get_project(self, project_id: int) -> Project | None:
+        """Get project by ID.
+
+        Args:
+            project_id: Project ID
+
+        Returns:
+            Project or None if not found
+
+        Example:
+            >>> project = db.get_project(1)
+            >>> print(project.name)
+        """
+        row = self._fetchone("SELECT * FROM projects WHERE id = ?", (project_id,))
+        if not row:
+            return None
+
+        return Project(
+            id=row["id"],
+            name=row["name"],
+            description=row["description"] or "",
+            created_at=datetime.fromisoformat(row["created_at"]),
+            updated_at=datetime.fromisoformat(row["updated_at"]),
+            metadata=json.loads(row["metadata"]) if row["metadata"] else {},
+        )
+
+    def list_projects(self) -> list[Project]:
+        """List all projects.
+
+        Returns:
+            List of projects
+
+        Example:
+            >>> projects = db.list_projects()
+            >>> for proj in projects:
+            ...     print(f"{proj.id}: {proj.name}")
+        """
+        rows = self._fetchall("SELECT * FROM projects ORDER BY updated_at DESC")
+        return [
+            Project(
+                id=row["id"],
+                name=row["name"],
+                description=row["description"] or "",
+                created_at=datetime.fromisoformat(row["created_at"]),
+                updated_at=datetime.fromisoformat(row["updated_at"]),
+                metadata=json.loads(row["metadata"]) if row["metadata"] else {},
+            )
+            for row in rows
+        ]
+
+    def create_session(
+        self,
+        project_id: int,
+        session_type: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> int:
+        """Create new session.
+
+        Args:
+            project_id: Parent project ID
+            session_type: Session type (blackbox, can, uart, etc.)
+            metadata: Session metadata
+
+        Returns:
+            Session ID
+
+        Example:
+            >>> session_id = db.create_session(
+            ...     project_id=1,
+            ...     session_type="blackbox",
+            ...     metadata={"capture": "device.bin"}
+            ... )
+        """
+        metadata_json = json.dumps(metadata or {})
+        cursor = self._execute(
+            "INSERT INTO sessions (project_id, session_type, metadata) VALUES (?, ?, ?)",
+            (project_id, session_type, metadata_json),
+        )
+        result: int = cursor.lastrowid
+        return result
+
+    def get_sessions(self, project_id: int) -> list[Session]:
+        """Get all sessions for project.
+
+        Args:
+            project_id: Project ID
+
+        Returns:
+            List of sessions
+
+        Example:
+            >>> sessions = db.get_sessions(project_id=1)
+            >>> for sess in sessions:
+            ...     print(f"{sess.id}: {sess.session_type}")
+        """
+        rows = self._fetchall(
+            "SELECT * FROM sessions WHERE project_id = ? ORDER BY timestamp DESC",
+            (project_id,),
+        )
+        return [
+            Session(
+                id=row["id"],
+                project_id=row["project_id"],
+                session_type=row["session_type"],
+                timestamp=datetime.fromisoformat(row["timestamp"]),
+                metadata=json.loads(row["metadata"]) if row["metadata"] else {},
+            )
+            for row in rows
+        ]
+
+    def store_protocol(
+        self,
+        session_id: int,
+        name: str,
+        spec_json: dict[str, Any],
+        confidence: float,
+    ) -> int:
+        """Store discovered protocol.
+
+        Args:
+            session_id: Parent session ID
+            name: Protocol name
+            spec_json: Protocol specification
+            confidence: Confidence score (0.0-1.0)
+
+        Returns:
+            Protocol ID
+
+        Example:
+            >>> protocol_id = db.store_protocol(
+            ...     session_id=1,
+            ...     name="IoT Protocol",
+            ...     spec_json={"fields": [...]},
+            ...     confidence=0.85
+            ... )
+        """
+        spec_str = json.dumps(spec_json)
+        cursor = self._execute(
+            "INSERT INTO protocols (session_id, name, spec_json, confidence) VALUES (?, ?, ?, ?)",
+            (session_id, name, spec_str, confidence),
+        )
+        result: int = cursor.lastrowid
+        return result
+
+    def find_protocols(
+        self,
+        name_pattern: str | None = None,
+        min_confidence: float | None = None,
+    ) -> list[Protocol]:
+        """Find protocols by criteria.
+
+        Args:
+            name_pattern: SQL LIKE pattern (e.g., "UDS%")
+            min_confidence: Minimum confidence threshold
+
+        Returns:
+            List of matching protocols
+
+        Example:
+            >>> # Find all UDS protocols with confidence > 0.8
+            >>> protocols = db.find_protocols(name_pattern="UDS%", min_confidence=0.8)
+        """
+        conditions = []
+        params: list[Any] = []
+
+        if name_pattern:
+            conditions.append("name LIKE ?")
+            params.append(name_pattern)
+
+        if min_confidence is not None:
+            conditions.append("confidence >= ?")
+            params.append(min_confidence)
+
+        where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        sql = f"SELECT * FROM protocols {where_clause} ORDER BY confidence DESC"
+
+        rows = self._fetchall(sql, tuple(params))
+        return [
+            Protocol(
+                id=row["id"],
+                session_id=row["session_id"],
+                name=row["name"],
+                spec_json=json.loads(row["spec_json"]),
+                confidence=row["confidence"],
+                created_at=datetime.fromisoformat(row["created_at"]),
+            )
+            for row in rows
+        ]
+
+    def store_message(
+        self,
+        protocol_id: int,
+        timestamp: float,
+        data: bytes,
+        decoded_fields: dict[str, Any] | None = None,
+    ) -> int:
+        """Store decoded message.
+
+        Args:
+            protocol_id: Parent protocol ID
+            timestamp: Message timestamp
+            data: Raw message bytes
+            decoded_fields: Decoded field values
+
+        Returns:
+            Message ID
+
+        Example:
+            >>> msg_id = db.store_message(
+            ...     protocol_id=1,
+            ...     timestamp=1.5,
+            ...     data=b"\\xaa\\x55\\x01",
+            ...     decoded_fields={"id": 1, "counter": 0}
+            ... )
+        """
+        data_hex = data.hex()
+        fields_json = json.dumps(decoded_fields or {})
+        cursor = self._execute(
+            "INSERT INTO messages (protocol_id, timestamp, data, decoded_fields) "
+            "VALUES (?, ?, ?, ?)",
+            (protocol_id, timestamp, data_hex, fields_json),
+        )
+        result: int = cursor.lastrowid
+        return result
+
+    def query_messages(
+        self,
+        protocol_id: int,
+        time_range: tuple[float, float] | None = None,
+        field_filters: dict[str, Any] | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> QueryResult:
+        """Query messages with filtering and pagination.
+
+        Args:
+            protocol_id: Protocol ID
+            time_range: (start_time, end_time) tuple
+            field_filters: Field name -> value filters
+            limit: Maximum results per page
+            offset: Result offset for pagination
+
+        Returns:
+            Paginated query results
+
+        Example:
+            >>> # Get first 10 messages between t=0 and t=10
+            >>> result = db.query_messages(
+            ...     protocol_id=1,
+            ...     time_range=(0.0, 10.0),
+            ...     limit=10
+            ... )
+            >>> print(f"Page {result.page + 1}/{result.total_pages}")
+            >>> for msg in result.items:
+            ...     print(msg.decoded_fields)
+        """
+        conditions = ["protocol_id = ?"]
+        params: list[Any] = [protocol_id]
+
+        if time_range:
+            conditions.append("timestamp >= ? AND timestamp <= ?")
+            params.extend(time_range)
+
+        where_clause = f"WHERE {' AND '.join(conditions)}"
+
+        # Count total
+        count_sql = f"SELECT COUNT(*) as total FROM messages {where_clause}"
+        count_row = self._fetchone(count_sql, tuple(params))
+        total = count_row["total"] if count_row else 0
+
+        # Fetch page
+        sql = f"SELECT * FROM messages {where_clause} ORDER BY timestamp LIMIT ? OFFSET ?"
+        params.extend([limit, offset])
+        rows = self._fetchall(sql, tuple(params))
+
+        messages = [
+            Message(
+                id=row["id"],
+                protocol_id=row["protocol_id"],
+                timestamp=row["timestamp"],
+                data=row["data"],
+                decoded_fields=json.loads(row["decoded_fields"]) if row["decoded_fields"] else {},
+            )
+            for row in rows
+        ]
+
+        # Apply field filters (client-side for SQLite)
+        if field_filters:
+            messages = [
+                msg
+                for msg in messages
+                if all(msg.decoded_fields.get(k) == v for k, v in field_filters.items())
+            ]
+
+        return QueryResult(
+            items=messages,
+            total=total,
+            page=offset // limit,
+            page_size=limit,
+        )
+
+    def store_analysis_result(
+        self,
+        session_id: int,
+        analysis_type: str,
+        results_json: dict[str, Any],
+        metrics: dict[str, Any] | None = None,
+    ) -> int:
+        """Store analysis result.
+
+        Args:
+            session_id: Parent session ID
+            analysis_type: Analysis type (dpa, timing, entropy, etc.)
+            results_json: Analysis results
+            metrics: Computed metrics
+
+        Returns:
+            Result ID
+
+        Example:
+            >>> result_id = db.store_analysis_result(
+            ...     session_id=1,
+            ...     analysis_type="dpa",
+            ...     results_json={"recovered_key": "0x1234..."},
+            ...     metrics={"confidence": 0.95}
+            ... )
+        """
+        results_str = json.dumps(results_json)
+        metrics_str = json.dumps(metrics or {})
+        cursor = self._execute(
+            "INSERT INTO analysis_results (session_id, analysis_type, results_json, metrics) "
+            "VALUES (?, ?, ?, ?)",
+            (session_id, analysis_type, results_str, metrics_str),
+        )
+        result: int = cursor.lastrowid
+        return result
+
+    def get_analysis_results(
+        self, session_id: int, analysis_type: str | None = None
+    ) -> list[AnalysisResult]:
+        """Get analysis results for session.
+
+        Args:
+            session_id: Session ID
+            analysis_type: Filter by analysis type (optional)
+
+        Returns:
+            List of analysis results
+
+        Example:
+            >>> # Get all DPA results
+            >>> results = db.get_analysis_results(session_id=1, analysis_type="dpa")
+            >>> for result in results:
+            ...     print(result.metrics["confidence"])
+        """
+        if analysis_type:
+            sql = (
+                "SELECT * FROM analysis_results "
+                "WHERE session_id = ? AND analysis_type = ? "
+                "ORDER BY created_at DESC"
+            )
+            params: tuple[Any, ...] = (session_id, analysis_type)
+        else:
+            sql = "SELECT * FROM analysis_results WHERE session_id = ? ORDER BY created_at DESC"
+            params = (session_id,)
+
+        rows = self._fetchall(sql, params)
+        return [
+            AnalysisResult(
+                id=row["id"],
+                session_id=row["session_id"],
+                analysis_type=row["analysis_type"],
+                results_json=json.loads(row["results_json"]),
+                metrics=json.loads(row["metrics"]) if row["metrics"] else {},
+                created_at=datetime.fromisoformat(row["created_at"]),
+            )
+            for row in rows
+        ]
+
+    def export_to_sql(self, output_path: str | Path) -> None:
+        """Export database to SQL dump.
+
+        Args:
+            output_path: Output SQL file path
+
+        Example:
+            >>> db.export_to_sql("backup.sql")
+        """
+        output_path = Path(output_path)
+
+        if self._is_postgres:
+            raise NotImplementedError("PostgreSQL export via pg_dump recommended")
+
+        # SQLite dump
+        with open(output_path, "w") as f:
+            for line in self._conn.iterdump():
+                f.write(f"{line}\n")
+
+    def export_to_json(self, output_path: str | Path, project_id: int | None = None) -> None:
+        """Export database contents to JSON.
+
+        Args:
+            output_path: Output JSON file path
+            project_id: Export specific project (optional)
+
+        Example:
+            >>> db.export_to_json("export.json", project_id=1)
+        """
+        output_path = Path(output_path)
+
+        projects_list: list[Project | None]
+        if project_id:
+            projects_list = [self.get_project(project_id)]
+        else:
+            projects_list = list(self.list_projects())
+
+        export_data = []
+        for proj in projects_list:
+            if proj is None:
+                continue
+
+            proj_data = asdict(proj)
+            proj_data["sessions"] = []
+
+            sessions = self.get_sessions(proj.id)  # type: ignore[arg-type]
+            for sess in sessions:
+                sess_data = asdict(sess)
+                sess_data["protocols"] = []
+                sess_data["analysis_results"] = []
+
+                # Get protocols
+                protocols = self.find_protocols()
+                for prot in protocols:
+                    if prot.session_id == sess.id:
+                        prot_data = asdict(prot)
+                        # Get messages
+                        msgs = self.query_messages(prot.id, limit=1000)  # type: ignore[arg-type]
+                        prot_data["messages"] = [asdict(msg) for msg in msgs.items]
+                        sess_data["protocols"].append(prot_data)
+
+                # Get analysis results
+                results = self.get_analysis_results(sess.id)  # type: ignore[arg-type]
+                sess_data["analysis_results"] = [asdict(r) for r in results]
+
+                proj_data["sessions"].append(sess_data)
+
+            export_data.append(proj_data)
+
+        with open(output_path, "w") as f:
+            json.dump(export_data, f, indent=2, default=str)
+
+    def export_to_csv(self, output_dir: str | Path, project_id: int | None = None) -> None:
+        """Export database to CSV files.
+
+        Args:
+            output_dir: Output directory for CSV files
+            project_id: Export specific project (optional)
+
+        Example:
+            >>> db.export_to_csv("csv_export/", project_id=1)
+        """
+        import csv
+
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        projects_list: list[Project | None]
+        if project_id:
+            projects_list = [self.get_project(project_id)]
+        else:
+            projects_list = list(self.list_projects())
+
+        # Export projects
+        with open(output_dir / "projects.csv", "w", newline="") as f:
+            writer = csv.DictWriter(
+                f, fieldnames=["id", "name", "description", "created_at", "updated_at"]
+            )
+            writer.writeheader()
+            for proj in projects_list:
+                if proj:
+                    writer.writerow(
+                        {
+                            "id": proj.id,
+                            "name": proj.name,
+                            "description": proj.description,
+                            "created_at": proj.created_at,
+                            "updated_at": proj.updated_at,
+                        }
+                    )
+
+        # Export sessions
+        all_sessions = []
+        for proj in projects_list:
+            if proj:
+                all_sessions.extend(self.get_sessions(proj.id))  # type: ignore[arg-type]
+
+        with open(output_dir / "sessions.csv", "w", newline="") as f:
+            writer = csv.DictWriter(f, fieldnames=["id", "project_id", "session_type", "timestamp"])
+            writer.writeheader()
+            for sess in all_sessions:
+                writer.writerow(
+                    {
+                        "id": sess.id,
+                        "project_id": sess.project_id,
+                        "session_type": sess.session_type,
+                        "timestamp": sess.timestamp,
+                    }
+                )
+
+        # Export protocols
+        all_protocols = self.find_protocols()
+        with open(output_dir / "protocols.csv", "w", newline="") as f:
+            writer = csv.DictWriter(
+                f, fieldnames=["id", "session_id", "name", "confidence", "created_at"]
+            )
+            writer.writeheader()
+            for prot in all_protocols:
+                writer.writerow(
+                    {
+                        "id": prot.id,
+                        "session_id": prot.session_id,
+                        "name": prot.name,
+                        "confidence": prot.confidence,
+                        "created_at": prot.created_at,
+                    }
+                )
+
+    def close(self) -> None:
+        """Close database connection/pool.
+
+        Example:
+            >>> db.close()
+        """
+        if self._is_postgres and self._pool:
+            self._pool.closeall()
+        elif self._conn:
+            self._conn.close()
+
+    def __enter__(self) -> DatabaseBackend:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.close()