sqlspec 0.25.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

sqlspec/adapters/duckdb/config.py

@@ -2,7 +2,7 @@
 
 from collections.abc import Sequence
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, TypedDict, Union, cast
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict
 
 from typing_extensions import NotRequired
 
@@ -26,7 +26,7 @@ __all__ = (
 )
 
 
-class DuckDBConnectionParams(TypedDict, total=False):
+class DuckDBConnectionParams(TypedDict):
     """DuckDB connection parameters."""
 
     database: NotRequired[str]
@@ -65,7 +65,7 @@ class DuckDBConnectionParams(TypedDict, total=False):
     extra: NotRequired[dict[str, Any]]
 
 
-class DuckDBPoolParams(DuckDBConnectionParams, total=False):
+class DuckDBPoolParams(DuckDBConnectionParams):
     """Complete pool configuration for DuckDB adapter.
 
     Combines standardized pool parameters with DuckDB-specific connection parameters.
@@ -77,7 +77,7 @@ class DuckDBPoolParams(DuckDBConnectionParams, total=False):
     pool_recycle_seconds: NotRequired[int]
 
 
-class DuckDBExtensionConfig(TypedDict, total=False):
+class DuckDBExtensionConfig(TypedDict):
     """DuckDB extension configuration for auto-management."""
 
     name: str
@@ -93,7 +93,7 @@ class DuckDBExtensionConfig(TypedDict, total=False):
     """Force reinstallation of the extension."""
 
 
-class DuckDBSecretConfig(TypedDict, total=False):
+class DuckDBSecretConfig(TypedDict):
     """DuckDB secret configuration for AI/API integrations."""
 
     secret_type: str
@@ -109,15 +109,25 @@ class DuckDBSecretConfig(TypedDict, total=False):
     """Scope of the secret (LOCAL or PERSISTENT)."""
 
 
-class DuckDBDriverFeatures(TypedDict, total=False):
-    """TypedDict for DuckDB driver features configuration."""
+class DuckDBDriverFeatures(TypedDict):
+    """TypedDict for DuckDB driver features configuration.
+
+    Attributes:
+        extensions: List of extensions to install/load on connection creation.
+        secrets: List of secrets to create for AI/API integrations.
+        on_connection_create: Callback executed when connection is created.
+        json_serializer: Custom JSON serializer for dict/list parameter conversion.
+            Defaults to sqlspec.utils.serializers.to_json if not provided.
+        enable_uuid_conversion: Enable automatic UUID string conversion.
+            When True (default), UUID strings are automatically converted to UUID objects.
+            When False, UUID strings are treated as regular strings.
+    """
 
     extensions: NotRequired[Sequence[DuckDBExtensionConfig]]
-    """List of extensions to install/load on connection creation."""
     secrets: NotRequired[Sequence[DuckDBSecretConfig]]
-    """List of secrets to create for AI/API integrations."""
-    on_connection_create: NotRequired["Callable[[DuckDBConnection], Optional[DuckDBConnection]]"]
-    """Callback executed when connection is created."""
+    on_connection_create: NotRequired["Callable[[DuckDBConnection], DuckDBConnection | None]"]
+    json_serializer: NotRequired["Callable[[Any], str]"]
+    enable_uuid_conversion: NotRequired[bool]
 
 
 class DuckDBConfig(SyncDatabaseConfig[DuckDBConnection, DuckDBConnectionPool, DuckDBDriver]):
@@ -131,26 +141,66 @@ class DuckDBConfig(SyncDatabaseConfig[DuckDBConnection, DuckDBConnectionPool, Du
     - Auto configuration settings
     - Arrow integration
     - Direct file querying capabilities
+    - Configurable type handlers for JSON serialization and UUID conversion
 
     DuckDB Connection Pool Configuration:
     - Default pool size is 1-4 connections (DuckDB uses single connection by default)
     - Connection recycling is set to 24 hours by default (set to 0 to disable)
     - Shared memory databases use `:memory:shared_db` for proper concurrency
+
+    Type Handler Configuration via driver_features:
+    - `json_serializer`: Custom JSON serializer for dict/list parameters.
+      Defaults to `sqlspec.utils.serializers.to_json` if not provided.
+      Example: `json_serializer=msgspec.json.encode(...).decode('utf-8')`
+
+    - `enable_uuid_conversion`: Enable automatic UUID string conversion (default: True).
+      When True, UUID strings in query results are automatically converted to UUID objects.
+      When False, UUID strings are treated as regular strings.
+
+    Example:
+        >>> import msgspec
+        >>> from sqlspec.adapters.duckdb import DuckDBConfig
+        >>>
+        >>> # Custom JSON serializer
+        >>> def custom_json(obj):
+        ...     return msgspec.json.encode(obj).decode("utf-8")
+        >>>
+        >>> config = DuckDBConfig(
+        ...     pool_config={"database": ":memory:"},
+        ...     driver_features={
+        ...         "json_serializer": custom_json,
+        ...         "enable_uuid_conversion": False,
+        ...     },
+        ... )
     """
 
     driver_type: "ClassVar[type[DuckDBDriver]]" = DuckDBDriver
     connection_type: "ClassVar[type[DuckDBConnection]]" = DuckDBConnection
+    supports_transactional_ddl: "ClassVar[bool]" = True
 
     def __init__(
         self,
         *,
-        pool_config: "Optional[Union[DuckDBPoolParams, dict[str, Any]]]" = None,
-        pool_instance: "Optional[DuckDBConnectionPool]" = None,
-        migration_config: Optional[dict[str, Any]] = None,
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[Union[DuckDBDriverFeatures, dict[str, Any]]]" = None,
+        pool_config: "DuckDBPoolParams | dict[str, Any] | None" = None,
+        pool_instance: "DuckDBConnectionPool | None" = None,
+        migration_config: dict[str, Any] | None = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "DuckDBDriverFeatures | dict[str, Any] | None" = None,
+        bind_key: "str | None" = None,
+        extension_config: "dict[str, dict[str, Any]] | None" = None,
     ) -> None:
-        """Initialize DuckDB configuration."""
+        """Initialize DuckDB configuration.
+
+        Args:
+            pool_config: Pool configuration parameters
+            pool_instance: Pre-created pool instance
+            migration_config: Migration configuration
+            statement_config: Statement configuration override
+            driver_features: DuckDB-specific driver features including json_serializer
+                and enable_uuid_conversion options
+            bind_key: Optional unique identifier for this configuration
+            extension_config: Extension-specific configuration (e.g., Litestar plugin settings)
+        """
         if pool_config is None:
             pool_config = {}
         if "database" not in pool_config:
@@ -159,12 +209,18 @@ class DuckDBConfig(SyncDatabaseConfig[DuckDBConnection, DuckDBConnectionPool, Du
         if pool_config.get("database") in {":memory:", ""}:
             pool_config["database"] = ":memory:shared_db"
 
+        processed_features = dict(driver_features) if driver_features else {}
+        if "enable_uuid_conversion" not in processed_features:
+            processed_features["enable_uuid_conversion"] = True
+
         super().__init__(
+            bind_key=bind_key,
             pool_config=dict(pool_config),
             pool_instance=pool_instance,
             migration_config=migration_config,
             statement_config=statement_config or duckdb_statement_config,
-            driver_features=cast("dict[str, Any]", driver_features),
+            driver_features=processed_features,
+            extension_config=extension_config,
         )
 
     def _get_connection_config_dict(self) -> "dict[str, Any]":
@@ -245,7 +301,7 @@ class DuckDBConfig(SyncDatabaseConfig[DuckDBConnection, DuckDBConnectionPool, Du
 
     @contextmanager
     def provide_session(
-        self, *args: Any, statement_config: "Optional[StatementConfig]" = None, **kwargs: Any
+        self, *args: Any, statement_config: "StatementConfig | None" = None, **kwargs: Any
     ) -> "Generator[DuckDBDriver, None, None]":
         """Provide a DuckDB driver session context manager.
 
@@ -258,7 +314,11 @@ class DuckDBConfig(SyncDatabaseConfig[DuckDBConnection, DuckDBConnectionPool, Du
             A context manager that yields a DuckDBDriver instance.
         """
         with self.provide_connection(*args, **kwargs) as connection:
-            driver = self.driver_type(connection=connection, statement_config=statement_config or self.statement_config)
+            driver = self.driver_type(
+                connection=connection,
+                statement_config=statement_config or self.statement_config,
+                driver_features=self.driver_features,
+            )
             yield driver
 
     def get_signature_namespace(self) -> "dict[str, type[Any]]":

sqlspec/adapters/duckdb/data_dictionary.py

@@ -0,0 +1,163 @@
+"""DuckDB-specific data dictionary for metadata queries."""
+
+import re
+from typing import TYPE_CHECKING, Any, cast
+
+from sqlspec.driver import SyncDataDictionaryBase, SyncDriverAdapterBase, VersionInfo
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlspec.adapters.duckdb.driver import DuckDBDriver
+
+logger = get_logger("adapters.duckdb.data_dictionary")
+
+# Compiled regex patterns
+DUCKDB_VERSION_PATTERN = re.compile(r"v?(\d+)\.(\d+)\.(\d+)")
+
+__all__ = ("DuckDBSyncDataDictionary",)
+
+
+class DuckDBSyncDataDictionary(SyncDataDictionaryBase):
+    """DuckDB-specific sync data dictionary."""
+
+    def get_version(self, driver: SyncDriverAdapterBase) -> "VersionInfo | None":
+        """Get DuckDB database version information.
+
+        Args:
+            driver: DuckDB driver instance
+
+        Returns:
+            DuckDB version information or None if detection fails
+        """
+        version_str = cast("DuckDBDriver", driver).select_value("SELECT version()")
+        if not version_str:
+            logger.warning("No DuckDB version information found")
+            return None
+
+        # Parse version like "v0.9.2" or "0.9.2"
+        version_match = DUCKDB_VERSION_PATTERN.search(str(version_str))
+        if not version_match:
+            logger.warning("Could not parse DuckDB version: %s", version_str)
+            return None
+
+        major, minor, patch = map(int, version_match.groups())
+        version_info = VersionInfo(major, minor, patch)
+        logger.debug("Detected DuckDB version: %s", version_info)
+        return version_info
+
+    def get_feature_flag(self, driver: SyncDriverAdapterBase, feature: str) -> bool:
+        """Check if DuckDB database supports a specific feature.
+
+        Args:
+            driver: DuckDB driver instance
+            feature: Feature name to check
+
+        Returns:
+            True if feature is supported, False otherwise
+        """
+        version_info = self.get_version(driver)
+        if not version_info:
+            return False
+
+        feature_checks: dict[str, Callable[..., bool]] = {
+            "supports_json": lambda _: True,  # DuckDB has excellent JSON support
+            "supports_arrays": lambda _: True,  # LIST type
+            "supports_maps": lambda _: True,  # MAP type
+            "supports_structs": lambda _: True,  # STRUCT type
+            "supports_returning": lambda v: v >= VersionInfo(0, 8, 0),
+            "supports_upsert": lambda v: v >= VersionInfo(0, 8, 0),
+            "supports_window_functions": lambda _: True,
+            "supports_cte": lambda _: True,
+            "supports_transactions": lambda _: True,
+            "supports_prepared_statements": lambda _: True,
+            "supports_schemas": lambda _: True,
+            "supports_uuid": lambda _: True,
+        }
+
+        if feature in feature_checks:
+            return bool(feature_checks[feature](version_info))
+
+        return False
+
+    def get_optimal_type(self, driver: SyncDriverAdapterBase, type_category: str) -> str:  # pyright: ignore
+        """Get optimal DuckDB type for a category.
+
+        Args:
+            driver: DuckDB driver instance
+            type_category: Type category
+
+        Returns:
+            DuckDB-specific type name
+        """
+        type_map = {
+            "json": "JSON",
+            "uuid": "UUID",
+            "boolean": "BOOLEAN",
+            "timestamp": "TIMESTAMP",
+            "text": "TEXT",
+            "blob": "BLOB",
+            "array": "LIST",
+            "map": "MAP",
+            "struct": "STRUCT",
+        }
+        return type_map.get(type_category, "VARCHAR")
+
+    def get_columns(
+        self, driver: SyncDriverAdapterBase, table: str, schema: "str | None" = None
+    ) -> "list[dict[str, Any]]":
+        """Get column information for a table using information_schema.
+
+        Args:
+            driver: DuckDB driver instance
+            table: Table name to query columns for
+            schema: Schema name (None for default)
+
+        Returns:
+            List of column metadata dictionaries with keys:
+                - column_name: Name of the column
+                - data_type: DuckDB data type
+                - nullable: Whether column allows NULL (YES/NO)
+                - column_default: Default value if any
+        """
+        duckdb_driver = cast("DuckDBDriver", driver)
+
+        if schema:
+            sql = f"""
+                SELECT column_name, data_type, is_nullable, column_default
+                FROM information_schema.columns
+                WHERE table_name = '{table}' AND table_schema = '{schema}'
+                ORDER BY ordinal_position
+            """
+        else:
+            sql = f"""
+                SELECT column_name, data_type, is_nullable, column_default
+                FROM information_schema.columns
+                WHERE table_name = '{table}'
+                ORDER BY ordinal_position
+            """
+
+        result = duckdb_driver.execute(sql)
+        return result.data or []
+
+    def list_available_features(self) -> "list[str]":
+        """List available DuckDB feature flags.
+
+        Returns:
+            List of supported feature names
+        """
+        return [
+            "supports_json",
+            "supports_arrays",
+            "supports_maps",
+            "supports_structs",
+            "supports_returning",
+            "supports_upsert",
+            "supports_window_functions",
+            "supports_cte",
+            "supports_transactions",
+            "supports_prepared_statements",
+            "supports_schemas",
+            "supports_uuid",
+        ]

sqlspec/adapters/duckdb/driver.py

@@ -1,16 +1,32 @@
 """DuckDB driver implementation."""
 
-from typing import TYPE_CHECKING, Any, Final, Optional
+import datetime
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, Final
 
 import duckdb
 from sqlglot import exp
 
+from sqlspec.adapters.duckdb.data_dictionary import DuckDBSyncDataDictionary
+from sqlspec.adapters.duckdb.type_converter import DuckDBTypeConverter
 from sqlspec.core.cache import get_cache_config
 from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
 from sqlspec.core.statement import SQL, StatementConfig
 from sqlspec.driver import SyncDriverAdapterBase
-from sqlspec.exceptions import SQLParsingError, SQLSpecError
+from sqlspec.exceptions import (
+    CheckViolationError,
+    DataError,
+    ForeignKeyViolationError,
+    IntegrityError,
+    NotFoundError,
+    NotNullViolationError,
+    OperationalError,
+    SQLParsingError,
+    SQLSpecError,
+    UniqueViolationError,
+)
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.serializers import to_json
 
 if TYPE_CHECKING:
     from contextlib import AbstractContextManager
@@ -18,11 +34,14 @@ if TYPE_CHECKING:
     from sqlspec.adapters.duckdb._types import DuckDBConnection
     from sqlspec.core.result import SQLResult
     from sqlspec.driver import ExecutionResult
+    from sqlspec.driver._sync import SyncDataDictionaryBase
 
 __all__ = ("DuckDBCursor", "DuckDBDriver", "DuckDBExceptionHandler", "duckdb_statement_config")
 
 logger = get_logger("adapters.duckdb")
 
+_type_converter = DuckDBTypeConverter()
+
 
 duckdb_statement_config = StatementConfig(
     dialect="duckdb",
@@ -31,7 +50,15 @@ duckdb_statement_config = StatementConfig(
         supported_parameter_styles={ParameterStyle.QMARK, ParameterStyle.NUMERIC, ParameterStyle.NAMED_DOLLAR},
         default_execution_parameter_style=ParameterStyle.QMARK,
         supported_execution_parameter_styles={ParameterStyle.QMARK, ParameterStyle.NUMERIC},
-        type_coercion_map={},
+        type_coercion_map={
+            bool: int,
+            datetime.datetime: lambda v: v.isoformat(),
+            datetime.date: lambda v: v.isoformat(),
+            Decimal: str,
+            dict: to_json,
+            list: to_json,
+            str: _type_converter.convert_if_detected,
+        },
         has_native_list_expansion=True,
         needs_static_script_compilation=False,
         preserve_parameter_format=True,
@@ -54,14 +81,13 @@ class DuckDBCursor:
 
     def __init__(self, connection: "DuckDBConnection") -> None:
         self.connection = connection
-        self.cursor: Optional[Any] = None
+        self.cursor: Any | None = None
 
     def __enter__(self) -> Any:
         self.cursor = self.connection.cursor()
         return self.cursor
 
-    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
-        _ = (exc_type, exc_val, exc_tb)
+    def __exit__(self, *_: Any) -> None:
         if self.cursor is not None:
             self.cursor.close()
 
@@ -69,8 +95,8 @@ class DuckDBCursor:
 class DuckDBExceptionHandler:
     """Context manager for handling DuckDB database exceptions.
 
-    Catches DuckDB-specific exceptions and converts them to appropriate
-    SQLSpec exception types for consistent error handling.
+    Uses exception type and message-based detection to map DuckDB errors
+    to specific SQLSpec exceptions for better error handling.
     """
 
     __slots__ = ()
@@ -79,41 +105,93 @@ class DuckDBExceptionHandler:
         return None
 
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        _ = exc_tb
         if exc_type is None:
             return
+        self._map_duckdb_exception(exc_type, exc_val)
 
-        if issubclass(exc_type, duckdb.IntegrityError):
-            e = exc_val
-            msg = f"DuckDB integrity constraint violation: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, duckdb.OperationalError):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "syntax" in error_msg or "parse" in error_msg:
-                msg = f"DuckDB SQL syntax error: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"DuckDB operational error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, duckdb.ProgrammingError):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "syntax" in error_msg or "parse" in error_msg:
-                msg = f"DuckDB SQL syntax error: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"DuckDB programming error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, duckdb.Error):
-            e = exc_val
-            msg = f"DuckDB error: {e}"
-            raise SQLSpecError(msg) from e
-        if issubclass(exc_type, Exception):
-            e = exc_val
-            error_msg = str(e).lower()
-            if "parse" in error_msg or "syntax" in error_msg:
-                msg = f"SQL parsing failed: {e}"
-                raise SQLParsingError(msg) from e
-            msg = f"Unexpected database operation error: {e}"
-            raise SQLSpecError(msg) from e
+    def _map_duckdb_exception(self, exc_type: Any, e: Any) -> None:
+        """Map DuckDB exception to SQLSpec exception.
+
+        Uses exception type and message-based detection.
+
+        Args:
+            exc_type: Exception type
+            e: Exception instance
+        """
+        error_msg = str(e).lower()
+        exc_name = exc_type.__name__ if hasattr(exc_type, "__name__") else str(exc_type)
+
+        if "constraintexception" in exc_name.lower():
+            self._handle_constraint_exception(e, error_msg)
+        elif "catalogexception" in exc_name.lower():
+            self._raise_not_found_error(e)
+        elif "parserexception" in exc_name.lower() or "binderexception" in exc_name.lower():
+            self._raise_parsing_error(e)
+        elif "ioexception" in exc_name.lower():
+            self._raise_operational_error(e)
+        elif "conversionexception" in exc_name.lower() or "type mismatch" in error_msg:
+            self._raise_data_error(e)
+        else:
+            self._raise_generic_error(e)
+
+    def _handle_constraint_exception(self, e: Any, error_msg: str) -> None:
+        """Handle constraint exceptions using message-based detection.
+
+        Args:
+            e: Exception instance
+            error_msg: Lowercase error message
+        """
+        if "unique" in error_msg or "duplicate" in error_msg:
+            self._raise_unique_violation(e)
+        elif "foreign key" in error_msg or "violates foreign key" in error_msg:
+            self._raise_foreign_key_violation(e)
+        elif "not null" in error_msg or "null value" in error_msg:
+            self._raise_not_null_violation(e)
+        elif "check constraint" in error_msg or "check condition" in error_msg:
+            self._raise_check_violation(e)
+        else:
+            self._raise_integrity_error(e)
+
+    def _raise_unique_violation(self, e: Any) -> None:
+        msg = f"DuckDB unique constraint violation: {e}"
+        raise UniqueViolationError(msg) from e
+
+    def _raise_foreign_key_violation(self, e: Any) -> None:
+        msg = f"DuckDB foreign key constraint violation: {e}"
+        raise ForeignKeyViolationError(msg) from e
+
+    def _raise_not_null_violation(self, e: Any) -> None:
+        msg = f"DuckDB not-null constraint violation: {e}"
+        raise NotNullViolationError(msg) from e
+
+    def _raise_check_violation(self, e: Any) -> None:
+        msg = f"DuckDB check constraint violation: {e}"
+        raise CheckViolationError(msg) from e
+
+    def _raise_integrity_error(self, e: Any) -> None:
+        msg = f"DuckDB integrity constraint violation: {e}"
+        raise IntegrityError(msg) from e
+
+    def _raise_not_found_error(self, e: Any) -> None:
+        msg = f"DuckDB catalog error: {e}"
+        raise NotFoundError(msg) from e
+
+    def _raise_parsing_error(self, e: Any) -> None:
+        msg = f"DuckDB SQL parsing error: {e}"
+        raise SQLParsingError(msg) from e
+
+    def _raise_operational_error(self, e: Any) -> None:
+        msg = f"DuckDB operational error: {e}"
+        raise OperationalError(msg) from e
+
+    def _raise_data_error(self, e: Any) -> None:
+        msg = f"DuckDB data error: {e}"
+        raise DataError(msg) from e
+
+    def _raise_generic_error(self, e: Any) -> None:
+        msg = f"DuckDB database error: {e}"
+        raise SQLSpecError(msg) from e
 
 
 class DuckDBDriver(SyncDriverAdapterBase):
@@ -127,14 +205,14 @@ class DuckDBDriver(SyncDriverAdapterBase):
     the sqlspec.core modules for statement processing and caching.
     """
 
-    __slots__ = ()
+    __slots__ = ("_data_dictionary",)
     dialect = "duckdb"
 
     def __init__(
         self,
         connection: "DuckDBConnection",
-        statement_config: "Optional[StatementConfig]" = None,
-        driver_features: "Optional[dict[str, Any]]" = None,
+        statement_config: "StatementConfig | None" = None,
+        driver_features: "dict[str, Any] | None" = None,
     ) -> None:
         if statement_config is None:
             cache_config = get_cache_config()
@@ -146,7 +224,40 @@ class DuckDBDriver(SyncDriverAdapterBase):
             )
             statement_config = updated_config
 
+        if driver_features:
+            json_serializer = driver_features.get("json_serializer")
+            enable_uuid_conversion = driver_features.get("enable_uuid_conversion", True)
+
+            if json_serializer or not enable_uuid_conversion:
+                type_converter = DuckDBTypeConverter(enable_uuid_conversion=enable_uuid_conversion)
+                type_coercion_map = dict(statement_config.parameter_config.type_coercion_map)
+
+                if json_serializer:
+                    type_coercion_map[dict] = json_serializer
+                    type_coercion_map[list] = json_serializer
+
+                if not enable_uuid_conversion:
+                    type_coercion_map[str] = type_converter.convert_if_detected
+
+                param_config = statement_config.parameter_config
+                updated_param_config = ParameterStyleConfig(
+                    default_parameter_style=param_config.default_parameter_style,
+                    supported_parameter_styles=param_config.supported_parameter_styles,
+                    supported_execution_parameter_styles=param_config.supported_execution_parameter_styles,
+                    default_execution_parameter_style=param_config.default_execution_parameter_style,
+                    type_coercion_map=type_coercion_map,
+                    has_native_list_expansion=param_config.has_native_list_expansion,
+                    needs_static_script_compilation=param_config.needs_static_script_compilation,
+                    allow_mixed_parameter_styles=param_config.allow_mixed_parameter_styles,
+                    preserve_parameter_format=param_config.preserve_parameter_format,
+                    preserve_original_params_for_many=param_config.preserve_original_params_for_many,
+                    output_transformer=param_config.output_transformer,
+                    ast_transformer=param_config.ast_transformer,
+                )
+                statement_config = statement_config.replace(parameter_config=updated_param_config)
+
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
+        self._data_dictionary: SyncDataDictionaryBase | None = None
 
     def with_cursor(self, connection: "DuckDBConnection") -> "DuckDBCursor":
         """Create context manager for DuckDB cursor.
@@ -167,7 +278,7 @@ class DuckDBDriver(SyncDriverAdapterBase):
         """
         return DuckDBExceptionHandler()
 
-    def _try_special_handling(self, cursor: Any, statement: SQL) -> "Optional[SQLResult]":
+    def _try_special_handling(self, cursor: Any, statement: SQL) -> "SQLResult | None":
         """Handle DuckDB-specific special operations.
 
         DuckDB does not require special operation handling, so this method
@@ -282,7 +393,7 @@ class DuckDBDriver(SyncDriverAdapterBase):
             column_names = [col[0] for col in cursor.description or []]
 
             if fetched_data and isinstance(fetched_data[0], tuple):
-                dict_data = [dict(zip(column_names, row)) for row in fetched_data]
+                dict_data = [dict(zip(column_names, row, strict=False)) for row in fetched_data]
             else:
                 dict_data = fetched_data
 
@@ -325,3 +436,14 @@ class DuckDBDriver(SyncDriverAdapterBase):
         except duckdb.Error as e:
             msg = f"Failed to commit DuckDB transaction: {e}"
             raise SQLSpecError(msg) from e
+
+    @property
+    def data_dictionary(self) -> "SyncDataDictionaryBase":
+        """Get the data dictionary for this driver.
+
+        Returns:
+            Data dictionary instance for metadata queries
+        """
+        if self._data_dictionary is None:
+            self._data_dictionary = DuckDBSyncDataDictionary()
+        return self._data_dictionary

sqlspec/adapters/duckdb/litestar/__init__.py

@@ -0,0 +1,5 @@
+"""Litestar integration for DuckDB adapter."""
+
+from sqlspec.adapters.duckdb.litestar.store import DuckdbStore
+
+__all__ = ("DuckdbStore",)