sqlspec 0.8.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

sqlspec/base.py

@@ -1,10 +1,12 @@
 # ruff: noqa: PLR6301
+import atexit
+import contextlib
 import re
 from abc import ABC, abstractmethod
-from collections.abc import AsyncGenerator, Awaitable, Generator
-from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from collections.abc import Awaitable, Sequence
 from dataclasses import dataclass, field
 from typing import (
+    TYPE_CHECKING,
     Annotated,
     Any,
     ClassVar,
@@ -17,15 +19,29 @@ from typing import (
 )
 
 from sqlspec.exceptions import NotFoundError
+from sqlspec.statement import SQLStatement
 from sqlspec.typing import ModelDTOT, StatementParameterType
+from sqlspec.utils.sync_tools import maybe_async_
+
+if TYPE_CHECKING:
+    from contextlib import AbstractAsyncContextManager, AbstractContextManager
+
+    from pyarrow import Table as ArrowTable
 
 __all__ = (
+    "AsyncArrowBulkOperationsMixin",
     "AsyncDatabaseConfig",
+    "AsyncDriverAdapterProtocol",
+    "CommonDriverAttributes",
     "DatabaseConfigProtocol",
     "GenericPoolConfig",
     "NoPoolAsyncConfig",
     "NoPoolSyncConfig",
+    "SQLSpec",
+    "SQLStatement",
+    "SyncArrowBulkOperationsMixin",
     "SyncDatabaseConfig",
+    "SyncDriverAdapterProtocol",
 )
 
 T = TypeVar("T")
@@ -39,13 +55,15 @@ ConfigT = TypeVar(
     bound="Union[Union[AsyncDatabaseConfig[Any, Any, Any], NoPoolAsyncConfig[Any, Any]], SyncDatabaseConfig[Any, Any, Any], NoPoolSyncConfig[Any, Any]]",
 )
 DriverT = TypeVar("DriverT", bound="Union[SyncDriverAdapterProtocol[Any], AsyncDriverAdapterProtocol[Any]]")
-
-# Regex to find :param style placeholders, avoiding those inside quotes
-# Handles basic cases, might need refinement for complex SQL
+# Regex to find :param or %(param)s style placeholders, skipping those inside quotes
 PARAM_REGEX = re.compile(
-    r"(?P<dquote>\"(?:[^\"]|\"\")*\")|"  # Double-quoted strings
-    r"(?P<squote>'(?:[^']|'')*')|"  # Single-quoted strings
-    r"(?P<lead>[^:]):(?P<var_name>[a-zA-Z_][a-zA-Z0-9_]*)"  # :param placeholder
+    r"""
+    (?P<dquote>"([^"]|\\")*") | # Double-quoted strings
+    (?P<squote>'([^']|\\')*') | # Single-quoted strings
+    : (?P<var_name_colon>[a-zA-Z_][a-zA-Z0-9_]*) | # :var_name
+    % \( (?P<var_name_perc>[a-zA-Z_][a-zA-Z0-9_]*) \) s # %(var_name)s
+    """,
+    re.VERBOSE,
 )
 
 
@@ -56,14 +74,14 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
     connection_type: "type[ConnectionT]" = field(init=False)
     driver_type: "type[DriverT]" = field(init=False)
     pool_instance: "Optional[PoolT]" = field(default=None)
-    __is_async__: ClassVar[bool] = False
-    __supports_connection_pooling__: ClassVar[bool] = False
+    __is_async__: "ClassVar[bool]" = False
+    __supports_connection_pooling__: "ClassVar[bool]" = False
 
     def __hash__(self) -> int:
         return id(self)
 
     @abstractmethod
-    def create_connection(self) -> Union[ConnectionT, Awaitable[ConnectionT]]:
+    def create_connection(self) -> "Union[ConnectionT, Awaitable[ConnectionT]]":
         """Create and return a new database connection."""
         raise NotImplementedError
 
@@ -72,28 +90,32 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         self,
         *args: Any,
         **kwargs: Any,
-    ) -> Union[
-        Generator[ConnectionT, None, None],
-        AsyncGenerator[ConnectionT, None],
-        AbstractContextManager[ConnectionT],
-        AbstractAsyncContextManager[ConnectionT],
-    ]:
+    ) -> "Union[AbstractContextManager[ConnectionT], AbstractAsyncContextManager[ConnectionT]]":
         """Provide a database connection context manager."""
         raise NotImplementedError
 
+    @abstractmethod
+    def provide_session(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> "Union[AbstractContextManager[DriverT], AbstractAsyncContextManager[DriverT]]":
+        """Provide a database session context manager."""
+        raise NotImplementedError
+
     @property
     @abstractmethod
-    def connection_config_dict(self) -> dict[str, Any]:
+    def connection_config_dict(self) -> "dict[str, Any]":
         """Return the connection configuration as a dict."""
         raise NotImplementedError
 
     @abstractmethod
-    def create_pool(self) -> Union[PoolT, Awaitable[PoolT]]:
+    def create_pool(self) -> "Union[PoolT, Awaitable[PoolT]]":
         """Create and return connection pool."""
         raise NotImplementedError
 
     @abstractmethod
-    def close_pool(self) -> Optional[Awaitable[None]]:
+    def close_pool(self) -> "Optional[Awaitable[None]]":
         """Terminate the connection pool."""
         raise NotImplementedError
 
@@ -102,7 +124,7 @@ class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
         self,
         *args: Any,
         **kwargs: Any,
-    ) -> Union[PoolT, Awaitable[PoolT], AbstractContextManager[PoolT], AbstractAsyncContextManager[PoolT]]:
+    ) -> "Union[PoolT, Awaitable[PoolT], AbstractContextManager[PoolT], AbstractAsyncContextManager[PoolT]]":
         """Provide pool instance."""
         raise NotImplementedError
 
@@ -183,20 +205,26 @@ class SQLSpec:
 
     def __init__(self) -> None:
         self._configs: dict[Any, DatabaseConfigProtocol[Any, Any, Any]] = {}
+        # Register the cleanup handler to run at program exit
+        atexit.register(self._cleanup_pools)
+
+    def _cleanup_pools(self) -> None:
+        """Clean up all open database pools at program exit."""
+        for config in self._configs.values():
+            if config.support_connection_pooling and config.pool_instance is not None:
+                with contextlib.suppress(Exception):
+                    maybe_async_(config.close_pool)()
 
     @overload
-    def add_config(self, config: SyncConfigT) -> type[SyncConfigT]: ...
+    def add_config(self, config: "SyncConfigT") -> "type[SyncConfigT]": ...
 
     @overload
-    def add_config(self, config: AsyncConfigT) -> type[AsyncConfigT]: ...
+    def add_config(self, config: "AsyncConfigT") -> "type[AsyncConfigT]": ...
 
     def add_config(
         self,
-        config: Union[
-            SyncConfigT,
-            AsyncConfigT,
-        ],
-    ) -> Union[Annotated[type[SyncConfigT], int], Annotated[type[AsyncConfigT], int]]:  # pyright: ignore[reportInvalidTypeVarUse]
+        config: "Union[SyncConfigT, AsyncConfigT]",
+    ) -> "Union[Annotated[type[SyncConfigT], int], Annotated[type[AsyncConfigT], int]]":  # pyright: ignore[reportInvalidTypeVarUse]
         """Add a new configuration to the manager.
 
         Returns:
@@ -207,15 +235,15 @@ class SQLSpec:
         return key  # type: ignore[return-value]  # pyright: ignore[reportReturnType]
 
     @overload
-    def get_config(self, name: type[SyncConfigT]) -> SyncConfigT: ...
+    def get_config(self, name: "type[SyncConfigT]") -> "SyncConfigT": ...
 
     @overload
-    def get_config(self, name: type[AsyncConfigT]) -> AsyncConfigT: ...
+    def get_config(self, name: "type[AsyncConfigT]") -> "AsyncConfigT": ...
 
     def get_config(
         self,
-        name: Union[type[DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]], Any],
-    ) -> DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]:
+        name: "Union[type[DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]], Any]",
+    ) -> "DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]":
         """Retrieve a configuration by its type.
 
         Returns:
@@ -234,61 +262,197 @@ class SQLSpec:
     def get_connection(
         self,
         name: Union[
-            type[NoPoolSyncConfig[ConnectionT, DriverT]],
-            type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]],  # pyright: ignore[reportInvalidTypeVarUse]
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",  # pyright: ignore[reportInvalidTypeVarUse]
         ],
-    ) -> ConnectionT: ...
+    ) -> "ConnectionT": ...
 
     @overload
     def get_connection(
         self,
         name: Union[
-            type[NoPoolAsyncConfig[ConnectionT, DriverT]],
-            type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]],  # pyright: ignore[reportInvalidTypeVarUse]
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",  # pyright: ignore[reportInvalidTypeVarUse]
         ],
-    ) -> Awaitable[ConnectionT]: ...
+    ) -> "Awaitable[ConnectionT]": ...
 
     def get_connection(
         self,
         name: Union[
-            type[NoPoolSyncConfig[ConnectionT, DriverT]],
-            type[NoPoolAsyncConfig[ConnectionT, DriverT]],
-            type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]],
-            type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]],
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
         ],
-    ) -> Union[ConnectionT, Awaitable[ConnectionT]]:
-        """Create and return a connection from the specified configuration.
+    ) -> "Union[ConnectionT, Awaitable[ConnectionT]]":
+        """Create and return a new database connection from the specified configuration.
 
         Args:
             name: The configuration type to use for creating the connection.
 
         Returns:
-            Either a connection instance or an awaitable that resolves to a connection,
-            depending on whether the configuration is sync or async.
+            Either a connection instance or an awaitable that resolves to a connection instance.
         """
         config = self.get_config(name)
         return config.create_connection()
 
+    @overload
+    def get_session(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+    ) -> "DriverT": ...
+
+    @overload
+    def get_session(
+        self,
+        name: Union[
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+    ) -> "Awaitable[DriverT]": ...
+
+    def get_session(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+    ) -> "Union[DriverT, Awaitable[DriverT]]":
+        """Create and return a new database session from the specified configuration.
+
+        Args:
+            name: The configuration type to use for creating the session.
+
+        Returns:
+            Either a driver instance or an awaitable that resolves to a driver instance.
+        """
+        config = self.get_config(name)
+        connection = self.get_connection(name)
+        if isinstance(connection, Awaitable):
+
+            async def _create_session() -> DriverT:
+                return cast("DriverT", config.driver_type(await connection))  # pyright: ignore
+
+            return _create_session()
+        return cast("DriverT", config.driver_type(connection))  # pyright: ignore
+
+    @overload
+    def provide_connection(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "AbstractContextManager[ConnectionT]": ...
+
+    @overload
+    def provide_connection(
+        self,
+        name: Union[
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "AbstractAsyncContextManager[ConnectionT]": ...
+
+    def provide_connection(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "Union[AbstractContextManager[ConnectionT], AbstractAsyncContextManager[ConnectionT]]":
+        """Create and provide a database connection from the specified configuration.
+
+        Args:
+            name: The configuration type to use for creating the connection.
+            *args: Positional arguments to pass to the configuration's provide_connection method.
+            **kwargs: Keyword arguments to pass to the configuration's provide_connection method.
+
+        Returns:
+            Either a synchronous or asynchronous context manager that provides a database connection.
+        """
+        config = self.get_config(name)
+        return config.provide_connection(*args, **kwargs)
+
+    @overload
+    def provide_session(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "AbstractContextManager[DriverT]": ...
+
+    @overload
+    def provide_session(
+        self,
+        name: Union[
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "AbstractAsyncContextManager[DriverT]": ...
+
+    def provide_session(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "Union[AbstractContextManager[DriverT], AbstractAsyncContextManager[DriverT]]":
+        """Create and provide a database session from the specified configuration.
+
+        Args:
+            name: The configuration type to use for creating the session.
+            *args: Positional arguments to pass to the configuration's provide_session method.
+            **kwargs: Keyword arguments to pass to the configuration's provide_session method.
+
+        Returns:
+            Either a synchronous or asynchronous context manager that provides a database session.
+        """
+        config = self.get_config(name)
+        return config.provide_session(*args, **kwargs)
+
     @overload
     def get_pool(
-        self, name: type[Union[NoPoolSyncConfig[ConnectionT, DriverT], NoPoolAsyncConfig[ConnectionT, DriverT]]]
-    ) -> None: ...  # pyright: ignore[reportInvalidTypeVarUse]
+        self, name: "type[Union[NoPoolSyncConfig[ConnectionT, DriverT], NoPoolAsyncConfig[ConnectionT, DriverT]]]"
+    ) -> "None": ...  # pyright: ignore[reportInvalidTypeVarUse]
 
     @overload
-    def get_pool(self, name: type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]) -> type[PoolT]: ...  # pyright: ignore[reportInvalidTypeVarUse]
+    def get_pool(self, name: "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]") -> "type[PoolT]": ...  # pyright: ignore[reportInvalidTypeVarUse]
 
     @overload
-    def get_pool(self, name: type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]) -> Awaitable[type[PoolT]]: ...  # pyright: ignore[reportInvalidTypeVarUse]
+    def get_pool(self, name: "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]") -> "Awaitable[type[PoolT]]": ...  # pyright: ignore[reportInvalidTypeVarUse]
 
     def get_pool(
         self,
         name: Union[
-            type[NoPoolSyncConfig[ConnectionT, DriverT]],
-            type[NoPoolAsyncConfig[ConnectionT, DriverT]],
-            type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]],
-            type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]],
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
         ],
-    ) -> Union[type[PoolT], Awaitable[type[PoolT]], None]:
+    ) -> "Union[type[PoolT], Awaitable[type[PoolT]], None]":
         """Create and return a connection pool from the specified configuration.
 
         Args:
@@ -303,15 +467,33 @@ class SQLSpec:
             return cast("Union[type[PoolT], Awaitable[type[PoolT]]]", config.create_pool())
         return None
 
+    @overload
+    def close_pool(
+        self,
+        name: Union[
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+    ) -> "None": ...
+
+    @overload
+    def close_pool(
+        self,
+        name: Union[
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+        ],
+    ) -> "Awaitable[None]": ...
+
     def close_pool(
         self,
         name: Union[
-            type[NoPoolSyncConfig[ConnectionT, DriverT]],
-            type[NoPoolAsyncConfig[ConnectionT, DriverT]],
-            type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]],
-            type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]],
+            "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
+            "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
         ],
-    ) -> Optional[Awaitable[None]]:
+    ) -> "Optional[Awaitable[None]]":
         """Close the connection pool for the specified configuration.
 
         Args:
@@ -329,10 +511,12 @@ class SQLSpec:
 class CommonDriverAttributes(Generic[ConnectionT]):
     """Common attributes and methods for driver adapters."""
 
-    param_style: str = "?"
-    """The parameter style placeholder supported by the underlying database driver (e.g., '?', '%s')."""
+    dialect: str
+    """The SQL dialect supported by the underlying database driver (e.g., 'postgres', 'mysql')."""
     connection: ConnectionT
     """The connection to the underlying database."""
+    __supports_arrow__: ClassVar[bool] = False
+    """Indicates if the driver supports Apache Arrow operations."""
 
     def _connection(self, connection: "Optional[ConnectionT]" = None) -> "ConnectionT":
         return connection if connection is not None else self.connection
@@ -355,100 +539,123 @@ class CommonDriverAttributes(Generic[ConnectionT]):
             raise NotFoundError(msg)
         return item_or_none
 
-    def _process_sql_statement(self, sql: str) -> str:
-        """Perform any preprocessing of the SQL query string if needed.
-        Default implementation returns the SQL unchanged.
+    def _process_sql_params(
+        self, sql: str, parameters: "Optional[StatementParameterType]" = None, /, **kwargs: Any
+    ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
+        """Process SQL query and parameters using SQLStatement for validation and formatting.
 
         Args:
             sql: The SQL query string.
+            parameters: Parameters for the query.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            The processed SQL query string.
+            A tuple containing the processed SQL query and parameters.
         """
-        return sql
+        # Instantiate SQLStatement with parameters and kwargs for internal merging
+        stmt = SQLStatement(sql=sql, parameters=parameters, dialect=self.dialect, kwargs=kwargs or None)
+        # Process uses the merged parameters internally
+        return stmt.process()
 
-    def _process_sql_params(
-        self, sql: str, parameters: "Optional[StatementParameterType]" = None
-    ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
-        """Process SQL query and parameters for DB-API execution.
 
-        Converts named parameters (:name) to positional parameters specified by `self.param_style`
-        if the input parameters are a dictionary.
+class SyncArrowBulkOperationsMixin(Generic[ConnectionT]):
+    """Mixin for sync drivers supporting bulk Apache Arrow operations."""
+
+    __supports_arrow__: "ClassVar[bool]" = True
+
+    @abstractmethod
+    def select_arrow(  # pyright: ignore[reportUnknownParameterType]
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        **kwargs: Any,
+    ) -> "ArrowTable":  # pyright: ignore[reportUnknownReturnType]
+        """Execute a SQL query and return results as an Apache Arrow Table.
 
         Args:
             sql: The SQL query string.
-            parameters: The parameters for the query (dict, tuple, list, or None).
+            parameters: Parameters for the query.
+            connection: Optional connection override.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            A tuple containing the processed SQL string and the processed parameters
-            (always a tuple or None if the input was a dictionary, otherwise the original type).
-
-        Raises:
-            ValueError: If a named parameter in the SQL is not found in the dictionary
-                        or if a parameter in the dictionary is not used in the SQL.
+            An Apache Arrow Table containing the query results.
         """
-        if not isinstance(parameters, dict) or not parameters:
-            # If parameters are not a dict, or empty dict, assume positional/no params
-            # Let the underlying driver handle tuples/lists directly
-            return self._process_sql_statement(sql), parameters
-
-        processed_sql = ""
-        processed_params_list: list[Any] = []
-        last_end = 0
-        found_params: set[str] = set()
-
-        for match in PARAM_REGEX.finditer(sql):
-            if match.group("dquote") is not None or match.group("squote") is not None:
-                # Skip placeholders within quotes
-                continue
-
-            var_name = match.group("var_name")
-            if var_name is None:  # Should not happen with the regex, but safeguard
-                continue
-
-            if var_name not in parameters:
-                msg = f"Named parameter ':{var_name}' found in SQL but not provided in parameters dictionary."
-                raise ValueError(msg)
-
-            # Append segment before the placeholder + the leading character + the driver's positional placeholder
-            # The match.start("var_name") -1 includes the character before the ':'
-            processed_sql += sql[last_end : match.start("var_name")] + self.param_style
-            processed_params_list.append(parameters[var_name])
-            found_params.add(var_name)
-            last_end = match.end("var_name")
-
-        # Append the rest of the SQL string
-        processed_sql += sql[last_end:]
-
-        # Check if all provided parameters were used
-        unused_params = set(parameters.keys()) - found_params
-        if unused_params:
-            msg = f"Parameters provided but not found in SQL: {unused_params}"
-            # Depending on desired strictness, this could be a warning or an error
-            # For now, let's raise an error for clarity
-            raise ValueError(msg)
-
-        processed_params = tuple(processed_params_list)
-        # Pass the processed SQL through the driver-specific processor if needed
-        final_sql = self._process_sql_statement(processed_sql)
-        return final_sql, processed_params
+        raise NotImplementedError
 
 
 class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generic[ConnectionT]):
-    connection: ConnectionT
+    connection: "ConnectionT"
 
-    def __init__(self, connection: ConnectionT) -> None:
+    def __init__(self, connection: "ConnectionT", **kwargs: Any) -> None:
         self.connection = connection
 
+    @overload
     @abstractmethod
     def select(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Sequence[dict[str, Any]]": ...
+
+    @overload
+    @abstractmethod
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Sequence[ModelDTOT]": ...
+
+    @abstractmethod
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
         schema_type: Optional[type[ModelDTOT]] = None,
-    ) -> "list[Union[ModelDTOT, dict[str, Any]]]": ...
+        **kwargs: Any,
+    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]": ...
+
+    @overload
+    @abstractmethod
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+
+    @overload
+    @abstractmethod
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
 
     @abstractmethod
     def select_one(
@@ -456,29 +663,113 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[ModelDTOT]] = None,
+        **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]": ...
 
+    @overload
+    @abstractmethod
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[dict[str, Any]]": ...
+
+    @overload
+    @abstractmethod
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Optional[ModelDTOT]": ...
+
     @abstractmethod
     def select_one_or_none(
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[ModelDTOT]] = None,
+        **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]": ...
 
+    @overload
+    @abstractmethod
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Any": ...
+
+    @overload
+    @abstractmethod
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "T": ...
+
     @abstractmethod
     def select_value(
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[T]] = None,
-    ) -> "Union[Any, T]": ...
+        **kwargs: Any,
+    ) -> "Union[T, Any]": ...
+
+    @overload
+    @abstractmethod
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[Any]": ...
+
+    @overload
+    @abstractmethod
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "Optional[T]": ...
 
     @abstractmethod
     def select_value_or_none(
@@ -486,9 +777,11 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[T]] = None,
-    ) -> "Optional[Union[Any, T]]": ...
+        **kwargs: Any,
+    ) -> "Optional[Union[T, Any]]": ...
 
     @abstractmethod
     def insert_update_delete(
@@ -496,18 +789,48 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
+        **kwargs: Any,
     ) -> int: ...
 
+    @overload
+    @abstractmethod
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+
+    @overload
+    @abstractmethod
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
+
     @abstractmethod
     def insert_update_delete_returning(
         self,
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
         schema_type: Optional[type[ModelDTOT]] = None,
-    ) -> "Optional[Union[dict[str, Any], ModelDTOT]]": ...
+        **kwargs: Any,
+    ) -> "Union[ModelDTOT, dict[str, Any]]": ...
 
     @abstractmethod
     def execute_script(
@@ -515,92 +838,295 @@ class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generi
         sql: str,
         parameters: Optional[StatementParameterType] = None,
         /,
+        *,
         connection: Optional[ConnectionT] = None,
+        **kwargs: Any,
     ) -> str: ...
 
 
+class AsyncArrowBulkOperationsMixin(Generic[ConnectionT]):
+    """Mixin for async drivers supporting bulk Apache Arrow operations."""
+
+    __supports_arrow__: "ClassVar[bool]" = True
+
+    @abstractmethod
+    async def select_arrow(  # pyright: ignore[reportUnknownParameterType]
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        **kwargs: Any,
+    ) -> "ArrowTable":  # pyright: ignore[reportUnknownReturnType]
+        """Execute a SQL query and return results as an Apache Arrow Table.
+
+        Args:
+            sql: The SQL query string.
+            parameters: Parameters for the query.
+            connection: Optional connection override.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
+        Returns:
+            An Apache Arrow Table containing the query results.
+        """
+        raise NotImplementedError
+
+
 class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generic[ConnectionT]):
-    connection: ConnectionT
+    connection: "ConnectionT"
 
-    def __init__(self, connection: ConnectionT) -> None:
+    def __init__(self, connection: "ConnectionT") -> None:
         self.connection = connection
 
+    @overload
     @abstractmethod
     async def select(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
-    ) -> "list[Union[ModelDTOT, dict[str, Any]]]": ...
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Sequence[dict[str, Any]]": ...
+
+    @overload
+    @abstractmethod
+    async def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Sequence[ModelDTOT]": ...
 
+    @abstractmethod
+    async def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
+    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]": ...
+
+    @overload
     @abstractmethod
     async def select_one(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+
+    @overload
+    @abstractmethod
+    async def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
+
+    @abstractmethod
+    async def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]": ...
 
+    @overload
     @abstractmethod
     async def select_one_or_none(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[dict[str, Any]]": ...
+
+    @overload
+    @abstractmethod
+    async def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Optional[ModelDTOT]": ...
+
+    @abstractmethod
+    async def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]": ...
 
+    @overload
     @abstractmethod
     async def select_value(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[T]] = None,
-    ) -> "Union[Any, T]": ...
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Any": ...
 
+    @overload
+    @abstractmethod
+    async def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "T": ...
+
+    @abstractmethod
+    async def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "Optional[type[T]]" = None,
+        **kwargs: Any,
+    ) -> "Union[T, Any]": ...
+
+    @overload
     @abstractmethod
     async def select_value_or_none(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[T]] = None,
-    ) -> "Optional[Union[Any, T]]": ...
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[Any]": ...
+
+    @overload
+    @abstractmethod
+    async def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "Optional[T]": ...
+
+    @abstractmethod
+    async def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "Optional[type[T]]" = None,
+        **kwargs: Any,
+    ) -> "Optional[Union[T, Any]]": ...
 
     @abstractmethod
     async def insert_update_delete(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        **kwargs: Any,
     ) -> int: ...
 
+    @overload
     @abstractmethod
     async def insert_update_delete_returning(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
-    ) -> "Optional[Union[dict[str, Any], ModelDTOT]]": ...
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+
+    @overload
+    @abstractmethod
+    async def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
+
+    @abstractmethod
+    async def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
+    ) -> "Union[ModelDTOT, dict[str, Any]]": ...
 
     @abstractmethod
     async def execute_script(
         self,
         sql: str,
-        parameters: Optional[StatementParameterType] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional[ConnectionT] = None,
+        *,
+        connection: "Optional[ConnectionT]" = None,
+        **kwargs: Any,
     ) -> str: ...