hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/builtin/adapters/database/sqlalchemy/sqlalchemy_adapter.py

@@ -0,0 +1,252 @@
+# type: ignore
+"""SQLAlchemy adapter implementation for hexDAG."""
+
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+from sqlalchemy import MetaData, Table, inspect, select, text
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from hexdag.core.ports.database import (
+    ColumnSchema,
+    DatabasePort,
+    SupportsIndexes,
+    SupportsRawSQL,
+    SupportsStatistics,
+    TableSchema,
+)
+
+
+class SQLAlchemyAdapter(DatabasePort, SupportsRawSQL, SupportsIndexes, SupportsStatistics):
+    """Adapter for SQLAlchemy-supported databases."""
+
+    def __init__(self, dsn: str) -> None:
+        """
+        Initialize SQLAlchemy adapter.
+
+        Args:
+            dsn: Database connection string (e.g., postgresql+asyncpg://user:pass@localhost/db)
+        """
+        self.engine: AsyncEngine | None = None
+        self.dsn = dsn
+        self._metadata = MetaData()
+
+    async def connect(self) -> None:
+        """Establish database connection."""
+        self.engine = create_async_engine(self.dsn)
+        async with self.engine.connect() as conn:
+            # Force reflection after any schema changes
+            await conn.run_sync(self._metadata.reflect)
+
+    async def disconnect(self) -> None:
+        """Close database connection."""
+        if self.engine:
+            await self.engine.dispose()
+            self.engine = None
+
+    async def aget_table_schemas(self) -> dict[str, dict[str, Any]]:
+        """
+        Get schema information for all tables in DatabasePort format.
+
+        Returns:
+            Dictionary mapping table names to schema information.
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        schemas = {}
+        for table_name, table in self._metadata.tables.items():
+            columns = {}
+            primary_keys = []
+            foreign_keys = []
+
+            for col in table.columns:
+                columns[col.name] = str(col.type)
+
+                if col.primary_key:
+                    primary_keys.append(col.name)
+
+                if col.foreign_keys:
+                    fk = next(iter(col.foreign_keys))
+                    foreign_keys.append({
+                        "from_column": col.name,
+                        "to_table": fk.column.table.name,
+                        "to_column": fk.column.name,
+                    })
+
+            schemas[table_name] = {
+                "table_name": table_name,
+                "columns": columns,
+                "primary_keys": primary_keys,
+                "foreign_keys": foreign_keys,
+            }
+
+        return schemas
+
+    async def aexecute_query(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        """Execute a SQL query and return results.
+
+        Args:
+            query: SQL query string
+            params: Optional query parameters for safe parameterized queries
+
+        Returns:
+            List of dictionaries representing query result rows
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        results = []
+        async with self.engine.connect() as conn:
+            result = await conn.execute(text(query), params or {})
+            results.extend(dict(row._mapping) for row in result)
+        return results
+
+    async def get_table_schemas(self) -> Sequence[TableSchema]:
+        """
+        Get schema information for all tables.
+
+        Returns:
+            Sequence[TableSchema]: List of table schemas
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        schemas = []
+        for table_name, table in self._metadata.tables.items():
+            columns = []
+            for col in table.columns:
+                foreign_key = None
+                if col.foreign_keys:
+                    fk = next(iter(col.foreign_keys))
+                    foreign_key = f"{fk.column.table.name}.{fk.column.name}"
+
+                nullable = bool(col.nullable) if col.nullable is not None else False
+
+                columns.append(
+                    ColumnSchema(
+                        name=col.name,
+                        type=col.type.value,
+                        nullable=nullable,
+                        primary_key=col.primary_key,
+                        foreign_key=foreign_key,
+                    )
+                )
+            schemas.append(TableSchema(name=table_name, columns=columns))
+
+        return schemas
+
+    def query(
+        self,
+        table: str,
+        filters: dict[str, Any] | None = None,
+        columns: list[str] | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """
+        Query rows from a table with filtering and column selection.
+
+        Args:
+            table: Table name
+            filters: Optional column-value pairs to filter by
+            columns: Optional list of columns to return (None = all)
+            limit: Optional maximum number of rows to return
+        Returns:
+            AsyncIterator[dict[str, Any]]: An async iterator over rows as dictionaries
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        table_obj = Table(table, self._metadata, extend_existing=True)
+        query = select(table_obj)
+
+        if columns:
+            query = select(*[table_obj.c[col] for col in columns])
+
+        if filters:
+            conditions = [table_obj.c[k] == v for k, v in filters.items()]
+            query = query.where(*conditions)
+
+        if limit:
+            query = query.limit(limit)
+
+        async def generate_rows() -> AsyncIterator[dict[str, Any]]:
+            if not self.engine:  # Recheck engine in case it was closed
+                raise RuntimeError("Database connection lost")
+            async with self.engine.connect() as conn:
+                result = await conn.stream(query)
+                async for row in result:
+                    yield dict(row._mapping)
+
+        return generate_rows()
+
+    def query_raw(
+        self, sql: str, params: dict[str, Any] | None = None
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Execute a raw SQL query."""
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        async def generate_rows() -> AsyncIterator[dict[str, Any]]:
+            if not self.engine:
+                raise RuntimeError("Database connection lost")
+            async with self.engine.connect() as conn:
+                result = await conn.stream(text(sql), params or {})
+                async for row in result:
+                    yield dict(row._mapping)
+
+        return generate_rows()
+
+    async def execute_raw(self, sql: str, params: dict[str, Any] | None = None) -> None:
+        """
+        Execute a raw SQL statement without returning results.
+
+        Args:
+            sql: SQL statement to execute
+            params: Optional parameters for the SQL statement
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        async with self.engine.connect() as conn:
+            await conn.execute(text(sql), params or {})
+            await conn.commit()
+
+    async def get_indexes(self, table: str) -> list[str]:
+        """
+        Get index information for a table.
+
+        Args:
+            table: Table name
+
+        Returns:
+            list[str]: List of index names
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        async with self.engine.connect() as conn:
+            # Remove engine argument from inspect call
+            inspector = await conn.run_sync(inspect)
+            # Filter out None values to ensure list[str]
+            return [idx["name"] for idx in inspector.get_indexes(table) if idx["name"] is not None]
+
+    async def get_table_statistics(self, table: str) -> dict[str, int]:
+        """
+        Get statistical information about a table.
+
+        Args:
+            table: Table name
+
+        Returns:
+            dict[str, int]: Statistics including row count
+        """
+        if not self.engine:
+            raise RuntimeError("Not connected to database")
+
+        async with self.engine.connect() as conn:
+            result = await conn.execute(text(f"SELECT COUNT(*) as count FROM {table}"))  # nosec
+            row = await result.fetchone()  # type: ignore # type: ignore
+            return {"row_count": int(row[0]) if row else 0}

hexdag/builtin/adapters/database/sqlite/__init__.py

@@ -0,0 +1,5 @@
+"""SQLite adapter for hexDAG."""
+
+from hexdag.builtin.adapters.database.sqlite.sqlite_adapter import SQLiteAdapter
+
+__all__ = ["SQLiteAdapter"]

hexdag/builtin/adapters/database/sqlite/sqlite_adapter.py

@@ -0,0 +1,410 @@
+"""SQLite database adapter implementation with async support."""
+
+import re
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+from hexdag.core.logging import get_logger
+from hexdag.core.utils.sql_validation import validate_sql_identifier
+
+logger = get_logger(__name__)
+
+
+class SQLiteAdapter:
+    """Async SQLite adapter for database port.
+
+    Provides a lightweight, file-based database solution that implements
+    the DatabasePort interface for SQL execution and schema introspection.
+    All operations are fully async using aiosqlite.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize SQLite adapter.
+
+        Args
+        ----
+            **kwargs: Configuration options (db_path, timeout, etc.)
+        """
+        db_path = kwargs.get("db_path", ":memory:")
+        self.db_path = Path(db_path) if db_path != ":memory:" else db_path
+        self.check_same_thread = kwargs.get("check_same_thread", False)
+        self.timeout = kwargs.get("timeout", 5.0)
+        self.journal_mode = kwargs.get("journal_mode", "WAL")
+        self.foreign_keys = kwargs.get("foreign_keys", True)
+        self.read_only = kwargs.get("read_only", False)
+
+        self.connection: aiosqlite.Connection | None = None
+
+    async def _ensure_database(self) -> None:
+        """Ensure database connection exists and is configured."""
+        if self.connection is not None:
+            return
+
+        db_path = str(self.db_path) if isinstance(self.db_path, Path) else self.db_path
+
+        if self.read_only and db_path != ":memory:":
+            # Use URI mode for read-only access
+            db_uri = f"file:{db_path}?mode=ro"
+            self.connection = await aiosqlite.connect(
+                db_uri,
+                uri=True,
+                check_same_thread=self.check_same_thread,
+                timeout=self.timeout,
+            )
+        else:
+            self.connection = await aiosqlite.connect(
+                db_path,
+                check_same_thread=self.check_same_thread,
+                timeout=self.timeout,
+            )
+
+        self.connection.row_factory = aiosqlite.Row  # Return rows as dictionaries
+
+        # Configure database settings
+        if self.connection:
+            async with self.connection.cursor() as cursor:
+                if self.journal_mode:
+                    await cursor.execute(f"PRAGMA journal_mode = {self.journal_mode}")
+                if self.foreign_keys:
+                    await cursor.execute("PRAGMA foreign_keys = ON")
+            await self.connection.commit()
+
+    @asynccontextmanager
+    async def _get_cursor(self) -> AsyncIterator[aiosqlite.Cursor]:
+        """Context manager for database cursor.
+
+        Ensures proper cursor cleanup and error handling.
+
+        Yields
+        ------
+        aiosqlite.Cursor
+            Async SQLite database cursor
+
+        Raises
+        ------
+        RuntimeError
+            If database connection is not established
+        aiosqlite.Error
+            If database error occurs during operation
+        """
+        await self._ensure_database()
+        if self.connection is None:
+            raise RuntimeError("Database connection not established")
+
+        async with self.connection.cursor() as cursor:
+            try:
+                yield cursor
+            except aiosqlite.Error as e:
+                logger.error(f"Database error: {e}")
+                await self.connection.rollback()
+                raise
+
+    async def _get_all_tables(self) -> list[str]:
+        """Get all non-system tables from the database.
+
+        Returns
+        -------
+            List of table names
+        """
+        async with self._get_cursor() as cursor:
+            await cursor.execute(
+                """
+                SELECT name FROM sqlite_master
+                WHERE type='table' AND name NOT LIKE 'sqlite_%'
+            """
+            )
+            rows = await cursor.fetchall()
+            return [row[0] for row in rows]
+
+    def _validate_identifier(self, identifier: str, identifier_type: str = "table") -> bool:
+        """Validate a database identifier to prevent injection.
+
+        Parameters
+        ----------
+        identifier : str
+            The identifier to validate (table name, column name, etc.)
+        identifier_type : str
+            Type of identifier for error messages
+
+        Returns
+        -------
+        bool
+            True if valid, False otherwise
+        """
+        return validate_sql_identifier(identifier, identifier_type=identifier_type)
+
+    async def aget_table_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schema information for all tables.
+
+        Returns
+        -------
+            Dictionary mapping table names to schema information
+        """
+        tables = await self._get_all_tables()
+        schemas = {}
+
+        async with self._get_cursor() as cursor:
+            for table in tables:
+                if not self._validate_identifier(table):
+                    continue
+
+                await cursor.execute(f'PRAGMA table_info("{table}")')  # nosec B608 - validated
+                rows = await cursor.fetchall()
+
+                columns = {}
+                primary_keys = []
+                for row in rows:
+                    col_name = row[1]
+                    col_type = row[2]
+                    is_pk = row[5]
+
+                    columns[col_name] = col_type
+                    if is_pk:
+                        primary_keys.append(col_name)
+
+                # nosec B608 - validated
+                await cursor.execute(f'PRAGMA foreign_key_list("{table}")')
+                fk_rows = await cursor.fetchall()
+                foreign_keys = [
+                    {
+                        "from_column": fk_row[3],
+                        "to_table": fk_row[2],
+                        "to_column": fk_row[4],
+                    }
+                    for fk_row in fk_rows
+                ]
+
+                schemas[table] = {
+                    "table_name": table,
+                    "columns": columns,
+                    "primary_keys": primary_keys,
+                    "foreign_keys": foreign_keys,
+                }
+
+        return schemas
+
+    async def aexecute_query(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        """Execute a SQL query and return results.
+
+        Args
+        ----
+            query: SQL query to execute
+            params: Optional query parameters for safe parameterized queries
+
+        Returns
+        -------
+            List of dictionaries representing query result rows.
+            For non-SELECT queries (INSERT/UPDATE/DELETE), returns an empty list
+            and commits the transaction.
+
+        Notes
+        -----
+        - SELECT/PRAGMA/WITH queries return result rows
+        - INSERT/UPDATE/DELETE queries are committed automatically and return []
+        - Use parameters to prevent SQL injection with :name placeholders
+
+        Raises
+        ------
+        ValueError
+            If a required parameter is missing
+        aiosqlite.Error
+            If query execution fails
+        """
+        try:
+            async with self._get_cursor() as cursor:
+                if params:
+                    # SQLite uses ? placeholders, but we support :name format
+                    param_names = []
+
+                    def replacer(match: re.Match[str]) -> str:
+                        param_names.append(match.group(1))
+                        return "?"
+
+                    converted_query = re.sub(r":(\w+)", replacer, query)
+
+                    try:
+                        param_values = [params[name] for name in param_names]
+                        await cursor.execute(converted_query, param_values)
+                    except KeyError as e:
+                        raise ValueError(f"Missing parameter: {e}") from e
+                else:
+                    await cursor.execute(query)
+
+                # Determine query type
+                query_type = query.strip().upper().split()[0] if query.strip() else ""
+
+                # For SELECT queries, fetch results
+                if query_type in ("SELECT", "PRAGMA", "WITH"):
+                    rows = await cursor.fetchall()
+                    return [dict(row) for row in rows]
+                # For INSERT/UPDATE/DELETE operations
+                # Note: If database is opened in read-only mode, SQLite will
+                # automatically raise an OperationalError for write operations
+                affected_rows = cursor.rowcount
+                if self.connection is not None:
+                    await self.connection.commit()
+
+                # Log the operation
+                logger.info(f"Executed {query_type} query, affected rows: {affected_rows}")
+                return []
+        except aiosqlite.Error as e:
+            logger.error(f"Query execution failed: {e}")
+            logger.error(f"Query: {query[:100]}...")  # Log first 100 chars of query
+            raise
+
+    async def aget_relationships(self) -> list[dict[str, Any]]:
+        """Get foreign key relationships between tables.
+
+        Returns
+        -------
+            List of relationship dictionaries
+        """
+        tables = await self._get_all_tables()
+        relationships: list[dict[str, Any]] = []
+
+        async with self._get_cursor() as cursor:
+            for table in tables:
+                if not self._validate_identifier(table):
+                    continue
+
+                # nosec B608 - validated
+                await cursor.execute(f'PRAGMA foreign_key_list("{table}")')
+                fk_rows = await cursor.fetchall()
+
+                relationships.extend(
+                    {
+                        "from_table": table,
+                        "from_column": fk_row[3],
+                        "to_table": fk_row[2],
+                        "to_column": fk_row[4],
+                        "relationship_type": "many_to_one",  # SQLite doesn't store this info
+                    }
+                    for fk_row in fk_rows
+                )
+
+        return relationships
+
+    async def aget_indexes(self) -> list[dict[str, Any]]:
+        """Get index information for performance optimization.
+
+        Returns
+        -------
+            List of index dictionaries
+        """
+        indexes = []
+
+        async with self._get_cursor() as cursor:
+            await cursor.execute(
+                """
+                SELECT name, tbl_name, sql FROM sqlite_master
+                WHERE type='index' AND sql IS NOT NULL
+            """
+            )
+            index_rows = await cursor.fetchall()
+
+            for row in index_rows:
+                index_name = row[0]
+                table_name = row[1]
+
+                if not self._validate_identifier(index_name, "index"):
+                    continue
+                if not self._validate_identifier(table_name, "table"):
+                    continue
+
+                await cursor.execute(f'PRAGMA index_info("{index_name}")')  # nosec B608 - validated
+                col_rows = await cursor.fetchall()
+                columns = [col_row[2] for col_row in col_rows]
+
+                await cursor.execute(f'PRAGMA index_list("{table_name}")')  # nosec B608 - validated
+                idx_list = await cursor.fetchall()
+                is_unique = False
+                for idx in idx_list:
+                    if idx[1] == index_name:
+                        is_unique = bool(idx[2])
+                        break
+
+                indexes.append({
+                    "index_name": index_name,
+                    "table_name": table_name,
+                    "columns": columns,
+                    "index_type": "btree",  # SQLite primarily uses B-tree
+                    "is_unique": is_unique,
+                })
+
+        return indexes
+
+    async def aget_table_statistics(self) -> dict[str, dict[str, Any]]:
+        """Get table statistics for query optimization.
+
+        Returns
+        -------
+            Dictionary mapping table names to statistics
+        """
+        tables = await self._get_all_tables()
+        stats = {}
+
+        async with self._get_cursor() as cursor:
+            for table in tables:
+                if not self._validate_identifier(table):
+                    continue  # Skip invalid table names
+
+                # SQLite uses double quotes for identifiers
+                await cursor.execute(f'SELECT COUNT(*) FROM "{table}"')  # nosec B608 - validated
+                result = await cursor.fetchone()
+                row_count = result[0] if result else 0
+
+                await cursor.execute(
+                    "SELECT SUM(LENGTH(sql)) FROM sqlite_master WHERE tbl_name = ?",
+                    (table,),
+                )
+                size_result = await cursor.fetchone()
+                size_bytes = size_result[0] if size_result and size_result[0] else 0
+
+                stats[table] = {
+                    "row_count": row_count,
+                    "size_bytes": size_bytes,
+                    "last_updated": None,  # SQLite doesn't track this
+                }
+
+        return stats
+
+    async def close(self) -> None:
+        """Close database connection."""
+        if self.connection:
+            await self.connection.close()
+            self.connection = None
+
+    async def __aenter__(self) -> "SQLiteAdapter":
+        """Async context manager entry."""
+        await self._ensure_database()
+        return self
+
+    async def __aexit__(
+        self,
+        _exc_type: Any,  # noqa: ARG002
+        _exc_val: Any,  # noqa: ARG002
+        _exc_tb: Any,  # noqa: ARG002
+    ) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    def __repr__(self) -> str:
+        """Return string representation."""
+        mode = "read-only" if self.read_only else "read-write"
+        return f"SQLiteAdapter(db_path='{self.db_path}', mode='{mode}')"
+
+    # SupportsReadOnly protocol method
+    async def is_read_only(self) -> bool:
+        """Check if the adapter is in read-only mode.
+
+        Returns
+        -------
+            True if adapter is read-only, False otherwise
+        """
+        return bool(self.read_only)