sqlspec 0.14.1__py3-none-any.whl → 0.16.0__py3-none-any.whl

sqlspec/base.py

@@ -13,6 +13,15 @@ from sqlspec.config import (
     SyncConfigT,
     SyncDatabaseConfig,
 )
+from sqlspec.core.cache import (
+    CacheConfig,
+    CacheStatsAggregate,
+    get_cache_config,
+    get_cache_stats,
+    log_cache_stats,
+    reset_cache_stats,
+    update_cache_config,
+)
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
@@ -27,18 +36,19 @@ logger = get_logger()
 
 
 class SQLSpec:
-    """Type-safe configuration manager and registry for database connections and pools."""
+    """Configuration manager and registry for database connections and pools."""
 
-    __slots__ = ("_configs",)
+    __slots__ = ("_cleanup_tasks", "_configs", "_instance_cache_config")
 
     def __init__(self) -> None:
         self._configs: dict[Any, DatabaseConfigProtocol[Any, Any, Any]] = {}
         atexit.register(self._cleanup_pools)
+        self._instance_cache_config: Optional[CacheConfig] = None
+        self._cleanup_tasks: list[asyncio.Task[None]] = []
 
     @staticmethod
     def _get_config_name(obj: Any) -> str:
         """Get display name for configuration object."""
-        # Try to get __name__ attribute if it exists, otherwise use str()
         return getattr(obj, "__name__", str(obj))
 
     def _cleanup_pools(self) -> None:
@@ -54,11 +64,11 @@ class SQLSpec:
                             try:
                                 loop = asyncio.get_running_loop()
                                 if loop.is_running():
-                                    _task = asyncio.ensure_future(close_pool_awaitable, loop=loop)  # noqa: RUF006
-
+                                    task = asyncio.create_task(cast("Coroutine[Any, Any, None]", close_pool_awaitable))
+                                    self._cleanup_tasks.append(task)
                                 else:
                                     asyncio.run(cast("Coroutine[Any, Any, None]", close_pool_awaitable))
-                            except RuntimeError:  # No running event loop
+                            except RuntimeError:
                                 asyncio.run(cast("Coroutine[Any, Any, None]", close_pool_awaitable))
                     else:
                         config.close_pool()
@@ -66,6 +76,14 @@ class SQLSpec:
                 except Exception as e:
                     logger.warning("Failed to clean up pool for config %s: %s", config_type.__name__, e)
 
+        if self._cleanup_tasks:
+            try:
+                loop = asyncio.get_running_loop()
+                if loop.is_running():
+                    asyncio.gather(*self._cleanup_tasks, return_exceptions=True)
+            except RuntimeError:
+                pass
+
         self._configs.clear()
         logger.info("Pool cleanup completed. Cleaned %d pools.", cleaned_count)
 
@@ -233,14 +251,13 @@ class SQLSpec:
             async def _create_driver_async() -> "DriverT":
                 resolved_connection = await connection_obj  # pyright: ignore
                 return cast(  # pyright: ignore
-                    "DriverT",
-                    config.driver_type(connection=resolved_connection, default_row_type=config.default_row_type),
+                    "DriverT", config.driver_type(connection=resolved_connection)
                 )
 
             return _create_driver_async()
 
         return cast(  # pyright: ignore
-            "DriverT", config.driver_type(connection=connection_obj, default_row_type=config.default_row_type)
+            "DriverT", config.driver_type(connection=connection_obj)
         )
 
     @overload
@@ -473,3 +490,82 @@ class SQLSpec:
 
         logger.debug("Config %s does not support connection pooling - nothing to close", config_name)
         return None
+
+    @staticmethod
+    def get_cache_config() -> CacheConfig:
+        """Get the current global cache configuration.
+
+        Returns:
+            The current cache configuration.
+        """
+        return get_cache_config()
+
+    @staticmethod
+    def update_cache_config(config: CacheConfig) -> None:
+        """Update the global cache configuration.
+
+        Args:
+            config: The new cache configuration to apply.
+        """
+        update_cache_config(config)
+
+    @staticmethod
+    def get_cache_stats() -> CacheStatsAggregate:
+        """Get current cache statistics.
+
+        Returns:
+            Cache statistics object with detailed metrics.
+        """
+        return get_cache_stats()
+
+    @staticmethod
+    def reset_cache_stats() -> None:
+        """Reset all cache statistics to zero."""
+        reset_cache_stats()
+
+    @staticmethod
+    def log_cache_stats() -> None:
+        """Log current cache statistics using the configured logger."""
+        log_cache_stats()
+
+    @staticmethod
+    def configure_cache(
+        *,
+        sql_cache_size: Optional[int] = None,
+        fragment_cache_size: Optional[int] = None,
+        optimized_cache_size: Optional[int] = None,
+        sql_cache_enabled: Optional[bool] = None,
+        fragment_cache_enabled: Optional[bool] = None,
+        optimized_cache_enabled: Optional[bool] = None,
+    ) -> None:
+        """Update cache configuration with partial values.
+
+        Args:
+            sql_cache_size: Size of the SQL statement cache
+            fragment_cache_size: Size of the AST fragment cache
+            optimized_cache_size: Size of the optimized expression cache
+            sql_cache_enabled: Enable/disable SQL cache
+            fragment_cache_enabled: Enable/disable fragment cache
+            optimized_cache_enabled: Enable/disable optimized cache
+        """
+        current_config = get_cache_config()
+        update_cache_config(
+            CacheConfig(
+                sql_cache_size=sql_cache_size if sql_cache_size is not None else current_config.sql_cache_size,
+                fragment_cache_size=fragment_cache_size
+                if fragment_cache_size is not None
+                else current_config.fragment_cache_size,
+                optimized_cache_size=optimized_cache_size
+                if optimized_cache_size is not None
+                else current_config.optimized_cache_size,
+                sql_cache_enabled=sql_cache_enabled
+                if sql_cache_enabled is not None
+                else current_config.sql_cache_enabled,
+                fragment_cache_enabled=fragment_cache_enabled
+                if fragment_cache_enabled is not None
+                else current_config.fragment_cache_enabled,
+                optimized_cache_enabled=optimized_cache_enabled
+                if optimized_cache_enabled is not None
+                else current_config.optimized_cache_enabled,
+            )
+        )

sqlspec/{statement/builder → builder}/__init__.py

@@ -2,14 +2,11 @@
 
 This package provides fluent interfaces for building SQL queries with automatic
 parameter binding and validation.
-
-# SelectBuilder is now generic and supports as_schema for type-safe schema integration.
 """
 
-from sqlspec.exceptions import SQLBuilderError
-from sqlspec.statement.builder._base import QueryBuilder, SafeQuery
-from sqlspec.statement.builder._column import Column, ColumnExpression, FunctionColumn
-from sqlspec.statement.builder._ddl import (
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder._column import Column, ColumnExpression, FunctionColumn
+from sqlspec.builder._ddl import (
     AlterTable,
     CommentOn,
     CreateIndex,
@@ -24,14 +21,15 @@ from sqlspec.statement.builder._ddl import (
     DropTable,
     DropView,
     RenameTable,
-    TruncateTable,
+    Truncate,
 )
-from sqlspec.statement.builder._delete import Delete
-from sqlspec.statement.builder._insert import Insert
-from sqlspec.statement.builder._merge import Merge
-from sqlspec.statement.builder._select import Select
-from sqlspec.statement.builder._update import Update
-from sqlspec.statement.builder.mixins import WhereClauseMixin
+from sqlspec.builder._delete import Delete
+from sqlspec.builder._insert import Insert
+from sqlspec.builder._merge import Merge
+from sqlspec.builder._select import Select
+from sqlspec.builder._update import Update
+from sqlspec.builder.mixins import WhereClauseMixin
+from sqlspec.exceptions import SQLBuilderError
 
 __all__ = (
     "AlterTable",
@@ -58,7 +56,7 @@ __all__ = (
     "SQLBuilderError",
     "SafeQuery",
     "Select",
-    "TruncateTable",
+    "Truncate",
     "Update",
     "WhereClauseMixin",
 )

sqlspec/{statement/builder → builder}/_base.py

@@ -1,13 +1,12 @@
 """Safe SQL query builder with validation and parameter binding.
 
 This module provides a fluent interface for building SQL queries safely,
-with automatic parameter binding and validation. Enhanced with SQLGlot's
-advanced builder patterns and optimization capabilities.
+with automatic parameter binding and validation.
 """
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Generic, NoReturn, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, NoReturn, Optional, Union, cast
 
 import sqlglot
 from sqlglot import Dialect, exp
@@ -16,14 +15,16 @@ 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.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.statement.sql import SQL, SQLConfig
-from sqlspec.typing import RowT
 from sqlspec.utils.logging import get_logger
 from sqlspec.utils.type_guards import has_sql_method, has_with_method
 
 if TYPE_CHECKING:
-    from sqlspec.statement.result import SQLResult
+    from sqlspec.core.result import SQLResult
 
 __all__ = ("QueryBuilder", "SafeQuery")
 
@@ -40,18 +41,11 @@ class SafeQuery:
 
 
 @dataclass
-class QueryBuilder(ABC, Generic[RowT]):
+class QueryBuilder(ABC):
     """Abstract base class for SQL query builders with SQLGlot optimization.
 
     Provides common functionality for dialect handling, parameter management,
-    query construction, and automatic query optimization using SQLGlot's
-    advanced capabilities.
-
-    New features:
-    - Automatic query optimization (join reordering, predicate pushdown)
-    - Query complexity analysis
-    - Smart parameter naming based on context
-    - Expression caching for performance
+    query construction, and query optimization using SQLGlot.
     """
 
     dialect: DialectType = field(default=None)
@@ -68,7 +62,6 @@ class QueryBuilder(ABC, Generic[RowT]):
     def __post_init__(self) -> None:
         self._expression = self._create_base_expression()
         if not self._expression:
-            # This path should be unreachable if _raise_sql_builder_error has NoReturn
             self._raise_sql_builder_error(
                 "QueryBuilder._create_base_expression must return a valid sqlglot expression."
             )
@@ -77,17 +70,13 @@ class QueryBuilder(ABC, Generic[RowT]):
     def _create_base_expression(self) -> exp.Expression:
         """Create the base sqlglot expression for the specific query type.
 
-        Examples:
-            For a SELECT query, this would return `exp.Select()`.
-            For an INSERT query, this would return `exp.Insert()`.
-
         Returns:
-            exp.Expression: A new sqlglot expression.
+            A new sqlglot expression appropriate for the query type.
         """
 
     @property
     @abstractmethod
-    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+    def _expected_result_type(self) -> "type[SQLResult]":
         """The expected result type for the query being built.
 
         Returns:
@@ -119,7 +108,6 @@ class QueryBuilder(ABC, Generic[RowT]):
         """
         self._parameter_counter += 1
 
-        # Use context-aware naming if provided
         param_name = f"{context}_param_{self._parameter_counter}" if context else f"param_{self._parameter_counter}"
 
         self._parameters[param_name] = value
@@ -141,10 +129,8 @@ class QueryBuilder(ABC, Generic[RowT]):
 
         def replacer(node: exp.Expression) -> exp.Expression:
             if isinstance(node, exp.Literal):
-                # Skip boolean literals (TRUE/FALSE) and NULL
-                if node.this in (True, False, None):
+                if node.this in {True, False, None}:
                     return node
-                # Convert other literals to parameters
                 param_name = self._add_parameter(node.this, context="where")
                 return exp.Placeholder(this=param_name)
             return node
@@ -195,7 +181,47 @@ class QueryBuilder(ABC, Generic[RowT]):
                 return name
             i += 1
 
-    def with_cte(self: Self, alias: str, query: "Union[QueryBuilder[Any], exp.Select, str]") -> Self:
+    def _generate_builder_cache_key(self, config: "Optional[StatementConfig]" = None) -> str:
+        """Generate cache key based on builder state and configuration.
+
+        Args:
+            config: Optional SQL configuration that affects the generated SQL
+
+        Returns:
+            A unique cache key representing the builder state and configuration
+        """
+        import hashlib
+
+        state_components = [
+            f"expression:{self._expression.sql() if self._expression else 'None'}",
+            f"parameters:{sorted(self._parameters.items())}",
+            f"ctes:{sorted(self._with_ctes.keys())}",
+            f"dialect:{self.dialect_name or 'default'}",
+            f"schema:{self.schema}",
+            f"optimization:{self.enable_optimization}",
+            f"optimize_joins:{self.optimize_joins}",
+            f"optimize_predicates:{self.optimize_predicates}",
+            f"simplify_expressions:{self.simplify_expressions}",
+        ]
+
+        if config:
+            config_components = [
+                f"config_dialect:{config.dialect or 'default'}",
+                f"enable_parsing:{config.enable_parsing}",
+                f"enable_validation:{config.enable_validation}",
+                f"enable_transformations:{config.enable_transformations}",
+                f"enable_analysis:{config.enable_analysis}",
+                f"enable_caching:{config.enable_caching}",
+                f"param_style:{config.parameter_config.default_parameter_style.value}",
+            ]
+            state_components.extend(config_components)
+
+        state_string = "|".join(state_components)
+        cache_key = hashlib.sha256(state_string.encode()).hexdigest()[:16]
+
+        return f"builder:{cache_key}"
+
+    def with_cte(self: Self, alias: str, query: "Union[QueryBuilder, exp.Select, str]") -> Self:
         """Adds a Common Table Expression (CTE) to the query.
 
         Args:
@@ -219,7 +245,6 @@ class QueryBuilder(ABC, Generic[RowT]):
                 self._raise_sql_builder_error(msg)
             cte_select_expression = query._expression.copy()
             for p_name, p_value in query.parameters.items():
-                # Try to preserve original parameter name, only rename if collision
                 unique_name = self._generate_unique_parameter_name(p_name)
                 self.add_parameter(p_value, unique_name)
 
@@ -229,7 +254,6 @@ class QueryBuilder(ABC, Generic[RowT]):
                 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)
-                # parsed_expression is now known to be exp.Select
                 cte_select_expression = parsed_expression
             except SQLGlotParseError as e:
                 self._raise_sql_builder_error(f"Failed to parse CTE query string: {e!s}", e)
@@ -241,7 +265,7 @@ class QueryBuilder(ABC, Generic[RowT]):
         else:
             msg = f"Invalid query type for CTE: {type(query).__name__}"
             self._raise_sql_builder_error(msg)
-            return self  # This line won't be reached but satisfies type checkers
+            return self
 
         self._with_ctes[alias] = exp.CTE(this=cte_select_expression, alias=exp.to_table(alias))
         return self
@@ -255,22 +279,22 @@ class QueryBuilder(ABC, Generic[RowT]):
         if self._expression is None:
             self._raise_sql_builder_error("QueryBuilder expression not initialized.")
 
-        final_expression = self._expression.copy()
-
         if self._with_ctes:
+            final_expression = self._expression.copy()
             if has_with_method(final_expression):
-                # Type checker now knows final_expression has with_ method
                 for alias, cte_node in self._with_ctes.items():
                     final_expression = cast("Any", final_expression).with_(cte_node.args["this"], as_=alias, copy=False)
             elif isinstance(final_expression, (exp.Select, exp.Insert, exp.Update, exp.Delete, exp.Union)):
                 final_expression = exp.With(expressions=list(self._with_ctes.values()), this=final_expression)
+        else:
+            final_expression = self._expression.copy() if self.enable_optimization else self._expression
 
         if self.enable_optimization and isinstance(final_expression, exp.Expression):
             final_expression = self._optimize_expression(final_expression)
 
         try:
             if has_sql_method(final_expression):
-                sql_string = final_expression.sql(dialect=self.dialect_name, pretty=True)  # pyright: ignore[reportAttributeAccessIssue]
+                sql_string = final_expression.sql(dialect=self.dialect_name, pretty=True)
             else:
                 sql_string = str(final_expression)
         except Exception as e:
@@ -281,7 +305,7 @@ class QueryBuilder(ABC, Generic[RowT]):
         return SafeQuery(sql=sql_string, parameters=self._parameters.copy(), dialect=self.dialect)
 
     def _optimize_expression(self, expression: exp.Expression) -> exp.Expression:
-        """Apply SQLGlot optimizations to the expression.
+        """Apply SQLGlot optimizations to the expression with caching.
 
         Args:
             expression: The expression to optimize
@@ -292,24 +316,63 @@ class QueryBuilder(ABC, Generic[RowT]):
         if not self.enable_optimization:
             return expression
 
+        optimizer_settings = {
+            "optimize_joins": self.optimize_joins,
+            "pushdown_predicates": self.optimize_predicates,
+            "simplify_expressions": self.simplify_expressions,
+        }
+
+        dialect_name = self.dialect_name or "default"
+        cache_key = hash_optimized_expression(
+            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)
+        if cached_optimized:
+            return cast("exp.Expression", cached_optimized)
+
         try:
-            # Use SQLGlot's comprehensive optimizer
-            return optimize(
-                expression.copy(),
-                schema=self.schema,
-                dialect=self.dialect_name,
-                optimizer_settings={
-                    "optimize_joins": self.optimize_joins,
-                    "pushdown_predicates": self.optimize_predicates,
-                    "simplify_expressions": self.simplify_expressions,
-                },
+            optimized = optimize(
+                expression.copy(), schema=self.schema, dialect=self.dialect_name, optimizer_settings=optimizer_settings
             )
+
+            unified_cache.put(cache_key_obj, optimized.copy())
+
         except Exception:
-            # Continue with unoptimized query on failure
             return expression
+        else:
+            return optimized
 
-    def to_statement(self, config: "Optional[SQLConfig]" = None) -> "SQL":
-        """Converts the built query into a SQL statement object.
+    def to_statement(self, config: "Optional[StatementConfig]" = None) -> "SQL":
+        """Converts the built query into a SQL statement object with caching.
+
+        Args:
+            config: Optional SQL configuration.
+
+        Returns:
+            SQL: A SQL statement object.
+        """
+        cache_config = get_cache_config()
+        if not cache_config.compiled_cache_enabled:
+            return self._to_statement_without_cache(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)
+        if cached_sql is not None:
+            return cast("SQL", cached_sql)
+
+        sql_statement = self._to_statement_without_cache(config)
+        unified_cache.put(cache_key, sql_statement)
+
+        return sql_statement
+
+    def _to_statement_without_cache(self, config: "Optional[StatementConfig]" = None) -> "SQL":
+        """Internal method to create SQL statement without caching.
 
         Args:
             config: Optional SQL configuration.
@@ -321,7 +384,7 @@ class QueryBuilder(ABC, Generic[RowT]):
 
         if isinstance(safe_query.parameters, dict):
             kwargs = safe_query.parameters
-            parameters = None
+            parameters: Optional[tuple] = None
         else:
             kwargs = None
             parameters = (
@@ -333,16 +396,18 @@ class QueryBuilder(ABC, Generic[RowT]):
             )
 
         if config is None:
-            from sqlspec.statement.sql import SQLConfig
+            from sqlspec.core.statement import StatementConfig
 
-            config = SQLConfig(dialect=safe_query.dialect)
+            parameter_config = ParameterStyleConfig(
+                default_parameter_style=ParameterStyle.QMARK, supported_parameter_styles={ParameterStyle.QMARK}
+            )
+            config = StatementConfig(parameter_config=parameter_config, dialect=safe_query.dialect)
 
-        # SQL expects parameters as variadic args, not as a keyword
         if kwargs:
-            return SQL(safe_query.sql, config=config, **kwargs)
+            return SQL(safe_query.sql, statement_config=config, **kwargs)
         if parameters:
-            return SQL(safe_query.sql, *parameters, config=config)
-        return SQL(safe_query.sql, config=config)
+            return SQL(safe_query.sql, *parameters, statement_config=config)
+        return SQL(safe_query.sql, statement_config=config)
 
     def __str__(self) -> str:
         """Return the SQL string representation of the query.

sqlspec/{statement/builder → builder}/_column.py

@@ -17,6 +17,8 @@ __all__ = ("Column", "ColumnExpression", "FunctionColumn")
 class ColumnExpression:
     """Base class for column expressions that can be combined with operators."""
 
+    __slots__ = ("_expression",)
+
     def __init__(self, expression: exp.Expression) -> None:
         self._expression = expression
 
@@ -54,11 +56,12 @@ class ColumnExpression:
 class Column:
     """Represents a database column with Python operator support."""
 
+    __slots__ = ("_expression", "name", "table")
+
     def __init__(self, name: str, table: Optional[str] = None) -> None:
         self.name = name
         self.table = table
 
-        # Create SQLGlot column expression
         if table:
             self._expression = exp.Column(this=exp.Identifier(this=name), table=exp.Identifier(this=table))
         else:
@@ -174,7 +177,7 @@ class Column:
         """SQL ROUND() function."""
         if decimals == 0:
             return FunctionColumn(exp.Round(this=self._expression))
-        return FunctionColumn(exp.Round(this=self._expression, expression=exp.Literal.number(decimals)))
+        return FunctionColumn(exp.Round(this=self._expression, expression=exp.convert(decimals)))
 
     def floor(self) -> "FunctionColumn":
         """SQL FLOOR() function."""
@@ -186,9 +189,9 @@ class Column:
 
     def substring(self, start: int, length: Optional[int] = None) -> "FunctionColumn":
         """SQL SUBSTRING() function."""
-        args = [exp.Literal.number(start)]
+        args = [exp.convert(start)]
         if length is not None:
-            args.append(exp.Literal.number(length))
+            args.append(exp.convert(length))
         return FunctionColumn(exp.Substring(this=self._expression, expressions=args))
 
     def coalesce(self, *values: Any) -> "FunctionColumn":
@@ -234,6 +237,14 @@ class Column:
         """Create an aliased column expression."""
         return exp.Alias(this=self._expression, alias=alias_name)
 
+    def asc(self) -> exp.Ordered:
+        """Create an ASC ordering expression."""
+        return exp.Ordered(this=self._expression, desc=False)
+
+    def desc(self) -> exp.Ordered:
+        """Create a DESC ordering expression."""
+        return exp.Ordered(this=self._expression, desc=True)
+
     def __repr__(self) -> str:
         if self.table:
             return f"Column<{self.table}.{self.name}>"
@@ -247,6 +258,8 @@ class Column:
 class FunctionColumn:
     """Represents the result of a SQL function call on a column."""
 
+    __slots__ = ("_expression",)
+
     def __init__(self, expression: exp.Expression) -> None:
         self._expression = expression
 
@@ -306,8 +319,6 @@ class FunctionColumn:
         """Create an aliased function expression."""
         return exp.Alias(this=self._expression, alias=alias_name)
 
-    # Add other operators as needed...
-
     def __hash__(self) -> int:
         """Hash based on the SQL expression."""
         return hash(self._expression.sql() if has_sql_method(self._expression) else str(self._expression))