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

sqlspec/_typing.py

@@ -1,8 +1,10 @@
+# ruff: noqa: RUF100, PLR0913, A002, DOC201, PLR6301
 """This is a simple wrapper around a few important classes in each library.
 
 This is used to ensure compatibility when one or more of the libraries are installed.
 """
 
+from collections.abc import Iterable, Mapping
 from enum import Enum
 from typing import (
     Any,
@@ -96,7 +98,7 @@ except ImportError:
 
         def validate_python(
             self,
-            object: Any,  # noqa: A002
+            object: Any,
             /,
             *,
             strict: "Optional[bool]" = None,
@@ -127,10 +129,7 @@ try:
 except ImportError:
     import enum
     from collections.abc import Iterable
-    from typing import TYPE_CHECKING, Callable, Optional, Union
-
-    if TYPE_CHECKING:
-        from collections.abc import Iterable
+    from typing import Callable, Optional, Union
 
     @dataclass_transform()
     @runtime_checkable
@@ -174,7 +173,6 @@ except ImportError:
             """Placeholder init"""
 
         def create_instance(self, **kwargs: Any) -> "T":
-            """Placeholder implementation"""
             return cast("T", kwargs)
 
         def update_instance(self, instance: "T", **kwargs: Any) -> "T":
@@ -198,11 +196,46 @@ EmptyType = Union[Literal[EmptyEnum.EMPTY], UnsetType]
 Empty: Final = EmptyEnum.EMPTY
 
 
+try:
+    from pyarrow import Table as ArrowTable
+
+    PYARROW_INSTALLED = True
+except ImportError:
+
+    @runtime_checkable
+    class ArrowTable(Protocol):  # type: ignore[no-redef]
+        """Placeholder Implementation"""
+
+        def to_batches(self, batch_size: int) -> Any: ...
+        def num_rows(self) -> int: ...
+        def num_columns(self) -> int: ...
+        def to_pydict(self) -> dict[str, Any]: ...
+        def to_string(self) -> str: ...
+        def from_arrays(
+            self,
+            arrays: list[Any],
+            names: "Optional[list[str]]" = None,
+            schema: "Optional[Any]" = None,
+            metadata: "Optional[Mapping[str, Any]]" = None,
+        ) -> Any: ...
+        def from_pydict(
+            self,
+            mapping: dict[str, Any],
+            schema: "Optional[Any]" = None,
+            metadata: "Optional[Mapping[str, Any]]" = None,
+        ) -> Any: ...
+        def from_batches(self, batches: Iterable[Any], schema: Optional[Any] = None) -> Any: ...
+
+    PYARROW_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+
 __all__ = (
     "LITESTAR_INSTALLED",
     "MSGSPEC_INSTALLED",
+    "PYARROW_INSTALLED",
     "PYDANTIC_INSTALLED",
     "UNSET",
+    "ArrowTable",
     "BaseModel",
     "DTOData",
     "DataclassProtocol",

sqlspec/adapters/adbc/__init__.py

@@ -1,7 +1,7 @@
-from sqlspec.adapters.adbc.config import Adbc
+from sqlspec.adapters.adbc.config import AdbcConfig
 from sqlspec.adapters.adbc.driver import AdbcDriver
 
 __all__ = (
-    "Adbc",
+    "AdbcConfig",
     "AdbcDriver",
 )

sqlspec/adapters/adbc/config.py

@@ -14,11 +14,11 @@ if TYPE_CHECKING:
     from collections.abc import Generator
 
 
-__all__ = ("Adbc",)
+__all__ = ("AdbcConfig",)
 
 
 @dataclass
-class Adbc(NoPoolSyncConfig["Connection", "AdbcDriver"]):
+class AdbcConfig(NoPoolSyncConfig["Connection", "AdbcDriver"]):
     """Configuration for ADBC connections.
 
     This class provides configuration options for ADBC database connections using the
@@ -55,17 +55,41 @@ class Adbc(NoPoolSyncConfig["Connection", "AdbcDriver"]):
         """
 
         if isinstance(self.driver_name, str):
-            if self.driver_name != "adbc_driver_sqlite.dbapi.connect" and "sqlite" in self.driver_name:
+            if self.driver_name != "adbc_driver_sqlite.dbapi.connect" and self.driver_name in {
+                "sqlite",
+                "sqlite3",
+                "adbc_driver_sqlite",
+            }:
                 self.driver_name = "adbc_driver_sqlite.dbapi.connect"
-            elif self.driver_name != "adbc_driver_duckdb.dbapi.connect" and "duckdb" in self.driver_name:
+            elif self.driver_name != "adbc_driver_duckdb.dbapi.connect" and self.driver_name in {
+                "duckdb",
+                "adbc_driver_duckdb",
+            }:
                 self.driver_name = "adbc_driver_duckdb.dbapi.connect"
-            elif self.driver_name != "adbc_driver_postgresql.dbapi.connect" and "postgres" in self.driver_name:
+            elif self.driver_name != "adbc_driver_postgresql.dbapi.connect" and self.driver_name in {
+                "postgres",
+                "adbc_driver_postgresql",
+                "postgresql",
+                "pg",
+            }:
                 self.driver_name = "adbc_driver_postgresql.dbapi.connect"
-            elif self.driver_name != "adbc_driver_snowflake.dbapi.connect" and "snowflake" in self.driver_name:
+            elif self.driver_name != "adbc_driver_snowflake.dbapi.connect" and self.driver_name in {
+                "snowflake",
+                "adbc_driver_snowflake",
+                "sf",
+            }:
                 self.driver_name = "adbc_driver_snowflake.dbapi.connect"
-            elif self.driver_name != "adbc_driver_bigquery.dbapi.connect" and "bigquery" in self.driver_name:
+            elif self.driver_name != "adbc_driver_bigquery.dbapi.connect" and self.driver_name in {
+                "bigquery",
+                "adbc_driver_bigquery",
+                "bq",
+            }:
                 self.driver_name = "adbc_driver_bigquery.dbapi.connect"
-            elif self.driver_name != "adbc_driver_flightsql.dbapi.connect" and "flightsql" in self.driver_name:
+            elif self.driver_name != "adbc_driver_flightsql.dbapi.connect" and self.driver_name in {
+                "flightsql",
+                "adbc_driver_flightsql",
+                "grpc",
+            }:
                 self.driver_name = "adbc_driver_flightsql.dbapi.connect"
             return self.driver_name
 
@@ -153,11 +177,10 @@ class Adbc(NoPoolSyncConfig["Connection", "AdbcDriver"]):
         """
         try:
             connect_func = self._get_connect_func()
-            _config = self.connection_config_dict
-            return connect_func(**_config)
+            return connect_func(**self.connection_config_dict)
         except Exception as e:
             # Include driver name in error message for better context
-            driver_name = self.driver_name if isinstance(self.driver_name, str) else "Unknown/Derived"
+            driver_name = self.driver_name if isinstance(self.driver_name, str) else "Unknown/Missing"
             # Use the potentially modified driver_path from _get_connect_func if available,
             # otherwise fallback to self.driver_name for the error message.
             # This requires _get_connect_func to potentially return the used path or store it.

sqlspec/adapters/adbc/driver.py

@@ -1,41 +1,73 @@
 import contextlib
+import logging
 import re
 from collections.abc import Generator
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, Union, cast
 
 from adbc_driver_manager.dbapi import Connection, Cursor
 
-from sqlspec.base import SyncDriverAdapterProtocol, T
+from sqlspec.base import SyncArrowBulkOperationsMixin, SyncDriverAdapterProtocol, T
+from sqlspec.exceptions import ParameterStyleMismatchError, SQLParsingError
+from sqlspec.statement import SQLStatement
+from sqlspec.typing import ArrowTable, StatementParameterType
 
 if TYPE_CHECKING:
-    from sqlspec.typing import ModelDTOT, StatementParameterType
+    from sqlspec.typing import ArrowTable, ModelDTOT, StatementParameterType
 
 __all__ = ("AdbcDriver",)
 
+logger = logging.getLogger("sqlspec")
+
 
-# Regex to find :param or %(param)s style placeholders, skipping those inside quotes
 PARAM_REGEX = re.compile(
-    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
+    r"""(?<![:\w\$]) # Avoid matching ::, \:, etc. and other vendor prefixes
+    (?:
+        (?P<dquote>"(?:[^"]|"")*") |     # Double-quoted strings
+        (?P<squote>'(?:[^']|'')*') |     # Single-quoted strings
+        (?P<comment>--.*?\n|\/\*.*?\*\/) | # SQL comments
+        (?P<lead>[:\$])(?P<var_name>[a-zA-Z_][a-zA-Z0-9_]*) # :name or $name identifier
+    )
     """,
-    re.VERBOSE,
+    re.VERBOSE | re.DOTALL,
 )
 
 
-class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
+class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterProtocol["Connection"]):
     """ADBC Sync Driver Adapter."""
 
     connection: Connection
+    __supports_arrow__: ClassVar[bool] = True
 
     def __init__(self, connection: "Connection") -> None:
         """Initialize the ADBC driver adapter."""
         self.connection = connection
-        # Potentially introspect connection.paramstyle here if needed in the future
-        # For now, assume 'qmark' based on typical ADBC DBAPI behavior
+        self.dialect = self._get_dialect(connection)
+
+    @staticmethod
+    def _get_dialect(connection: "Connection") -> str:  # noqa: PLR0911
+        """Get the database dialect based on the driver name.
+
+        Args:
+            connection: The ADBC connection object.
+
+        Returns:
+            The database dialect.
+        """
+        driver_name = connection.adbc_get_info()["vendor_name"].lower()
+        if "postgres" in driver_name:
+            return "postgres"
+        if "bigquery" in driver_name:
+            return "bigquery"
+        if "sqlite" in driver_name:
+            return "sqlite"
+        if "duckdb" in driver_name:
+            return "duckdb"
+        if "mysql" in driver_name:
+            return "mysql"
+        if "snowflake" in driver_name:
+            return "snowflake"
+        return "postgres"  # default to postgresql dialect
 
     @staticmethod
     def _cursor(connection: "Connection", *args: Any, **kwargs: Any) -> "Cursor":
@@ -51,79 +83,92 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
                 cursor.close()  # type: ignore[no-untyped-call]
 
     def _process_sql_params(
-        self, sql: str, parameters: "Optional[StatementParameterType]" = None
+        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 for DB-API execution.
-
-        Converts named parameters (:name or %(name)s) to positional parameters specified by `self.param_style`
-        if the input parameters are a dictionary.
-
-        Args:
-            sql: The SQL query string.
-            parameters: The parameters for the query (dict, tuple, list, or None).
-
-        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.
-        """
-        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
-
-            # Get name from whichever group matched
-            var_name = match.group("var_name_colon") or match.group("var_name_perc")
-
-            if var_name is None:  # Should not happen with the new regex structure
-                continue
-
-            if var_name not in parameters:
-                placeholder = match.group(0)  # Get the full matched placeholder
-                msg = f"Named parameter '{placeholder}' found in SQL but not provided in parameters dictionary."
-                raise ValueError(msg)
-
-            # Append segment before the placeholder
-            processed_sql += sql[last_end : match.start()]
-            # Append the driver's positional placeholder
-            processed_sql += self.param_style
-            processed_params_list.append(parameters[var_name])
-            found_params.add(var_name)
-            last_end = match.end()
-
-        # 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)
-
-        return self._process_sql_statement(processed_sql), tuple(processed_params_list)
+        # Determine effective parameter type *before* calling SQLStatement
+        merged_params_type = dict if kwargs else type(parameters)
+
+        # If ADBC + sqlite/duckdb + dictionary params, handle conversion manually
+        if self.dialect in {"sqlite", "duckdb"} and merged_params_type is dict:
+            logger.debug(
+                "ADBC/%s with dict params; bypassing SQLStatement conversion, manually converting to '?' positional.",
+                self.dialect,
+            )
+
+            # Combine parameters and kwargs into the actual dictionary to use
+            parameter_dict = {}  # type: ignore[var-annotated]
+            if isinstance(parameters, dict):
+                parameter_dict.update(parameters)
+            if kwargs:
+                parameter_dict.update(kwargs)
+
+            # Define regex locally to find :name or $name
+
+            processed_sql_parts: list[str] = []
+            ordered_params = []
+            last_end = 0
+            found_params_regex: list[str] = []
+
+            for match in PARAM_REGEX.finditer(sql):  # Use original sql
+                if match.group("dquote") or match.group("squote") or match.group("comment"):
+                    continue
+
+                if match.group("var_name"):
+                    var_name = match.group("var_name")
+                    leading_char = match.group("lead")  # : or $
+                    found_params_regex.append(var_name)
+                    # Use match span directly for replacement
+                    start = match.start()
+                    end = match.end()
+
+                    if var_name not in parameter_dict:
+                        msg = f"Named parameter '{leading_char}{var_name}' found in SQL but not provided. SQL: {sql}"
+                        raise SQLParsingError(msg)
+
+                    processed_sql_parts.extend((sql[last_end:start], "?"))  # Force ? style
+                    ordered_params.append(parameter_dict[var_name])
+                    last_end = end
+
+            processed_sql_parts.append(sql[last_end:])
+
+            if not found_params_regex and parameter_dict:
+                msg = f"ADBC/{self.dialect}: Dict params provided, but no :name or $name placeholders found. SQL: {sql}"
+                raise ParameterStyleMismatchError(msg)
+
+            # Key validation
+            provided_keys = set(parameter_dict.keys())
+            missing_keys = set(found_params_regex) - provided_keys
+            if missing_keys:
+                msg = (
+                    f"Named parameters found in SQL ({found_params_regex}) but not provided: {missing_keys}. SQL: {sql}"
+                )
+                raise SQLParsingError(msg)
+            extra_keys = provided_keys - set(found_params_regex)
+            if extra_keys:
+                logger.debug("Extra parameters provided for ADBC/%s: %s", self.dialect, extra_keys)
+                # Allow extra keys
+
+            final_sql = "".join(processed_sql_parts)
+            final_params = tuple(ordered_params)
+            return final_sql, final_params
+        # For all other cases (other dialects, or non-dict params for sqlite/duckdb),
+        # use the standard SQLStatement processing.
+        stmt = SQLStatement(sql=sql, parameters=parameters, dialect=self.dialect, kwargs=kwargs or None)
+        return stmt.process()
 
     def select(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
     ) -> "list[Union[ModelDTOT, dict[str, Any]]]":
         """Fetch data from the database.
 
@@ -131,7 +176,7 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             List of row data as either model instances or dictionaries.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             results = cursor.fetchall()  # pyright: ignore
@@ -149,8 +194,10 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]":
         """Fetch one row from the database.
 
@@ -158,7 +205,7 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             The first row of the query results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
@@ -173,8 +220,10 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
         """Fetch one row from the database.
 
@@ -182,7 +231,7 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             The first row of the query results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
@@ -198,8 +247,10 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[T]]" = None,
+        **kwargs: Any,
     ) -> "Union[T, Any]":
         """Fetch a single value from the database.
 
@@ -207,7 +258,7 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             The first value from the first row of results, or None if no results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
@@ -221,8 +272,10 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[T]]" = None,
+        **kwargs: Any,
     ) -> "Optional[Union[T, Any]]":
         """Fetch a single value from the database.
 
@@ -230,7 +283,7 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             The first value from the first row of results, or None if no results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
@@ -245,7 +298,9 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
+        **kwargs: Any,
     ) -> int:
         """Insert, update, or delete data from the database.
 
@@ -253,7 +308,7 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             Row count affected by the operation.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -264,8 +319,10 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
+        **kwargs: Any,
     ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
         """Insert, update, or delete data from the database and return result.
 
@@ -273,25 +330,31 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             The first row of results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
-        column_names: list[str] = []
-
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchall()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
-            if len(result) == 0:  # pyright: ignore[reportUnknownArgumentType]
+            if not result:
                 return None
+
+            first_row = result[0]
+
             column_names = [c[0] for c in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**dict(zip(column_names, result[0]))))  # pyright: ignore[reportUnknownArgumentType]
-            return dict(zip(column_names, result[0]))  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType]
+
+            result_dict = dict(zip(column_names, first_row))
+
+            if schema_type is None:
+                return result_dict
+            return cast("ModelDTOT", schema_type(**result_dict))
 
     def execute_script(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
+        *,
         connection: Optional["Connection"] = None,
+        **kwargs: Any,
     ) -> str:
         """Execute a script.
 
@@ -305,29 +368,25 @@ class AdbcDriver(SyncDriverAdapterProtocol["Connection"]):
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             return cast("str", cursor.statusmessage) if hasattr(cursor, "statusmessage") else "DONE"  # pyright: ignore[reportUnknownMemberType,reportAttributeAccessIssue]
 
-    def execute_script_returning(
+    # --- Arrow Bulk Operations ---
+
+    def select_arrow(  # pyright: ignore[reportUnknownParameterType]
         self,
         sql: str,
-        parameters: Optional["StatementParameterType"] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
-        connection: Optional["Connection"] = None,
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-    ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
-        """Execute a script and return result.
+        *,
+        connection: "Optional[Connection]" = None,
+        **kwargs: Any,
+    ) -> "ArrowTable":
+        """Execute a SQL query and return results as an Apache Arrow Table.
 
         Returns:
-            The first row of results.
+            The results of the query as an Apache Arrow Table.
         """
-        connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters)
-        column_names: list[str] = []
+        conn = self._connection(connection)
+        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
 
-        with self._with_cursor(connection) as cursor:
+        with self._with_cursor(conn) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
-            result = cursor.fetchall()  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
-            if len(result) == 0:  # pyright: ignore[reportUnknownArgumentType]
-                return None
-            column_names = [c[0] for c in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**dict(zip(column_names, result[0]))))  # pyright: ignore[reportUnknownArgumentType]
-            return dict(zip(column_names, result[0]))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
+            return cast("ArrowTable", cursor.fetch_arrow_table())  # pyright: ignore[reportUnknownMemberType]

sqlspec/adapters/aiosqlite/__init__.py

@@ -1,7 +1,7 @@
-from sqlspec.adapters.aiosqlite.config import Aiosqlite
+from sqlspec.adapters.aiosqlite.config import AiosqliteConfig
 from sqlspec.adapters.aiosqlite.driver import AiosqliteDriver
 
 __all__ = (
-    "Aiosqlite",
+    "AiosqliteConfig",
     "AiosqliteDriver",
 )

sqlspec/adapters/aiosqlite/config.py

@@ -15,11 +15,11 @@ if TYPE_CHECKING:
     from typing import Literal
 
 
-__all__ = ("Aiosqlite",)
+__all__ = ("AiosqliteConfig",)
 
 
 @dataclass
-class Aiosqlite(NoPoolAsyncConfig["Connection", "AiosqliteDriver"]):
+class AiosqliteConfig(NoPoolAsyncConfig["Connection", "AiosqliteDriver"]):
     """Configuration for Aiosqlite database connections.
 
     This class provides configuration options for Aiosqlite database connections, wrapping all parameters