sqlspec 0.24.1__py3-none-any.whl → 0.26.0__py3-none-any.whl

sqlspec/adapters/psycopg/driver.py

@@ -14,6 +14,7 @@ PostgreSQL Features:
 - PostgreSQL-specific error handling
 """
 
+import datetime
 import io
 from typing import TYPE_CHECKING, Any, Optional
 
@@ -32,7 +33,9 @@ from sqlspec.utils.serializers import to_json
 if TYPE_CHECKING:
     from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
+    from sqlspec.driver._async import AsyncDataDictionaryBase
     from sqlspec.driver._common import ExecutionResult
+    from sqlspec.driver._sync import SyncDataDictionaryBase
 
 logger = get_logger("adapters.psycopg")
 
@@ -94,7 +97,12 @@ psycopg_statement_config = StatementConfig(
             ParameterStyle.NAMED_PYFORMAT,
             ParameterStyle.NUMERIC,
         },
-        type_coercion_map={dict: to_json},
+        type_coercion_map={
+            dict: to_json,
+            datetime.datetime: lambda x: x,
+            datetime.date: lambda x: x,
+            datetime.time: lambda x: x,
+        },
         has_native_list_expansion=True,
         needs_static_script_compilation=False,
         preserve_parameter_format=True,
@@ -125,8 +133,7 @@ class PsycopgSyncCursor:
         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()
 
@@ -187,7 +194,7 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
     bulk data transfer, and PostgreSQL-specific error handling.
     """
 
-    __slots__ = ()
+    __slots__ = ("_data_dictionary",)
     dialect = "postgres"
 
     def __init__(
@@ -207,6 +214,7 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
             statement_config = default_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
+        self._data_dictionary: Optional[SyncDataDictionaryBase] = None
 
     def with_cursor(self, connection: PsycopgSyncConnection) -> PsycopgSyncCursor:
         """Create context manager for PostgreSQL cursor."""
@@ -411,6 +419,19 @@ class PsycopgSyncDriver(SyncDriverAdapterBase):
         affected_rows = cursor.rowcount if cursor.rowcount and cursor.rowcount > 0 else 0
         return self.create_execution_result(cursor, rowcount_override=affected_rows)
 
+    @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:
+            from sqlspec.adapters.psycopg.data_dictionary import PostgresSyncDataDictionary
+
+            self._data_dictionary = PostgresSyncDataDictionary()
+        return self._data_dictionary
+
 
 class PsycopgAsyncCursor:
     """Async context manager for PostgreSQL psycopg cursor management."""
@@ -488,7 +509,7 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
     and async pub/sub support.
     """
 
-    __slots__ = ()
+    __slots__ = ("_data_dictionary",)
     dialect = "postgres"
 
     def __init__(
@@ -508,6 +529,7 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
             statement_config = default_config
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
+        self._data_dictionary: Optional[AsyncDataDictionaryBase] = None
 
     def with_cursor(self, connection: "PsycopgAsyncConnection") -> "PsycopgAsyncCursor":
         """Create async context manager for PostgreSQL cursor."""
@@ -714,3 +736,16 @@ class PsycopgAsyncDriver(AsyncDriverAdapterBase):
 
         affected_rows = cursor.rowcount if cursor.rowcount and cursor.rowcount > 0 else 0
         return self.create_execution_result(cursor, rowcount_override=affected_rows)
+
+    @property
+    def data_dictionary(self) -> "AsyncDataDictionaryBase":
+        """Get the data dictionary for this driver.
+
+        Returns:
+            Data dictionary instance for metadata queries
+        """
+        if self._data_dictionary is None:
+            from sqlspec.adapters.psycopg.data_dictionary import PostgresAsyncDataDictionary
+
+            self._data_dictionary = PostgresAsyncDataDictionary()
+        return self._data_dictionary

sqlspec/adapters/sqlite/config.py

@@ -47,6 +47,7 @@ class SqliteConfig(SyncDatabaseConfig[SqliteConnection, SqliteConnectionPool, Sq
         migration_config: "Optional[dict[str, Any]]" = None,
         statement_config: "Optional[StatementConfig]" = None,
         driver_features: "Optional[dict[str, Any]]" = None,
+        bind_key: "Optional[str]" = None,
     ) -> None:
         """Initialize SQLite configuration.
 
@@ -56,6 +57,7 @@ class SqliteConfig(SyncDatabaseConfig[SqliteConnection, SqliteConnectionPool, Sq
             migration_config: Migration configuration
             statement_config: Default SQL statement configuration
             driver_features: Optional driver feature configuration
+            bind_key: Optional bind key for the configuration
         """
         if pool_config is None:
             pool_config = {}
@@ -64,6 +66,7 @@ class SqliteConfig(SyncDatabaseConfig[SqliteConnection, SqliteConnectionPool, Sq
             pool_config["uri"] = True
 
         super().__init__(
+            bind_key=bind_key,
             pool_instance=pool_instance,
             pool_config=cast("dict[str, Any]", pool_config),
             migration_config=migration_config,

sqlspec/adapters/sqlite/data_dictionary.py

@@ -0,0 +1,117 @@
+"""SQLite-specific data dictionary for metadata queries."""
+
+import re
+from typing import TYPE_CHECKING, Callable, Optional, cast
+
+from sqlspec.driver import SyncDataDictionaryBase, SyncDriverAdapterBase, VersionInfo
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from sqlspec.adapters.sqlite.driver import SqliteDriver
+
+logger = get_logger("adapters.sqlite.data_dictionary")
+
+# Compiled regex patterns
+SQLITE_VERSION_PATTERN = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+
+__all__ = ("SqliteSyncDataDictionary",)
+
+
+class SqliteSyncDataDictionary(SyncDataDictionaryBase):
+    """SQLite-specific sync data dictionary."""
+
+    def get_version(self, driver: SyncDriverAdapterBase) -> "Optional[VersionInfo]":
+        """Get SQLite database version information.
+
+        Args:
+            driver: Sync database driver instance
+
+        Returns:
+            SQLite version information or None if detection fails
+        """
+        version_str = cast("SqliteDriver", driver).select_value("SELECT sqlite_version()")
+        if not version_str:
+            logger.warning("No SQLite version information found")
+            return None
+
+        # Parse version like "3.45.0"
+        version_match = SQLITE_VERSION_PATTERN.match(str(version_str))
+        if not version_match:
+            logger.warning("Could not parse SQLite version: %s", version_str)
+            return None
+
+        major, minor, patch = map(int, version_match.groups())
+        version_info = VersionInfo(major, minor, patch)
+        logger.debug("Detected SQLite version: %s", version_info)
+        return version_info
+
+    def get_feature_flag(self, driver: SyncDriverAdapterBase, feature: str) -> bool:
+        """Check if SQLite database supports a specific feature.
+
+        Args:
+            driver: SQLite 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[[VersionInfo], bool]] = {
+            "supports_json": lambda v: v >= VersionInfo(3, 38, 0),
+            "supports_returning": lambda v: v >= VersionInfo(3, 35, 0),
+            "supports_upsert": lambda v: v >= VersionInfo(3, 24, 0),
+            "supports_window_functions": lambda v: v >= VersionInfo(3, 25, 0),
+            "supports_cte": lambda v: v >= VersionInfo(3, 8, 3),
+            "supports_transactions": lambda _: True,
+            "supports_prepared_statements": lambda _: True,
+            "supports_schemas": lambda _: False,  # SQLite has ATTACH but not schemas
+            "supports_arrays": lambda _: False,
+            "supports_uuid": lambda _: False,
+        }
+
+        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:
+        """Get optimal SQLite type for a category.
+
+        Args:
+            driver: SQLite driver instance
+            type_category: Type category
+
+        Returns:
+            SQLite-specific type name
+        """
+        version_info = self.get_version(driver)
+
+        if type_category == "json":
+            if version_info and version_info >= VersionInfo(3, 38, 0):
+                return "JSON"
+            return "TEXT"
+
+        type_map = {"uuid": "TEXT", "boolean": "INTEGER", "timestamp": "TIMESTAMP", "text": "TEXT", "blob": "BLOB"}
+        return type_map.get(type_category, "TEXT")
+
+    def list_available_features(self) -> "list[str]":
+        """List available SQLite feature flags.
+
+        Returns:
+            List of supported feature names
+        """
+        return [
+            "supports_json",
+            "supports_returning",
+            "supports_upsert",
+            "supports_window_functions",
+            "supports_cte",
+            "supports_transactions",
+            "supports_prepared_statements",
+            "supports_schemas",
+            "supports_arrays",
+            "supports_uuid",
+        ]

sqlspec/adapters/sqlite/driver.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
     from sqlspec.core.result import SQLResult
     from sqlspec.core.statement import SQL
     from sqlspec.driver import ExecutionResult
+    from sqlspec.driver._sync import SyncDataDictionaryBase
 
 __all__ = ("SqliteCursor", "SqliteDriver", "SqliteExceptionHandler", "sqlite_statement_config")
 
@@ -36,6 +37,7 @@ sqlite_statement_config = StatementConfig(
             datetime.datetime: lambda v: v.isoformat(),
             datetime.date: lambda v: v.isoformat(),
             Decimal: str,
+            dict: to_json,
             list: to_json,
         },
         has_native_list_expansion=False,
@@ -75,7 +77,7 @@ class SqliteCursor:
         self.cursor = self.connection.cursor()
         return self.cursor
 
-    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+    def __exit__(self, *_: Any) -> None:
         """Clean up cursor resources.
 
         Args:
@@ -83,7 +85,6 @@ class SqliteCursor:
             exc_val: Exception value if an exception occurred
             exc_tb: Exception traceback if an exception occurred
         """
-        _ = (exc_type, exc_val, exc_tb)
         if self.cursor is not None:
             with contextlib.suppress(Exception):
                 self.cursor.close()
@@ -159,7 +160,7 @@ class SqliteDriver(SyncDriverAdapterBase):
     for SQLite databases using the standard sqlite3 module.
     """
 
-    __slots__ = ()
+    __slots__ = ("_data_dictionary",)
     dialect = "sqlite"
 
     def __init__(
@@ -185,6 +186,7 @@ class SqliteDriver(SyncDriverAdapterBase):
             )
 
         super().__init__(connection=connection, statement_config=statement_config, driver_features=driver_features)
+        self._data_dictionary: Optional[SyncDataDictionaryBase] = None
 
     def with_cursor(self, connection: "SqliteConnection") -> "SqliteCursor":
         """Create context manager for SQLite cursor.
@@ -325,3 +327,16 @@ class SqliteDriver(SyncDriverAdapterBase):
         except sqlite3.Error as e:
             msg = f"Failed to commit 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:
+            from sqlspec.adapters.sqlite.data_dictionary import SqliteSyncDataDictionary
+
+            self._data_dictionary = SqliteSyncDataDictionary()
+        return self._data_dictionary

sqlspec/adapters/sqlite/pool.py

@@ -1,5 +1,6 @@
 """SQLite database configuration with thread-local connections."""
 
+import contextlib
 import sqlite3
 import threading
 from contextlib import contextmanager
@@ -49,6 +50,8 @@ class SqliteConnectionPool:
             enable_optimizations: Whether to apply performance PRAGMAs
             **kwargs: Ignored pool parameters for compatibility
         """
+        if "check_same_thread" not in connection_parameters:
+            connection_parameters = {**connection_parameters, "check_same_thread": False}
         self._connection_parameters = connection_parameters
         self._thread_local = threading.local()
         self._enable_optimizations = enable_optimizations
@@ -62,8 +65,7 @@ class SqliteConnectionPool:
             is_memory = database == ":memory:" or database.startswith("file::memory:")
 
             if not is_memory:
-                connection.execute("PRAGMA journal_mode = WAL")
-
+                connection.execute("PRAGMA journal_mode = DELETE")
                 connection.execute("PRAGMA busy_timeout = 5000")
                 connection.execute("PRAGMA optimize")
 
@@ -97,7 +99,13 @@ class SqliteConnectionPool:
         Yields:
             SqliteConnection: A thread-local connection.
         """
-        yield self._get_thread_connection()
+        connection = self._get_thread_connection()
+        try:
+            yield connection
+        finally:
+            with contextlib.suppress(Exception):
+                if connection.in_transaction:
+                    connection.commit()
 
     def close(self) -> None:
         """Close the thread-local connection if it exists."""
@@ -124,7 +132,8 @@ class SqliteConnectionPool:
             _ = self._thread_local.connection
         except AttributeError:
             return 0
-        return 1
+        else:
+            return 1
 
     def checked_out(self) -> int:
         """Get number of checked out connections (always 0)."""

sqlspec/base.py

@@ -15,9 +15,8 @@ from sqlspec.config import (
 )
 from sqlspec.core.cache import (
     CacheConfig,
-    CacheStatsAggregate,
     get_cache_config,
-    get_cache_stats,
+    get_cache_statistics,
     log_cache_stats,
     reset_cache_stats,
     update_cache_config,
@@ -532,13 +531,13 @@ class SQLSpec:
         update_cache_config(config)
 
     @staticmethod
-    def get_cache_stats() -> CacheStatsAggregate:
+    def get_cache_stats() -> "dict[str, Any]":
         """Get current cache statistics.
 
         Returns:
             Cache statistics object with detailed metrics.
         """
-        return get_cache_stats()
+        return get_cache_statistics()
 
     @staticmethod
     def reset_cache_stats() -> None:

sqlspec/builder/_base.py

@@ -3,6 +3,8 @@
 Provides abstract base classes and core functionality for SQL query builders.
 """
 
+import hashlib
+import uuid
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, NoReturn, Optional, Union, cast
 
@@ -13,19 +15,21 @@ from sqlglot.errors import ParseError as SQLGlotParseError
 from sqlglot.optimizer import optimize
 from typing_extensions import Self
 
-from sqlspec.core.cache import CacheKey, get_cache_config, get_default_cache
+from sqlspec.core.cache import get_cache, get_cache_config
 from sqlspec.core.hashing import hash_optimized_expression
 from sqlspec.core.parameters import ParameterStyle, ParameterStyleConfig
 from sqlspec.core.statement import SQL, StatementConfig
 from sqlspec.exceptions import SQLBuilderError
 from sqlspec.utils.logging import get_logger
-from sqlspec.utils.type_guards import has_expression_and_parameters, has_sql_method, has_with_method
+from sqlspec.utils.type_guards import has_expression_and_parameters, has_sql_method, has_with_method, is_expression
 
 if TYPE_CHECKING:
     from sqlspec.core.result import SQLResult
 
 __all__ = ("QueryBuilder", "SafeQuery")
 
+MAX_PARAMETER_COLLISION_ATTEMPTS = 1000
+
 logger = get_logger(__name__)
 
 
@@ -91,6 +95,32 @@ class QueryBuilder(ABC):
                 "QueryBuilder._create_base_expression must return a valid sqlglot expression."
             )
 
+    def get_expression(self) -> Optional[exp.Expression]:
+        """Get expression reference (no copy).
+
+        Returns:
+            The current SQLGlot expression or None if not set
+        """
+        return self._expression
+
+    def set_expression(self, expression: exp.Expression) -> None:
+        """Set expression with validation.
+
+        Args:
+            expression: SQLGlot expression to set
+        """
+        if not is_expression(expression):
+            self._raise_invalid_expression_type(expression)
+        self._expression = expression
+
+    def has_expression(self) -> bool:
+        """Check if expression exists.
+
+        Returns:
+            True if expression is set, False otherwise
+        """
+        return self._expression is not None
+
     @abstractmethod
     def _create_base_expression(self) -> exp.Expression:
         """Create the base sqlglot expression for the specific query type.
@@ -121,6 +151,46 @@ class QueryBuilder(ABC):
         """
         raise SQLBuilderError(message) from cause
 
+    @staticmethod
+    def _raise_invalid_expression_type(expression: Any) -> NoReturn:
+        """Raise error for invalid expression type.
+
+        Args:
+            expression: The invalid expression object
+
+        Raises:
+            TypeError: Always raised for type mismatch
+        """
+        msg = f"Expected Expression, got {type(expression)}"
+        raise TypeError(msg)
+
+    @staticmethod
+    def _raise_cte_query_error(alias: str, message: str) -> NoReturn:
+        """Raise error for CTE query issues.
+
+        Args:
+            alias: CTE alias name
+            message: Specific error message
+
+        Raises:
+            SQLBuilderError: Always raised for CTE errors
+        """
+        msg = f"CTE '{alias}': {message}"
+        raise SQLBuilderError(msg)
+
+    @staticmethod
+    def _raise_cte_parse_error(cause: BaseException) -> NoReturn:
+        """Raise error for CTE parsing failures.
+
+        Args:
+            cause: The original parsing exception
+
+        Raises:
+            SQLBuilderError: Always raised with chained cause
+        """
+        msg = f"Failed to parse CTE query: {cause!s}"
+        raise SQLBuilderError(msg) from cause
+
     def _add_parameter(self, value: Any, context: Optional[str] = None) -> str:
         """Adds a parameter to the query and returns its placeholder name.
 
@@ -199,13 +269,11 @@ class QueryBuilder(ABC):
         if base_name not in self._parameters:
             return base_name
 
-        for i in range(1, 1000):
+        for i in range(1, MAX_PARAMETER_COLLISION_ATTEMPTS):
             name = f"{base_name}_{i}"
             if name not in self._parameters:
                 return name
 
-        import uuid
-
         return f"{base_name}_{uuid.uuid4().hex[:8]}"
 
     def _merge_cte_parameters(self, cte_name: str, parameters: dict[str, Any]) -> dict[str, str]:
@@ -254,8 +322,6 @@ class QueryBuilder(ABC):
         Returns:
             A unique cache key representing the builder state and configuration
         """
-        import hashlib
-
         dialect_name: str = self.dialect_name or "default"
 
         if self._expression is None:
@@ -307,36 +373,31 @@ class QueryBuilder(ABC):
         cte_select_expression: exp.Select
 
         if isinstance(query, QueryBuilder):
-            if query._expression is None:
-                self._raise_sql_builder_error("CTE query builder has no expression.")
-            if not isinstance(query._expression, exp.Select):
-                msg = f"CTE query builder expression must be a Select, got {type(query._expression).__name__}."
-                self._raise_sql_builder_error(msg)
-            cte_select_expression = query._expression
+            query_expr = query.get_expression()
+            if query_expr is None:
+                self._raise_cte_query_error(alias, "query builder has no expression")
+            if not isinstance(query_expr, exp.Select):
+                self._raise_cte_query_error(alias, f"expression must be a Select, got {type(query_expr).__name__}")
+            cte_select_expression = query_expr
             param_mapping = self._merge_cte_parameters(alias, query.parameters)
-            updated_expression = self._update_placeholders_in_expression(cte_select_expression, param_mapping)
-            if not isinstance(updated_expression, exp.Select):
-                msg = f"Updated CTE expression must be a Select, got {type(updated_expression).__name__}."
-                self._raise_sql_builder_error(msg)
-            cte_select_expression = updated_expression
+            cte_select_expression = cast(
+                "exp.Select", self._update_placeholders_in_expression(cte_select_expression, param_mapping)
+            )
 
         elif isinstance(query, str):
             try:
                 parsed_expression = sqlglot.parse_one(query, read=self.dialect_name)
                 if not isinstance(parsed_expression, exp.Select):
-                    msg = f"CTE query string must parse to a SELECT statement, got {type(parsed_expression).__name__}."
-                    self._raise_sql_builder_error(msg)
+                    self._raise_cte_query_error(
+                        alias, f"query string must parse to SELECT, got {type(parsed_expression).__name__}"
+                    )
                 cte_select_expression = parsed_expression
             except SQLGlotParseError as e:
-                self._raise_sql_builder_error(f"Failed to parse CTE query string: {e!s}", e)
-            except Exception as e:
-                msg = f"An unexpected error occurred while parsing CTE query string: {e!s}"
-                self._raise_sql_builder_error(msg, e)
+                self._raise_cte_parse_error(e)
         elif isinstance(query, exp.Select):
             cte_select_expression = query
         else:
-            msg = f"Invalid query type for CTE: {type(query).__name__}"
-            self._raise_sql_builder_error(msg)
+            self._raise_cte_query_error(alias, f"invalid query type: {type(query).__name__}")
 
         self._with_ctes[alias] = exp.CTE(this=cte_select_expression, alias=exp.to_table(alias))
         return self
@@ -398,9 +459,8 @@ class QueryBuilder(ABC):
             expression, dialect=dialect_name, schema=self.schema, optimizer_settings=optimizer_settings
         )
 
-        cache_key_obj = CacheKey((cache_key,))
-        unified_cache = get_default_cache()
-        cached_optimized = unified_cache.get(cache_key_obj)
+        cache = get_cache()
+        cached_optimized = cache.get("optimized", cache_key)
         if cached_optimized:
             return cast("exp.Expression", cached_optimized)
 
@@ -408,10 +468,9 @@ class QueryBuilder(ABC):
             optimized = optimize(
                 expression, schema=self.schema, dialect=self.dialect_name, optimizer_settings=optimizer_settings
             )
-
-            unified_cache.put(cache_key_obj, optimized)
-
+            cache.put("optimized", cache_key, optimized)
         except Exception:
+            logger.debug("Expression optimization failed, using original expression")
             return expression
         else:
             return optimized
@@ -430,15 +489,14 @@ class QueryBuilder(ABC):
             return self._to_statement(config)
 
         cache_key_str = self._generate_builder_cache_key(config)
-        cache_key = CacheKey((cache_key_str,))
 
-        unified_cache = get_default_cache()
-        cached_sql = unified_cache.get(cache_key)
+        cache = get_cache()
+        cached_sql = cache.get("builder", cache_key_str)
         if cached_sql is not None:
             return cast("SQL", cached_sql)
 
         sql_statement = self._to_statement(config)
-        unified_cache.put(cache_key, sql_statement)
+        cache.put("builder", cache_key_str, sql_statement)
 
         return sql_statement
 
@@ -453,18 +511,7 @@ class QueryBuilder(ABC):
         """
         safe_query = self.build()
 
-        if isinstance(safe_query.parameters, dict):
-            kwargs = safe_query.parameters
-            parameters: Optional[tuple[Any, ...]] = None
-        else:
-            kwargs = None
-            parameters = (
-                safe_query.parameters
-                if isinstance(safe_query.parameters, tuple)
-                else tuple(safe_query.parameters)
-                if safe_query.parameters
-                else None
-            )
+        kwargs, parameters = self._extract_statement_parameters(safe_query.parameters)
 
         if config is None:
             config = StatementConfig(
@@ -492,6 +539,28 @@ class QueryBuilder(ABC):
             return SQL(sql_string, *parameters, statement_config=config)
         return SQL(sql_string, statement_config=config)
 
+    def _extract_statement_parameters(
+        self, raw_parameters: Any
+    ) -> "tuple[Optional[dict[str, Any]], Optional[tuple[Any, ...]]]":
+        """Extract parameters for SQL statement creation.
+
+        Args:
+            raw_parameters: Raw parameter data from SafeQuery
+
+        Returns:
+            Tuple of (kwargs, parameters) for SQL statement construction
+        """
+        if isinstance(raw_parameters, dict):
+            return raw_parameters, None
+
+        if isinstance(raw_parameters, tuple):
+            return None, raw_parameters
+
+        if raw_parameters:
+            return None, tuple(raw_parameters)
+
+        return None, None
+
     def __str__(self) -> str:
         """Return the SQL string representation of the query.
 
@@ -531,3 +600,16 @@ class QueryBuilder(ABC):
     def parameters(self) -> dict[str, Any]:
         """Public access to query parameters."""
         return self._parameters
+
+    def set_parameters(self, parameters: dict[str, Any]) -> None:
+        """Set query parameters (public API)."""
+        self._parameters = parameters.copy()
+
+    @property
+    def with_ctes(self) -> "dict[str, exp.CTE]":
+        """Get WITH clause CTEs (public API)."""
+        return dict(self._with_ctes)
+
+    def generate_unique_parameter_name(self, base_name: str) -> str:
+        """Generate unique parameter name (public API)."""
+        return self._generate_unique_parameter_name(base_name)