sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/driver/_async.py

@@ -0,0 +1,1830 @@
+"""Asynchronous driver protocol implementation."""
+
+from abc import abstractmethod
+from time import perf_counter
+from typing import TYPE_CHECKING, Any, ClassVar, Final, cast, final, overload
+
+from mypy_extensions import mypyc_attr
+
+from sqlspec.core import SQL, ProcessedState, StackResult, Statement, create_arrow_result
+from sqlspec.core.result import DMLResult
+from sqlspec.core.stack import StackOperation, StatementStack
+from sqlspec.driver._common import (
+    AsyncExceptionHandler,
+    CommonDriverAttributesMixin,
+    DataDictionaryDialectMixin,
+    DataDictionaryMixin,
+    ExecutionResult,
+    StackExecutionObserver,
+    _raise_database_exception,
+    describe_stack_statement,
+    handle_single_row_error,
+)
+from sqlspec.driver._query_cache import CachedQuery
+from sqlspec.driver._sql_helpers import DEFAULT_PRETTY
+from sqlspec.driver._sql_helpers import convert_to_dialect as _convert_to_dialect_impl
+from sqlspec.driver._storage_helpers import stringify_storage_target
+from sqlspec.exceptions import ImproperConfigurationError, StackExecutionError
+from sqlspec.storage import AsyncStoragePipeline, StorageBridgeJob, StorageDestination, StorageFormat, StorageTelemetry
+from sqlspec.utils.arrow_helpers import convert_dict_to_arrow_with_schema
+from sqlspec.utils.logging import get_logger
+from sqlspec.utils.schema import ValueT, to_value_type
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Sequence
+
+    from sqlglot.dialects.dialect import DialectType
+
+    from sqlspec.builder import QueryBuilder
+    from sqlspec.core import ArrowResult, SQLResult, StatementConfig, StatementFilter
+    from sqlspec.typing import (
+        ArrowReturnFormat,
+        ArrowTable,
+        ColumnMetadata,
+        ForeignKeyMetadata,
+        IndexMetadata,
+        SchemaT,
+        StatementParameters,
+        TableMetadata,
+        VersionInfo,
+    )
+
+
+__all__ = ("AsyncDataDictionaryBase", "AsyncDriverAdapterBase", "AsyncPoolConnectionContext", "AsyncPoolSessionFactory")
+
+
+EMPTY_FILTERS: Final["list[StatementFilter]"] = []
+_LOGGER_NAME: Final[str] = "sqlspec.driver"
+logger = get_logger(_LOGGER_NAME)
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class AsyncPoolConnectionContext:
+    """Base async connection context using pool acquire/release pattern.
+
+    Subclass per adapter and override ``__aenter__``/``__aexit__`` for
+    adapter-specific pool acquisition and release logic.
+    """
+
+    __slots__ = ("_config", "_connection")
+
+    def __init__(self, config: Any) -> None:
+        self._config = config
+        self._connection: Any = None
+
+    async def __aenter__(self) -> Any:
+        pool = self._config.connection_instance
+        if pool is None:
+            pool = await self._config.create_pool()
+            self._config.connection_instance = pool
+        self._connection = await pool.acquire()
+        return self._connection
+
+    async def __aexit__(
+        self, exc_type: "type[BaseException] | None", exc_val: "BaseException | None", exc_tb: Any
+    ) -> "bool | None":
+        if self._connection is not None:
+            if self._config.connection_instance:
+                await self._config.connection_instance.release(self._connection)
+            self._connection = None
+        return None
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class AsyncPoolSessionFactory:
+    """Base async session factory using pool acquire/release pattern.
+
+    Subclass per adapter and override ``acquire_connection``/``release_connection``
+    for adapter-specific pool acquisition and release logic.
+    """
+
+    __slots__ = ("_config", "_connection")
+
+    def __init__(self, config: Any) -> None:
+        self._config = config
+        self._connection: Any = None
+
+    async def acquire_connection(self) -> Any:
+        pool = self._config.connection_instance
+        if pool is None:
+            pool = await self._config.create_pool()
+            self._config.connection_instance = pool
+        self._connection = await pool.acquire()
+        return self._connection
+
+    async def release_connection(self, _conn: Any, **kwargs: Any) -> None:
+        if self._connection is not None and self._config.connection_instance is not None:
+            await self._config.connection_instance.release(self._connection)
+            self._connection = None
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class AsyncDriverAdapterBase(CommonDriverAttributesMixin):
+    """Base class for asynchronous database drivers.
+
+    This class includes flattened storage and SQL translation methods that were
+    previously in StorageDriverMixin and SQLTranslatorMixin. The flattening
+    eliminates cross-trait attribute access that caused mypyc segmentation faults.
+
+    Method Organization:
+        1. Core dispatch methods (the execution engine)
+        2. Transaction management (abstract methods)
+        3. Public API - execution methods
+        4. Public API - query methods (select/fetch variants)
+        5. Arrow API methods
+        6. Stack execution
+        7. Storage API methods
+        8. Utility methods
+        9. Private/internal methods
+
+    """
+
+    __slots__ = ()
+
+    dialect: "DialectType | None" = None
+
+    @property
+    def is_async(self) -> bool:
+        """Return whether the driver executes asynchronously.
+
+        Returns:
+            True for async drivers.
+
+        """
+        return True
+
+    @property
+    @abstractmethod
+    def data_dictionary(self) -> "AsyncDataDictionaryBase":
+        """Get the data dictionary for this driver.
+
+        Returns:
+            Data dictionary instance for metadata queries
+
+        """
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # CORE DISPATCH METHODS - The Execution Engine
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _check_pending_exception(exc_handler: AsyncExceptionHandler) -> None:
+        """Raise any pending mapped exception after context manager exit."""
+        if exc_handler.pending_exception is not None:
+            raise exc_handler.pending_exception from None
+
+    @final
+    async def dispatch_statement_execution(self, statement: "SQL", connection: "Any") -> "SQLResult":
+        """Central execution dispatcher using the Template Method Pattern.
+
+        Args:
+            statement: The SQL statement to execute
+            connection: The database connection to use
+
+        Returns:
+            The result of the SQL execution
+
+        """
+        try:
+            runtime = self._observability
+            compiled_sql, execution_parameters = statement.compile()
+            _ = cast("ProcessedState", statement.get_processed_state())
+            result: SQLResult | None = None
+
+            # FAST PATH: Skip all instrumentation if runtime is absent or idle.
+            if runtime is None or runtime.is_idle:
+                exc_handler = self.handle_database_exceptions()
+                async with exc_handler, self.with_cursor(connection) as cursor:
+                    special_result = await self.dispatch_special_handling(cursor, statement)
+                    if special_result is not None:
+                        result = special_result
+                    elif statement.is_script:
+                        execution_result = await self.dispatch_execute_script(cursor, statement)
+                        result = self.build_statement_result(statement, execution_result)
+                    elif statement.is_many:
+                        execution_result = await self.dispatch_execute_many(cursor, statement)
+                        result = self.build_statement_result(statement, execution_result)
+                    else:
+                        execution_result = await self.dispatch_execute(cursor, statement)
+                        result = self.build_statement_result(statement, execution_result)
+                self._check_pending_exception(exc_handler)
+                assert result is not None
+                return result
+
+            operation = statement.operation_type
+            query_context = {
+                "sql": compiled_sql,
+                "parameters": execution_parameters,
+                "driver": type(self).__name__,
+                "operation": operation,
+                "is_many": statement.is_many,
+                "is_script": statement.is_script,
+            }
+            runtime.emit_query_start(**query_context)
+            span = runtime.start_query_span(compiled_sql, operation, type(self).__name__)
+            started = perf_counter()
+
+            exc_handler = self.handle_database_exceptions()
+            try:
+                async with exc_handler, self.with_cursor(connection) as cursor:
+                    special_result = await self.dispatch_special_handling(cursor, statement)
+                    if special_result is not None:
+                        result = special_result
+                    elif statement.is_script:
+                        execution_result = await self.dispatch_execute_script(cursor, statement)
+                        result = self.build_statement_result(statement, execution_result)
+                    elif statement.is_many:
+                        execution_result = await self.dispatch_execute_many(cursor, statement)
+                        result = self.build_statement_result(statement, execution_result)
+                    else:
+                        execution_result = await self.dispatch_execute(cursor, statement)
+                        result = self.build_statement_result(statement, execution_result)
+            except Exception as exc:  # pragma: no cover - instrumentation path
+                pending_exception = exc_handler.pending_exception
+                if pending_exception is not None:
+                    mapped_exc = pending_exception
+                    runtime.span_manager.end_span(span, error=mapped_exc)
+                    runtime.emit_error(mapped_exc, **query_context)
+                    _raise_database_exception(exc_handler, exc)
+                runtime.span_manager.end_span(span, error=exc)
+                runtime.emit_error(exc, **query_context)
+                _raise_database_exception(exc_handler, exc)
+
+            pending_exception = exc_handler.pending_exception
+            if pending_exception is not None:
+                mapped_exc = pending_exception
+                runtime.span_manager.end_span(span, error=mapped_exc)
+                runtime.emit_error(mapped_exc, **query_context)
+                _raise_database_exception(exc_handler, None)
+
+            assert result is not None  # Guaranteed: no exception means result was assigned
+
+            runtime.span_manager.end_span(span)
+            duration = perf_counter() - started
+            runtime.emit_query_complete(**{**query_context, "rows_affected": result.rows_affected})
+            runtime.emit_statement_event(
+                sql=compiled_sql,
+                parameters=execution_parameters,
+                driver=type(self).__name__,
+                operation=operation,
+                execution_mode=self.statement_config.execution_mode,
+                is_many=statement.is_many,
+                is_script=statement.is_script,
+                rows_affected=result.rows_affected,
+                duration_s=duration,
+                storage_backend=(result.metadata or {}).get("storage_backend"),
+                started_at=started,
+            )
+            return result
+        finally:
+            self._release_pooled_statement(statement)
+
+    @abstractmethod
+    async def dispatch_execute(self, cursor: Any, statement: "SQL") -> ExecutionResult:
+        """Execute a single SQL statement.
+
+        Must be implemented by each driver for database-specific execution logic.
+
+        Args:
+            cursor: Database cursor/connection object
+            statement: SQL statement object with all necessary data and configuration
+
+        Returns:
+            ExecutionResult with execution data
+
+        """
+
+    @abstractmethod
+    async def dispatch_execute_many(self, cursor: Any, statement: "SQL") -> ExecutionResult:
+        """Execute SQL with multiple parameter sets (executemany).
+
+        Must be implemented by each driver for database-specific executemany logic.
+
+        Args:
+            cursor: Database cursor/connection object
+            statement: SQL statement object with all necessary data and configuration
+
+        Returns:
+            ExecutionResult with execution data for the many operation
+
+        """
+
+    async def dispatch_execute_script(self, cursor: Any, statement: "SQL") -> ExecutionResult:
+        """Execute a SQL script containing multiple statements.
+
+        Default implementation splits the script and executes statements individually.
+        Drivers can override for database-specific script execution methods.
+
+        Args:
+            cursor: Database cursor/connection object
+            statement: SQL statement object with all necessary data and configuration
+
+        Returns:
+            ExecutionResult with script execution data including statement counts
+
+        """
+        sql, prepared_parameters = self._get_compiled_sql(statement, self.statement_config)
+        statements = self.split_script_statements(sql, self.statement_config, strip_trailing_semicolon=True)
+
+        statement_count: int = len(statements)
+        successful_count: int = 0
+
+        for stmt in statements:
+            single_stmt = statement.copy(statement=stmt, parameters=prepared_parameters)
+            await self.dispatch_execute(cursor, single_stmt)
+            successful_count += 1
+
+        return self.create_execution_result(
+            cursor, statement_count=statement_count, successful_statements=successful_count, is_script_result=True
+        )
+
+    async def dispatch_special_handling(self, cursor: Any, statement: "SQL") -> "SQLResult | None":
+        """Hook for database-specific special operations (e.g., PostgreSQL COPY, bulk operations).
+
+        This method is called first in dispatch_statement_execution() to allow drivers to handle
+        special operations that don't follow the standard SQL execution pattern.
+
+        Args:
+            cursor: Database cursor/connection object
+            statement: SQL statement to analyze
+
+        Returns:
+            SQLResult if the special operation was handled and completed,
+            None if standard execution should proceed
+
+        """
+        _ = (cursor, statement)
+        return None
+
+    def collect_rows(self, cursor: Any, fetched: "list[Any]") -> "tuple[list[Any], list[str], int]":
+        """Collect rows from cursor after fetchall for the direct execution path.
+
+        Adapters should override this method to provide optimized row collection
+        that bypasses full dispatch_execute overhead.
+
+        Args:
+            cursor: Database cursor with description metadata.
+            fetched: Rows returned from cursor.fetchall().
+
+        Returns:
+            Tuple of (data, column_names, row_count).
+
+        Raises:
+            NotImplementedError: If the adapter does not implement this method.
+
+        """
+        msg = "Adapter must implement collect_rows() for direct execution path"
+        raise NotImplementedError(msg)
+
+    def resolve_rowcount(self, cursor: Any) -> int:
+        """Resolve the number of affected rows from cursor for the direct execution path.
+
+        Adapters should override this method to provide optimized rowcount resolution
+        that bypasses full dispatch_execute overhead.
+
+        Args:
+            cursor: Database cursor with rowcount metadata.
+
+        Returns:
+            Number of affected rows, or 0 when unknown.
+
+        Raises:
+            NotImplementedError: If the adapter does not implement this method.
+
+        """
+        msg = "Adapter must implement resolve_rowcount() for direct execution path"
+        raise NotImplementedError(msg)
+
+    async def _stmt_cache_execute_direct(
+        self, sql: str, params: "tuple[Any, ...] | list[Any]", cached: CachedQuery
+    ) -> "SQLResult":
+        """Execute pre-compiled query via ultra-fast path (async).
+
+        Uses _stmt_cache_build_direct + dispatch_execute since async drivers can't
+        call cursor.execute directly. For DML operations, returns DMLResult
+        to bypass full SQLResult construction.
+
+        Args:
+            sql: Raw SQL string (original, not compiled).
+            params: Query parameters.
+            cached: Cached query metadata.
+
+        Returns:
+            SQLResult or DMLResult.
+        """
+        compiled_sql = cached.compiled_sql
+        direct_statement = self._stmt_cache_build_direct(
+            sql, params, cached, params, params_are_simple=True, compiled_sql=compiled_sql
+        )
+
+        exc_handler = self.handle_database_exceptions()
+        result: SQLResult | None = None
+        try:
+            async with exc_handler, self.with_cursor(self.connection) as cursor:
+                execution_result = await self.dispatch_execute(cursor, direct_statement)
+
+                if cached.operation_profile.returns_rows:
+                    result = self.build_statement_result(direct_statement, execution_result)
+                else:
+                    # DML path: use DMLResult to bypass full SQLResult construction
+                    affected_rows = (
+                        execution_result.rowcount_override
+                        if execution_result.rowcount_override is not None and execution_result.rowcount_override >= 0
+                        else 0
+                    )
+                    result = DMLResult(cached.operation_type, affected_rows)
+
+            self._check_pending_exception(exc_handler)
+            assert result is not None
+            return result
+        finally:
+            self._release_pooled_statement(direct_statement)
+
+    async def _stmt_cache_lookup(self, statement: str, params: "tuple[Any, ...] | list[Any]") -> "SQLResult | None":
+        """Attempt fast-path execution for cached query (async).
+
+        Args:
+            statement: Raw SQL string.
+            params: Query parameters.
+
+        Returns:
+            SQLResult if cache hit and execution succeeds, None otherwise.
+        """
+        result = super()._stmt_cache_lookup(statement, params)
+        if result is None:
+            return None
+        return await cast("Awaitable[SQLResult | None]", result)
+
+    async def _stmt_cache_execute(self, statement: "SQL") -> "SQLResult":
+        """Execute pre-compiled query via fast path (async).
+
+        The statement is already compiled by _stmt_cache_prepare_direct, so dispatch_execute
+        will hit the fast path in _get_compiled_statement (is_processed check).
+        """
+        exc_handler = self.handle_database_exceptions()
+        result: SQLResult | None = None
+        try:
+            async with exc_handler, self.with_cursor(self.connection) as cursor:
+                execution_result = await self.dispatch_execute(cursor, statement)
+                result = self.build_statement_result(statement, execution_result)
+
+            self._check_pending_exception(exc_handler)
+            assert result is not None
+            return result
+        finally:
+            self._release_pooled_statement(statement)
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # TRANSACTION MANAGEMENT - Required Abstract Methods
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    async def begin(self) -> None:
+        """Begin a database transaction on the current connection."""
+
+    @abstractmethod
+    async def commit(self) -> None:
+        """Commit the current transaction on the current connection."""
+
+    @abstractmethod
+    async def rollback(self) -> None:
+        """Rollback the current transaction on the current connection."""
+
+    @abstractmethod
+    def with_cursor(self, connection: Any) -> Any:
+        """Create and return an async context manager for cursor acquisition and cleanup.
+
+        Returns an async context manager that yields a cursor for database operations.
+        Concrete implementations handle database-specific cursor creation and cleanup.
+        """
+
+    @abstractmethod
+    def handle_database_exceptions(self) -> "AsyncExceptionHandler":
+        """Handle database-specific exceptions and wrap them appropriately.
+
+        Returns:
+            Exception handler with deferred exception pattern for mypyc compatibility.
+            The handler stores mapped exceptions in pending_exception rather than
+            raising from __aexit__ to avoid ABI boundary violations.
+
+        """
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # PUBLIC API - Core Execution Methods
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    async def execute(
+        self,
+        statement: "SQL | Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SQLResult":
+        """Execute a statement with parameter handling."""
+        exc_handler = self.handle_database_exceptions()
+        result: SQLResult | None = None
+        async with exc_handler:
+            if (
+                self._stmt_cache_enabled
+                and (statement_config is None or statement_config is self.statement_config)
+                and isinstance(statement, str)
+                and len(parameters) == 1
+                and isinstance(parameters[0], (tuple, list))
+                and not kwargs
+            ):
+                fast_result = await self._stmt_cache_lookup(statement, parameters[0])
+                if fast_result is not None:
+                    result = fast_result
+            if result is None:
+                sql_statement = self.prepare_statement(
+                    statement, parameters, statement_config=statement_config or self.statement_config, kwargs=kwargs
+                )
+                result = await self.dispatch_statement_execution(statement=sql_statement, connection=self.connection)
+        self._check_pending_exception(exc_handler)
+        assert result is not None
+        return result
+
+    async def execute_many(
+        self,
+        statement: "SQL | Statement | QueryBuilder",
+        /,
+        parameters: "Sequence[StatementParameters]",
+        *filters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SQLResult":
+        """Execute statement multiple times with different parameters.
+
+        Parameters passed will be used as the batch execution sequence.
+        """
+        exc_handler = self.handle_database_exceptions()
+        result: SQLResult | None = None
+        async with exc_handler:
+            config = statement_config or self.statement_config
+
+            if isinstance(statement, str) and not filters and not kwargs:
+                sql_statement = SQL(statement, parameters, statement_config=config, is_many=True)
+            elif isinstance(statement, SQL):
+                statement_seed = statement.raw_expression or statement.raw_sql
+                sql_statement = SQL(statement_seed, parameters, statement_config=config, is_many=True, **kwargs)
+            else:
+                base_statement = self.prepare_statement(statement, filters, statement_config=config, kwargs=kwargs)
+                statement_seed = base_statement.raw_expression or base_statement.raw_sql
+                sql_statement = SQL(statement_seed, parameters, statement_config=config, is_many=True, **kwargs)
+
+            result = await self.dispatch_statement_execution(statement=sql_statement, connection=self.connection)
+        self._check_pending_exception(exc_handler)
+        assert result is not None
+        return result
+
+    async def execute_script(
+        self,
+        statement: "str | SQL",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SQLResult":
+        """Execute a multi-statement script.
+
+        By default, validates each statement and logs warnings for dangerous
+        operations. Use suppress_warnings=True for migrations and admin scripts.
+        """
+        exc_handler = self.handle_database_exceptions()
+        result: SQLResult | None = None
+        async with exc_handler:
+            config = statement_config or self.statement_config
+            sql_statement = self.prepare_statement(statement, parameters, statement_config=config, kwargs=kwargs)
+            result = await self.dispatch_statement_execution(
+                statement=sql_statement.as_script(), connection=self.connection
+            )
+        self._check_pending_exception(exc_handler)
+        assert result is not None
+        return result
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # PUBLIC API - Query Methods (select/fetch variants)
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    @overload
+    async def select(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "list[SchemaT]": ...
+
+    @overload
+    async def select(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "list[dict[str, Any]]": ...
+
+    async def select(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "list[SchemaT] | list[dict[str, Any]]":
+        """Execute a select statement and return all rows."""
+        result = await self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+        return result.get_data(schema_type=schema_type)
+
+    @overload
+    async def fetch(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "list[SchemaT]": ...
+
+    @overload
+    async def fetch(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "list[dict[str, Any]]": ...
+
+    async def fetch(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "list[SchemaT] | list[dict[str, Any]]":
+        """Execute a select statement and return all rows.
+
+        This is an alias for :meth:`select` provided for users familiar
+        with asyncpg's fetch() naming convention.
+
+        See Also:
+            select(): Primary method with identical behavior
+
+        """
+        return await self.select(
+            statement, *parameters, schema_type=schema_type, statement_config=statement_config, **kwargs
+        )
+
+    @overload
+    async def select_one(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT": ...
+
+    @overload
+    async def select_one(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+
+    async def select_one(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT | dict[str, Any]":
+        """Execute a select statement and return exactly one row.
+
+        Raises an exception if no rows or more than one row is returned.
+        """
+        result = await self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+        try:
+            return result.one(schema_type=schema_type)
+        except ValueError as error:
+            handle_single_row_error(error)
+
+    @overload
+    async def fetch_one(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT": ...
+
+    @overload
+    async def fetch_one(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+
+    async def fetch_one(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT | dict[str, Any]":
+        """Execute a select statement and return exactly one row.
+
+        This is an alias for :meth:`select_one` provided for users familiar
+        with asyncpg's fetch_one() naming convention.
+
+        Raises an exception if no rows or more than one row is returned.
+
+        See Also:
+            select_one(): Primary method with identical behavior
+
+        """
+        return await self.select_one(
+            statement, *parameters, schema_type=schema_type, statement_config=statement_config, **kwargs
+        )
+
+    @overload
+    async def select_one_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT | None": ...
+
+    @overload
+    async def select_one_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any] | None": ...
+
+    async def select_one_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT | dict[str, Any] | None":
+        """Execute a select statement and return at most one row.
+
+        Returns None if no rows are found. Raises ``ValueError`` if more than one
+        row is returned. Any database or SQL execution errors raised by the driver
+        are propagated unchanged.
+        """
+        result = await self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+        return result.one_or_none(schema_type=schema_type)
+
+    @overload
+    async def fetch_one_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT | None": ...
+
+    @overload
+    async def fetch_one_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any] | None": ...
+
+    async def fetch_one_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "SchemaT | dict[str, Any] | None":
+        """Execute a select statement and return at most one row.
+
+        This is an alias for :meth:`select_one_or_none` provided for users familiar
+        with asyncpg's fetch_one_or_none() naming convention.
+
+        Returns None if no rows are found.
+        Raises an exception if more than one row is returned.
+
+        See Also:
+            select_one_or_none(): Primary method with identical behavior
+
+        """
+        return await self.select_one_or_none(
+            statement, *parameters, schema_type=schema_type, statement_config=statement_config, **kwargs
+        )
+
+    @overload
+    async def select_value(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT": ...
+
+    @overload
+    async def select_value(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> Any: ...
+
+    async def select_value(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT | Any":
+        """Execute a select statement and return a single scalar value.
+
+        Expects exactly one row with one column.
+        Raises an exception if no rows or more than one row/column is returned.
+
+        Args:
+            statement: SQL statement or query builder to execute.
+            *parameters: Positional parameters for the statement.
+            value_type: Optional type to convert the result to. When provided,
+                the return value is converted to this type and the return type
+                is narrowed for type checkers. Supports int, float, str, bool,
+                datetime, date, time, Decimal, UUID, Path, dict, and list.
+            statement_config: Optional statement configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The scalar value, optionally converted to the specified type
+
+        Examples:
+            Basic usage (returns Any):
+
+            >>> count = await driver.select_value(
+            ...     "SELECT COUNT(*) FROM users"
+            ... )
+
+            With type hint (returns int):
+
+            >>> count = await driver.select_value(
+            ...     "SELECT COUNT(*) FROM users", value_type=int
+            ... )
+
+            With UUID conversion:
+
+            >>> user_id = await driver.select_value(
+            ...     "SELECT id FROM users WHERE name = :name",
+            ...     {"name": "alice"},
+            ...     value_type=UUID,
+            ... )
+        """
+        result = await self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+        try:
+            value = result.scalar()
+        except ValueError as error:
+            handle_single_row_error(error)
+
+        if value_type is not None:
+            return to_value_type(value, value_type)
+        return value
+
+    @overload
+    async def fetch_value(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT": ...
+
+    @overload
+    async def fetch_value(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> Any: ...
+
+    async def fetch_value(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT | Any":
+        """Execute a select statement and return a single scalar value.
+
+        This is an alias for :meth:`select_value` provided for users familiar
+        with asyncpg's fetch_value() naming convention.
+
+        Expects exactly one row with one column.
+        Raises an exception if no rows or more than one row/column is returned.
+
+        See Also:
+            select_value(): Primary method with identical behavior
+
+        """
+        return await self.select_value(
+            statement, *parameters, value_type=value_type, statement_config=statement_config, **kwargs
+        )
+
+    @overload
+    async def select_value_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT | None": ...
+
+    @overload
+    async def select_value_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> Any: ...
+
+    async def select_value_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT | None | Any":
+        """Execute a select statement and return a single scalar value or None.
+
+        Returns None if no rows are found.
+        Expects at most one row with one column.
+        Raises an exception if more than one row is returned.
+
+        Args:
+            statement: SQL statement or query builder to execute.
+            *parameters: Positional parameters for the statement.
+            value_type: Optional type to convert the result to. When provided,
+                the return value is converted to this type and the return type
+                is narrowed to ``T | None`` for type checkers. Supports int, float,
+                str, bool, datetime, date, time, Decimal, UUID, Path, dict, and list.
+            statement_config: Optional statement configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The scalar value (optionally converted), or None if no rows found.
+
+        Examples:
+            Basic usage:
+
+            >>> email = await driver.select_value_or_none(
+            ...     "SELECT email FROM users WHERE id = :id", {"id": 123}
+            ... )
+            >>> if email is not None:
+            ...     print(email)
+
+            With type hint:
+
+            >>> count = await driver.select_value_or_none(
+            ...     "SELECT COUNT(*) FROM users WHERE active = true",
+            ...     value_type=int,
+            ... )
+            >>> if count is not None and count > 0:
+            ...     print(f"Found {count} active users")
+        """
+        result = await self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+        value = result.scalar_or_none()
+
+        if value is None:
+            return None
+        if value_type is not None:
+            return to_value_type(value, value_type)
+        return value
+
+    @overload
+    async def fetch_value_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT]",
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT | None": ...
+
+    @overload
+    async def fetch_value_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> Any: ...
+
+    async def fetch_value_or_none(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        value_type: "type[ValueT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        **kwargs: Any,
+    ) -> "ValueT | None | Any":
+        """Execute a select statement and return a single scalar value or None.
+
+        This is an alias for :meth:`select_value_or_none` provided for users familiar
+        with asyncpg's fetch_value_or_none() naming convention.
+
+        Returns None if no rows are found.
+        Expects at most one row with one column.
+        Raises an exception if more than one row is returned.
+
+        See Also:
+            select_value_or_none(): Primary method with identical behavior
+
+        """
+        return await self.select_value_or_none(
+            statement, *parameters, value_type=value_type, statement_config=statement_config, **kwargs
+        )
+
+    @overload
+    async def select_with_total(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
+        **kwargs: Any,
+    ) -> "tuple[list[SchemaT], int]": ...
+
+    @overload
+    async def select_with_total(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
+        **kwargs: Any,
+    ) -> "tuple[list[dict[str, Any]], int]": ...
+
+    async def select_with_total(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
+        **kwargs: Any,
+    ) -> "tuple[list[SchemaT] | list[dict[str, Any]], int]":
+        """Execute a select statement and return both the data and total count.
+
+        This method is designed for pagination scenarios where you need both
+        the current page of data and the total number of rows that match the query.
+
+        Args:
+            statement: The SQL statement, QueryBuilder, or raw SQL string
+            *parameters: Parameters for the SQL statement
+            schema_type: Optional schema type for data transformation
+            statement_config: Optional SQL configuration
+            count_with_window: If True, use a single query with COUNT(*) OVER() window
+                function instead of two separate queries. This can be more efficient
+                for some databases but adds a column to each row. Default False.
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            A tuple containing:
+            - List of data rows (transformed by schema_type if provided)
+            - Total count of rows matching the query (ignoring LIMIT/OFFSET)
+
+        Example:
+            >>> # Two-query approach (default):
+            >>> data, total = await driver.select_with_total(
+            ...     sql
+            ...     .select("*")
+            ...     .from_("users")
+            ...     .where_eq("status", "active")
+            ...     .limit(10)
+            ... )
+
+            >>> # Single-query with window function:
+            >>> data, total = await driver.select_with_total(
+            ...     sql
+            ...     .select("*")
+            ...     .from_("users")
+            ...     .where_eq("status", "active")
+            ...     .limit(10),
+            ...     count_with_window=True,
+            ... )
+
+        """
+        sql_statement = self.prepare_statement(
+            statement, parameters, statement_config=statement_config or self.statement_config, kwargs=kwargs
+        )
+
+        if count_with_window:
+            modified_sql = self._add_count_over_column(sql_statement)
+            result = await self.dispatch_statement_execution(modified_sql, self.connection)
+            rows = result.all()
+            data, total = self._extract_total_from_rows(rows)
+
+            if schema_type is not None:
+                return ([schema_type(**r) for r in data], total)
+            return (data, total)
+
+        count_result = await self.dispatch_statement_execution(self._create_count_query(sql_statement), self.connection)
+        select_result = await self.dispatch_statement_execution(sql_statement, self.connection)
+
+        return (select_result.get_data(schema_type=schema_type), count_result.scalar())
+
+    @overload
+    async def fetch_with_total(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT]",
+        statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
+        **kwargs: Any,
+    ) -> "tuple[list[SchemaT], int]": ...
+
+    @overload
+    async def fetch_with_total(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: None = None,
+        statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
+        **kwargs: Any,
+    ) -> "tuple[list[dict[str, Any]], int]": ...
+
+    async def fetch_with_total(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        schema_type: "type[SchemaT] | None" = None,
+        statement_config: "StatementConfig | None" = None,
+        count_with_window: bool = False,
+        **kwargs: Any,
+    ) -> "tuple[list[SchemaT] | list[dict[str, Any]], int]":
+        """Execute a select statement and return both the data and total count.
+
+        This is an alias for :meth:`select_with_total` provided for users familiar
+        with asyncpg's fetch() naming convention.
+
+        This method is designed for pagination scenarios where you need both
+        the current page of data and the total number of rows that match the query.
+
+        See Also:
+            select_with_total(): Primary method with identical behavior and full documentation
+
+        """
+        return await self.select_with_total(
+            statement,
+            *parameters,
+            schema_type=schema_type,
+            statement_config=statement_config,
+            count_with_window=count_with_window,
+            **kwargs,
+        )
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # ARROW API METHODS
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    async def select_to_arrow(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        return_format: "ArrowReturnFormat" = "table",
+        native_only: bool = False,
+        batch_size: int | None = None,
+        arrow_schema: Any = None,
+        **kwargs: Any,
+    ) -> "ArrowResult":
+        """Execute query and return results as Apache Arrow format (async).
+
+        This base implementation uses the conversion path: execute() → dict → Arrow.
+        Adapters with native Arrow support (ADBC, DuckDB, BigQuery) override this
+        method to use zero-copy native paths for 5-10x performance improvement.
+
+        Args:
+            statement: SQL query string, Statement, or QueryBuilder
+            *parameters: Query parameters (same format as execute()/select())
+            statement_config: Optional statement configuration override
+            return_format: "table" for pyarrow.Table (default), "batch" for single RecordBatch,
+                         "batches" for iterator of RecordBatches, "reader" for RecordBatchReader
+            native_only: If True, raise error if native Arrow unavailable (default: False)
+            batch_size: Rows per batch for "batch"/"batches" format (default: None = all rows)
+            arrow_schema: Optional pyarrow.Schema for type casting
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            ArrowResult containing pyarrow.Table, RecordBatchReader, or RecordBatches
+
+        Raises:
+            ImproperConfigurationError: If native_only=True and adapter doesn't support native Arrow
+
+        Examples:
+            >>> result = await driver.select_to_arrow(
+            ...     "SELECT * FROM users WHERE age > ?", 18
+            ... )
+            >>> df = result.to_pandas()
+            >>> print(df.head())
+
+            >>> # Force native Arrow path (raises error if unavailable)
+            >>> result = await driver.select_to_arrow(
+            ...     "SELECT * FROM users", native_only=True
+            ... )
+
+        """
+        if native_only:
+            msg = (
+                f"Adapter '{self.__class__.__name__}' does not support native Arrow results. "
+                f"Use native_only=False to allow conversion path, or switch to an adapter "
+                f"with native Arrow support (ADBC, DuckDB, BigQuery)."
+            )
+            raise ImproperConfigurationError(msg)
+
+        result = await self.execute(statement, *parameters, statement_config=statement_config, **kwargs)
+
+        arrow_data = convert_dict_to_arrow_with_schema(
+            result.get_data(), return_format=return_format, batch_size=batch_size, arrow_schema=arrow_schema
+        )
+        return create_arrow_result(
+            statement=result.statement,
+            data=arrow_data,
+            rows_affected=result.rows_affected,
+            last_inserted_id=result.last_inserted_id,
+            execution_time=result.execution_time,
+            metadata=result.metadata,
+        )
+
+    async def fetch_to_arrow(
+        self,
+        statement: "Statement | QueryBuilder",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        return_format: "ArrowReturnFormat" = "table",
+        native_only: bool = False,
+        batch_size: int | None = None,
+        arrow_schema: Any = None,
+        **kwargs: Any,
+    ) -> "ArrowResult":
+        """Execute query and return results as Apache Arrow format (async).
+
+        This is an alias for :meth:`select_to_arrow` provided for users familiar
+        with asyncpg's fetch() naming convention.
+
+        See Also:
+            select_to_arrow(): Primary method with identical behavior and full documentation
+
+        """
+        return await self.select_to_arrow(
+            statement,
+            *parameters,
+            statement_config=statement_config,
+            return_format=return_format,
+            native_only=native_only,
+            batch_size=batch_size,
+            arrow_schema=arrow_schema,
+            **kwargs,
+        )
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # STACK EXECUTION
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    async def execute_stack(
+        self, stack: "StatementStack", *, continue_on_error: bool = False
+    ) -> "tuple[StackResult, ...]":
+        """Execute a StatementStack sequentially using the adapter's primitives."""
+        if not isinstance(stack, StatementStack):
+            msg = "execute_stack expects a StatementStack instance"
+            raise TypeError(msg)
+        if not stack:
+            msg = "Cannot execute an empty StatementStack"
+            raise ValueError(msg)
+
+        results: list[StackResult] = []
+        single_transaction = not continue_on_error
+
+        with StackExecutionObserver(self, stack, continue_on_error, native_pipeline=False) as observer:
+            started_transaction = False
+
+            try:
+                if single_transaction and not self._connection_in_transaction():
+                    await self.begin()
+                    started_transaction = True
+
+                for index, operation in enumerate(stack.operations):
+                    try:
+                        result = await self._execute_stack_operation(operation)
+                    except Exception as exc:  # pragma: no cover - exercised via tests
+                        stack_error = StackExecutionError(
+                            index,
+                            describe_stack_statement(operation.statement),
+                            exc,
+                            adapter=type(self).__name__,
+                            mode="continue-on-error" if continue_on_error else "fail-fast",
+                        )
+
+                        if started_transaction and not continue_on_error:
+                            try:
+                                await self.rollback()
+                            except Exception as rollback_error:  # pragma: no cover - diagnostics only
+                                logger.debug("Rollback after stack failure failed: %s", rollback_error)
+                            started_transaction = False
+
+                        if continue_on_error:
+                            await self._rollback_after_stack_error_async()
+                            observer.record_operation_error(stack_error)
+                            results.append(StackResult.from_error(stack_error))
+                            continue
+
+                        raise stack_error from exc
+
+                    results.append(StackResult(result=result))
+
+                    if continue_on_error:
+                        await self._commit_after_stack_operation_async()
+
+                if started_transaction:
+                    await self.commit()
+            except Exception:
+                if started_transaction:
+                    try:
+                        await self.rollback()
+                    except Exception as rollback_error:  # pragma: no cover - diagnostics only
+                        logger.debug("Rollback after stack failure failed: %s", rollback_error)
+                raise
+
+        return tuple(results)
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # STORAGE API METHODS
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    async def select_to_storage(
+        self,
+        statement: "SQL | str",
+        destination: "StorageDestination",
+        /,
+        *parameters: "StatementParameters | StatementFilter",
+        statement_config: "StatementConfig | None" = None,
+        partitioner: "dict[str, object] | None" = None,
+        format_hint: "StorageFormat | None" = None,
+        telemetry: "StorageTelemetry | None" = None,
+    ) -> "StorageBridgeJob":
+        """Stream a SELECT statement directly into storage.
+
+        Args:
+            statement: SQL statement to execute.
+            destination: Storage destination path.
+            parameters: Query parameters.
+            statement_config: Optional statement configuration.
+            partitioner: Optional partitioner configuration.
+            format_hint: Optional format hint for storage.
+            telemetry: Optional telemetry dict to merge.
+
+        Returns:
+            StorageBridgeJob with execution telemetry.
+
+        """
+        self._raise_storage_not_implemented("select_to_storage")
+        raise NotImplementedError
+
+    async def load_from_arrow(
+        self,
+        table: str,
+        source: "ArrowResult | Any",
+        *,
+        partitioner: "dict[str, object] | None" = None,
+        overwrite: bool = False,
+    ) -> "StorageBridgeJob":
+        """Load Arrow data into the target table.
+
+        Args:
+            table: Target table name.
+            source: Arrow data source.
+            partitioner: Optional partitioner configuration.
+            overwrite: Whether to overwrite existing data.
+
+        Returns:
+            StorageBridgeJob with execution telemetry.
+
+        Raises:
+            NotImplementedError: If not implemented.
+
+        """
+        self._raise_storage_not_implemented("load_from_arrow")
+        raise NotImplementedError
+
+    async def load_from_storage(
+        self,
+        table: str,
+        source: "StorageDestination",
+        *,
+        file_format: "StorageFormat",
+        partitioner: "dict[str, object] | None" = None,
+        overwrite: bool = False,
+    ) -> "StorageBridgeJob":
+        """Load artifacts from storage into the target table.
+
+        Args:
+            table: Target table name.
+            source: Storage source path.
+            file_format: File format of source.
+            partitioner: Optional partitioner configuration.
+            overwrite: Whether to overwrite existing data.
+
+        Returns:
+            StorageBridgeJob with execution telemetry.
+
+        """
+        self._raise_storage_not_implemented("load_from_storage")
+        raise NotImplementedError
+
+    def stage_artifact(self, request: "dict[str, Any]") -> "dict[str, Any]":
+        """Provision staging metadata for adapters that require remote URIs.
+
+        Args:
+            request: Staging request configuration.
+
+        Returns:
+            Staging metadata dict.
+
+        """
+        self._raise_storage_not_implemented("stage_artifact")
+        raise NotImplementedError
+
+    def flush_staging_artifacts(self, artifacts: "list[dict[str, Any]]", *, error: Exception | None = None) -> None:
+        """Clean up staged artifacts after a job completes.
+
+        Args:
+            artifacts: List of staging artifacts to clean up.
+            error: Optional error that triggered cleanup.
+
+        """
+        if artifacts:
+            self._raise_storage_not_implemented("flush_staging_artifacts")
+
+    def get_storage_job(self, job_id: str) -> "StorageBridgeJob | None":
+        """Fetch a previously created job handle.
+
+        Args:
+            job_id: Job identifier.
+
+        Returns:
+            StorageBridgeJob if found, None otherwise.
+
+        """
+        return None
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # UTILITY METHODS
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    def convert_to_dialect(
+        self, statement: "Statement", to_dialect: "DialectType | None" = None, pretty: bool = DEFAULT_PRETTY
+    ) -> str:
+        """Convert a statement to a target SQL dialect.
+
+        Args:
+            statement: SQL statement to convert.
+            to_dialect: Target dialect (defaults to current dialect).
+            pretty: Whether to format the output SQL.
+
+        Returns:
+            SQL string in target dialect.
+
+        """
+        return _convert_to_dialect_impl(statement, self.dialect, to_dialect, pretty)
+
+    # ─────────────────────────────────────────────────────────────────────────────
+    # PRIVATE/INTERNAL METHODS
+    # ─────────────────────────────────────────────────────────────────────────────
+
+    def _connection_in_transaction(self) -> bool:
+        """Check if the connection is inside a transaction.
+
+        Each adapter MUST override this method with direct attribute access
+        for optimal mypyc performance. Do not use getattr chains.
+
+        Raises:
+            NotImplementedError: Always - subclasses must override.
+
+        """
+        msg = "Adapters must override _connection_in_transaction()"
+        raise NotImplementedError(msg)
+
+    async def _execute_stack_operation(self, operation: "StackOperation") -> "SQLResult | ArrowResult | None":
+        kwargs = dict(operation.keyword_arguments) if operation.keyword_arguments else {}
+
+        if operation.method == "execute":
+            return await self.execute(operation.statement, *operation.arguments, **kwargs)
+
+        if operation.method == "execute_many":
+            if not operation.arguments:
+                msg = "execute_many stack operation requires parameter sets"
+                raise ValueError(msg)
+            parameter_sets = operation.arguments[0]
+            filters = operation.arguments[1:]
+            return await self.execute_many(operation.statement, parameter_sets, *filters, **kwargs)
+
+        if operation.method == "execute_script":
+            return await self.execute_script(operation.statement, *operation.arguments, **kwargs)
+
+        if operation.method == "execute_arrow":
+            return await self.select_to_arrow(operation.statement, *operation.arguments, **kwargs)
+
+        msg = f"Unsupported stack operation method: {operation.method}"
+        raise ValueError(msg)
+
+    async def _rollback_after_stack_error_async(self) -> None:
+        """Attempt to rollback after a stack operation error (async)."""
+        try:
+            await self.rollback()
+        except Exception as rollback_error:  # pragma: no cover - driver-specific cleanup
+            logger.debug("Rollback after stack error failed: %s", rollback_error)
+
+    async def _commit_after_stack_operation_async(self) -> None:
+        """Attempt to commit after a successful stack operation when not batching (async)."""
+        try:
+            await self.commit()
+        except Exception as commit_error:  # pragma: no cover - driver-specific cleanup
+            logger.debug("Commit after stack operation failed: %s", commit_error)
+
+    def _storage_pipeline(self) -> "AsyncStoragePipeline":
+        """Get or create an async storage pipeline.
+
+        Returns:
+            AsyncStoragePipeline instance.
+
+        """
+        factory = self.storage_pipeline_factory
+        if factory is None:
+            return AsyncStoragePipeline()
+        return cast("AsyncStoragePipeline", factory())
+
+    async def _write_result_to_storage_async(
+        self,
+        result: "ArrowResult",
+        destination: "StorageDestination",
+        *,
+        format_hint: "StorageFormat | None" = None,
+        storage_options: "dict[str, Any] | None" = None,
+        pipeline: "AsyncStoragePipeline | None" = None,
+    ) -> "StorageTelemetry":
+        """Write Arrow result to storage with telemetry.
+
+        Args:
+            result: Arrow result to write.
+            destination: Storage destination.
+            format_hint: Optional format hint.
+            storage_options: Optional storage options.
+            pipeline: Optional storage pipeline.
+
+        Returns:
+            StorageTelemetry with write metrics.
+
+        """
+        runtime = self.observability
+        span = runtime.start_storage_span(
+            "write", destination=stringify_storage_target(destination), format_label=format_hint
+        )
+        try:
+            telemetry = await result.write_to_storage_async(
+                destination, format_hint=format_hint, storage_options=storage_options, pipeline=pipeline
+            )
+        except Exception as exc:
+            runtime.end_storage_span(span, error=exc)
+            raise
+        telemetry = runtime.annotate_storage_telemetry(telemetry)
+        runtime.end_storage_span(span, telemetry=telemetry)
+        return telemetry
+
+    async def _read_arrow_from_storage_async(
+        self,
+        source: "StorageDestination",
+        *,
+        file_format: "StorageFormat",
+        storage_options: "dict[str, Any] | None" = None,
+    ) -> "tuple[ArrowTable, StorageTelemetry]":
+        """Read Arrow table from storage with telemetry.
+
+        Args:
+            source: Storage source path.
+            file_format: File format to read.
+            storage_options: Optional storage options.
+
+        Returns:
+            Tuple of (ArrowTable, StorageTelemetry).
+
+        """
+        runtime = self.observability
+        span = runtime.start_storage_span(
+            "read", destination=stringify_storage_target(source), format_label=file_format
+        )
+        pipeline = self._storage_pipeline()
+        try:
+            table, telemetry = await pipeline.read_arrow_async(
+                source, file_format=file_format, storage_options=storage_options
+            )
+        except Exception as exc:
+            runtime.end_storage_span(span, error=exc)
+            raise
+        telemetry = runtime.annotate_storage_telemetry(telemetry)
+        runtime.end_storage_span(span, telemetry=telemetry)
+        return table, telemetry
+
+
+@mypyc_attr(allow_interpreted_subclasses=True)
+class AsyncDataDictionaryBase(DataDictionaryDialectMixin, DataDictionaryMixin):
+    """Base class for asynchronous data dictionary implementations.
+
+    Uses Python-compatible class layouts for cross-module inheritance.
+    Child classes define dialect as a class attribute.
+    """
+
+    dialect: "ClassVar[str]"
+    """Dialect identifier. Must be defined by subclasses as a class attribute."""
+
+    def __init__(self) -> None:
+        self._version_cache: dict[int, VersionInfo | None] = {}
+        self._version_fetch_attempted: set[int] = set()
+
+    @abstractmethod
+    async def get_version(self, driver: Any) -> "VersionInfo | None":
+        """Get database version information.
+
+        Args:
+            driver: Async database driver instance
+
+        Returns:
+            Version information or None if detection fails
+
+        """
+
+    @abstractmethod
+    async def get_feature_flag(self, driver: Any, feature: str) -> bool:
+        """Check if database supports a specific feature.
+
+        Args:
+            driver: Async database driver instance
+            feature: Feature name to check
+
+        Returns:
+            True if feature is supported, False otherwise
+
+        """
+
+    @abstractmethod
+    async def get_optimal_type(self, driver: Any, type_category: str) -> str:
+        """Get optimal database type for a category.
+
+        Args:
+            driver: Async database driver instance
+            type_category: Type category (e.g., 'json', 'uuid', 'boolean')
+
+        Returns:
+            Database-specific type name
+
+        """
+
+    @abstractmethod
+    async def get_tables(self, driver: Any, schema: "str | None" = None) -> "list[TableMetadata]":
+        """Get list of tables in schema.
+
+        Args:
+            driver: Async database driver instance
+            schema: Schema name (None for default)
+
+        Returns:
+            List of table metadata dictionaries
+
+        """
+
+    @abstractmethod
+    async def get_columns(
+        self, driver: Any, table: "str | None" = None, schema: "str | None" = None
+    ) -> "list[ColumnMetadata]":
+        """Get column information for a table or schema.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name (None to fetch columns for all tables in schema)
+            schema: Schema name (None for default)
+
+        Returns:
+            List of column metadata dictionaries
+
+        """
+
+    @abstractmethod
+    async def get_indexes(
+        self, driver: Any, table: "str | None" = None, schema: "str | None" = None
+    ) -> "list[IndexMetadata]":
+        """Get index information for a table or schema.
+
+        Args:
+            driver: Async database driver instance
+            table: Table name (None to fetch indexes for all tables in schema)
+            schema: Schema name (None for default)
+
+        Returns:
+            List of index metadata dictionaries
+
+        """
+
+    @abstractmethod
+    async def get_foreign_keys(
+        self, driver: Any, table: "str | None" = None, schema: "str | None" = None
+    ) -> "list[ForeignKeyMetadata]":
+        """Get foreign key metadata.
+
+        Args:
+            driver: Async database driver instance
+            table: Optional table name filter
+            schema: Optional schema name filter
+
+        Returns:
+            List of foreign key metadata
+
+        """