sqlspec 0.11.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

sqlspec/statement/builder/delete.py

@@ -0,0 +1,80 @@
+"""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.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from sqlglot import exp
+
+from sqlspec.statement.builder.base import QueryBuilder, SafeQuery
+from sqlspec.statement.builder.mixins import DeleteFromClauseMixin, ReturningClauseMixin, WhereClauseMixin
+from sqlspec.statement.result import SQLResult
+from sqlspec.typing import RowT
+
+__all__ = ("DeleteBuilder",)
+
+
+@dataclass(unsafe_hash=True)
+class DeleteBuilder(QueryBuilder[RowT], WhereClauseMixin, ReturningClauseMixin, DeleteFromClauseMixin):
+    """Builder for DELETE statements.
+
+    This builder provides a fluent interface for constructing SQL DELETE statements
+    with automatic parameter binding and validation. It does not support JOIN
+    operations to maintain cross-dialect compatibility and safety.
+
+    Example:
+        ```python
+        # Basic DELETE
+        delete_query = (
+            DeleteBuilder().from_("users").where("age < 18")
+        )
+
+        # DELETE with parameterized conditions
+        delete_query = (
+            DeleteBuilder()
+            .from_("users")
+            .where_eq("status", "inactive")
+            .where_in("category", ["test", "demo"])
+        )
+        ```
+    """
+
+    _table: "Optional[str]" = field(default=None, init=False)
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+        """Get the expected result type for DELETE operations.
+
+        Returns:
+            The ExecuteResult type for DELETE statements.
+        """
+        return SQLResult[RowT]
+
+    def _create_base_expression(self) -> "exp.Delete":
+        """Create a new sqlglot Delete expression.
+
+        Returns:
+            A new sqlglot Delete expression.
+        """
+        return exp.Delete()
+
+    def build(self) -> "SafeQuery":
+        """Build the DELETE query with validation.
+
+        Returns:
+            SafeQuery: The built query with SQL and parameters.
+
+        Raises:
+            SQLBuilderError: If the table is not specified.
+        """
+
+        if not self._table:
+            from sqlspec.exceptions import SQLBuilderError
+
+            msg = "DELETE requires a table to be specified. Use from() to set the table."
+            raise SQLBuilderError(msg)
+
+        return super().build()

sqlspec/statement/builder/insert.py

@@ -0,0 +1,274 @@
+"""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.
+"""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Optional
+
+from sqlglot import exp
+from typing_extensions import Self
+
+from sqlspec.exceptions import SQLBuilderError
+from sqlspec.statement.builder.base import QueryBuilder
+from sqlspec.statement.builder.mixins import (
+    InsertFromSelectMixin,
+    InsertIntoClauseMixin,
+    InsertValuesMixin,
+    ReturningClauseMixin,
+)
+from sqlspec.statement.result import SQLResult
+from sqlspec.typing import RowT
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+
+__all__ = ("InsertBuilder",)
+
+ERR_MSG_TABLE_NOT_SET = "The target table must be set using .into() before adding values."
+ERR_MSG_VALUES_COLUMNS_MISMATCH = (
+    "Number of values ({values_len}) does not match the number of specified columns ({columns_len})."
+)
+ERR_MSG_INTERNAL_EXPRESSION_TYPE = "Internal error: expression is not an Insert instance as expected."
+ERR_MSG_EXPRESSION_NOT_INITIALIZED = "Internal error: base expression not initialized."
+
+
+@dataclass(unsafe_hash=True)
+class InsertBuilder(
+    QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, InsertFromSelectMixin, InsertIntoClauseMixin
+):
+    """Builder for INSERT statements.
+
+    This builder facilitates the construction of SQL INSERT queries
+    in a safe and dialect-agnostic manner with automatic parameter binding.
+
+    Example:
+        ```python
+        # Basic INSERT with values
+        insert_query = (
+            InsertBuilder()
+            .into("users")
+            .columns("name", "email", "age")
+            .values("John Doe", "john@example.com", 30)
+        )
+
+        # Multi-row INSERT
+        insert_query = (
+            InsertBuilder()
+            .into("users")
+            .columns("name", "email")
+            .values("John", "john@example.com")
+            .values("Jane", "jane@example.com")
+        )
+
+        # INSERT from dictionary
+        insert_query = (
+            InsertBuilder()
+            .into("users")
+            .values_from_dict(
+                {"name": "John", "email": "john@example.com"}
+            )
+        )
+
+        # INSERT from SELECT
+        insert_query = (
+            InsertBuilder()
+            .into("users_backup")
+            .from_select(
+                SelectBuilder()
+                .select("name", "email")
+                .from_("users")
+                .where("active = true")
+            )
+        )
+        ```
+    """
+
+    _table: "Optional[str]" = field(default=None, init=False)
+    _columns: list[str] = field(default_factory=list, init=False)
+    _values_added_count: int = field(default=0, init=False)
+
+    def _create_base_expression(self) -> exp.Insert:
+        """Create a base INSERT expression.
+
+        This method is called by the base QueryBuilder during initialization.
+
+        Returns:
+            A new sqlglot Insert expression.
+        """
+        return exp.Insert()
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+        """Specifies the expected result type for an INSERT query.
+
+        Returns:
+            The type of result expected for INSERT operations.
+        """
+        return SQLResult[RowT]
+
+    def _get_insert_expression(self) -> exp.Insert:
+        """Safely gets and casts the internal expression to exp.Insert.
+
+        Returns:
+            The internal expression as exp.Insert.
+
+        Raises:
+            SQLBuilderError: If the expression is not initialized or is not an Insert.
+        """
+        if self._expression is None:
+            raise SQLBuilderError(ERR_MSG_EXPRESSION_NOT_INITIALIZED)
+        if not isinstance(self._expression, exp.Insert):
+            raise SQLBuilderError(ERR_MSG_INTERNAL_EXPRESSION_TYPE)
+        return self._expression
+
+    def values(self, *values: Any) -> "Self":
+        """Adds a row of values to the INSERT statement.
+
+        This method can be called multiple times to insert multiple rows,
+        resulting in a multi-row INSERT statement like `VALUES (...), (...)`.
+
+        Args:
+            *values: The values for the row to be inserted. The number of values
+                     must match the number of columns set by `columns()`, if `columns()` was called
+                     and specified any non-empty list of columns.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If `into()` has not been called to set the table,
+                             or if `columns()` was called with a non-empty list of columns
+                             and the number of values does not match the number of specified columns.
+        """
+        if not self._table:
+            raise SQLBuilderError(ERR_MSG_TABLE_NOT_SET)
+
+        insert_expr = self._get_insert_expression()
+
+        if self._columns and len(values) != len(self._columns):
+            msg = ERR_MSG_VALUES_COLUMNS_MISMATCH.format(values_len=len(values), columns_len=len(self._columns))
+            raise SQLBuilderError(msg)
+
+        param_names = [self._add_parameter(value) for value in values]
+        value_placeholders = tuple(exp.var(name) for name in param_names)
+
+        current_values_expression = insert_expr.args.get("expression")
+
+        if self._values_added_count == 0:
+            new_values_node = exp.Values(expressions=[exp.Tuple(expressions=list(value_placeholders))])
+            insert_expr.set("expression", new_values_node)
+        elif isinstance(current_values_expression, exp.Values):
+            current_values_expression.expressions.append(exp.Tuple(expressions=list(value_placeholders)))
+        else:
+            # This case should ideally not be reached if logic is correct:
+            # means _values_added_count > 0 but expression is not exp.Values.
+            # Fallback to creating a new Values node, though this might indicate an issue.
+            new_values_node = exp.Values(expressions=[exp.Tuple(expressions=list(value_placeholders))])
+            insert_expr.set("expression", new_values_node)
+
+        self._values_added_count += 1
+        return self
+
+    def values_from_dict(self, data: "Mapping[str, Any]") -> "Self":
+        """Adds a row of values from a dictionary.
+
+        This is a convenience method that automatically sets columns based on
+        the dictionary keys and values based on the dictionary values.
+
+        Args:
+            data: A mapping of column names to values.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If `into()` has not been called to set the table.
+        """
+        if not self._table:
+            raise SQLBuilderError(ERR_MSG_TABLE_NOT_SET)
+
+        if not self._columns:
+            # Set columns from dictionary keys if not already set
+            self.columns(*data.keys())
+        elif set(self._columns) != set(data.keys()):
+            # Verify that dictionary keys match existing columns
+            msg = f"Dictionary keys {set(data.keys())} do not match existing columns {set(self._columns)}."
+            raise SQLBuilderError(msg)
+
+        # Add values in the same order as columns
+        return self.values(*[data[col] for col in self._columns])
+
+    def values_from_dicts(self, data: "Sequence[Mapping[str, Any]]") -> "Self":
+        """Adds multiple rows of values from a sequence of dictionaries.
+
+        This is a convenience method for bulk inserts from structured data.
+
+        Args:
+            data: A sequence of mappings, each representing a row of data.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Raises:
+            SQLBuilderError: If `into()` has not been called to set the table,
+                           or if dictionaries have inconsistent keys.
+        """
+        if not data:
+            return self
+
+        # Use the first dictionary to establish columns
+        first_dict = data[0]
+        if not self._columns:
+            self.columns(*first_dict.keys())
+
+        # Validate that all dictionaries have the same keys
+        expected_keys = set(self._columns)
+        for i, row_dict in enumerate(data):
+            if set(row_dict.keys()) != expected_keys:
+                msg = (
+                    f"Dictionary at index {i} has keys {set(row_dict.keys())} "
+                    f"which do not match expected keys {expected_keys}."
+                )
+                raise SQLBuilderError(msg)
+
+        # Add each row
+        for row_dict in data:
+            self.values(*[row_dict[col] for col in self._columns])
+
+        return self
+
+    def on_conflict_do_nothing(self) -> "Self":
+        """Adds an ON CONFLICT DO NOTHING clause (PostgreSQL syntax).
+
+        This is used to ignore rows that would cause a conflict.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Note:
+            This is PostgreSQL-specific syntax. Different databases have different syntax.
+            For a more general solution, you might need dialect-specific handling.
+        """
+        insert_expr = self._get_insert_expression()
+        # Using sqlglot's OnConflict expression if available
+        try:
+            on_conflict = exp.OnConflict(this=None, expressions=[])
+            insert_expr.set("on", on_conflict)
+        except AttributeError:
+            # Fallback for older sqlglot versions
+            pass
+        return self
+
+    def on_duplicate_key_update(self, **set_values: Any) -> "Self":
+        """Adds an ON DUPLICATE KEY UPDATE clause (MySQL syntax).
+
+        Args:
+            **set_values: Column-value pairs to update on duplicate key.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        return self

sqlspec/statement/builder/merge.py

@@ -0,0 +1,95 @@
+"""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.
+"""
+
+from dataclasses import dataclass
+
+from sqlglot import exp
+
+from sqlspec.statement.builder.base import QueryBuilder
+from sqlspec.statement.builder.mixins import (
+    MergeIntoClauseMixin,
+    MergeMatchedClauseMixin,
+    MergeNotMatchedBySourceClauseMixin,
+    MergeNotMatchedClauseMixin,
+    MergeOnClauseMixin,
+    MergeUsingClauseMixin,
+)
+from sqlspec.statement.result import SQLResult
+from sqlspec.typing import RowT
+
+__all__ = ("MergeBuilder",)
+
+
+@dataclass(unsafe_hash=True)
+class MergeBuilder(
+    QueryBuilder[RowT],
+    MergeUsingClauseMixin,
+    MergeOnClauseMixin,
+    MergeMatchedClauseMixin,
+    MergeNotMatchedClauseMixin,
+    MergeIntoClauseMixin,
+    MergeNotMatchedBySourceClauseMixin,
+):
+    """Builder for MERGE statements.
+
+    This builder provides a fluent interface for constructing SQL MERGE statements
+    (also known as UPSERT in some databases) with automatic parameter binding and validation.
+
+    Example:
+        ```python
+        # Basic MERGE statement
+        merge_query = (
+            MergeBuilder()
+            .into("target_table")
+            .using("source_table", "src")
+            .on("target_table.id = src.id")
+            .when_matched_then_update(
+                {"name": "src.name", "updated_at": "NOW()"}
+            )
+            .when_not_matched_then_insert(
+                columns=["id", "name", "created_at"],
+                values=["src.id", "src.name", "NOW()"],
+            )
+        )
+
+        # MERGE with subquery source
+        source_query = (
+            SelectBuilder()
+            .select("id", "name", "email")
+            .from_("temp_users")
+            .where("status = 'pending'")
+        )
+
+        merge_query = (
+            MergeBuilder()
+            .into("users")
+            .using(source_query, "src")
+            .on("users.email = src.email")
+            .when_matched_then_update({"name": "src.name"})
+            .when_not_matched_then_insert(
+                columns=["id", "name", "email"],
+                values=["src.id", "src.name", "src.email"],
+            )
+        )
+        ```
+    """
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+        """Return the expected result type for this builder.
+
+        Returns:
+            The SQLResult type for MERGE statements.
+        """
+        return SQLResult[RowT]
+
+    def _create_base_expression(self) -> "exp.Merge":
+        """Create a base MERGE expression.
+
+        Returns:
+            A new sqlglot Merge expression with empty clauses.
+        """
+        return exp.Merge(this=None, using=None, on=None, whens=exp.Whens(expressions=[]))

sqlspec/statement/builder/mixins/__init__.py

@@ -0,0 +1,65 @@
+"""SQL statement builder mixins."""
+
+from sqlspec.statement.builder.mixins._aggregate_functions import AggregateFunctionsMixin
+from sqlspec.statement.builder.mixins._case_builder import CaseBuilderMixin
+from sqlspec.statement.builder.mixins._common_table_expr import CommonTableExpressionMixin
+from sqlspec.statement.builder.mixins._delete_from import DeleteFromClauseMixin
+from sqlspec.statement.builder.mixins._from import FromClauseMixin
+from sqlspec.statement.builder.mixins._group_by import GroupByClauseMixin
+from sqlspec.statement.builder.mixins._having import HavingClauseMixin
+from sqlspec.statement.builder.mixins._insert_from_select import InsertFromSelectMixin
+from sqlspec.statement.builder.mixins._insert_into import InsertIntoClauseMixin
+from sqlspec.statement.builder.mixins._insert_values import InsertValuesMixin
+from sqlspec.statement.builder.mixins._join import JoinClauseMixin
+from sqlspec.statement.builder.mixins._limit_offset import LimitOffsetClauseMixin
+from sqlspec.statement.builder.mixins._merge_clauses import (
+    MergeIntoClauseMixin,
+    MergeMatchedClauseMixin,
+    MergeNotMatchedBySourceClauseMixin,
+    MergeNotMatchedClauseMixin,
+    MergeOnClauseMixin,
+    MergeUsingClauseMixin,
+)
+from sqlspec.statement.builder.mixins._order_by import OrderByClauseMixin
+from sqlspec.statement.builder.mixins._pivot import PivotClauseMixin
+from sqlspec.statement.builder.mixins._returning import ReturningClauseMixin
+from sqlspec.statement.builder.mixins._select_columns import SelectColumnsMixin
+from sqlspec.statement.builder.mixins._set_ops import SetOperationMixin
+from sqlspec.statement.builder.mixins._unpivot import UnpivotClauseMixin
+from sqlspec.statement.builder.mixins._update_from import UpdateFromClauseMixin
+from sqlspec.statement.builder.mixins._update_set import UpdateSetClauseMixin
+from sqlspec.statement.builder.mixins._update_table import UpdateTableClauseMixin
+from sqlspec.statement.builder.mixins._where import WhereClauseMixin
+from sqlspec.statement.builder.mixins._window_functions import WindowFunctionsMixin
+
+__all__ = (
+    "AggregateFunctionsMixin",
+    "CaseBuilderMixin",
+    "CommonTableExpressionMixin",
+    "DeleteFromClauseMixin",
+    "FromClauseMixin",
+    "GroupByClauseMixin",
+    "HavingClauseMixin",
+    "InsertFromSelectMixin",
+    "InsertIntoClauseMixin",
+    "InsertValuesMixin",
+    "JoinClauseMixin",
+    "LimitOffsetClauseMixin",
+    "MergeIntoClauseMixin",
+    "MergeMatchedClauseMixin",
+    "MergeNotMatchedBySourceClauseMixin",
+    "MergeNotMatchedClauseMixin",
+    "MergeOnClauseMixin",
+    "MergeUsingClauseMixin",
+    "OrderByClauseMixin",
+    "PivotClauseMixin",
+    "ReturningClauseMixin",
+    "SelectColumnsMixin",
+    "SetOperationMixin",
+    "UnpivotClauseMixin",
+    "UpdateFromClauseMixin",
+    "UpdateSetClauseMixin",
+    "UpdateTableClauseMixin",
+    "WhereClauseMixin",
+    "WindowFunctionsMixin",
+)

sqlspec/statement/builder/mixins/_aggregate_functions.py

@@ -0,0 +1,151 @@
+from typing import TYPE_CHECKING, Optional, Union, cast
+
+from sqlglot import exp
+from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from sqlspec.statement.builder.protocols import SelectBuilderProtocol
+
+__all__ = ("AggregateFunctionsMixin",)
+
+
+class AggregateFunctionsMixin:
+    """Mixin providing aggregate function methods for SQL builders."""
+
+    def count_(self, column: "Union[str, exp.Expression]" = "*", alias: Optional[str] = None) -> Self:
+        """Add COUNT function to SELECT clause.
+
+        Args:
+            column: The column to count (default is "*").
+            alias: Optional alias for the count.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        if column == "*":
+            count_expr = exp.Count(this=exp.Star())
+        else:
+            col_expr = exp.column(column) if isinstance(column, str) else column
+            count_expr = exp.Count(this=col_expr)
+
+        select_expr = exp.alias_(count_expr, alias) if alias else count_expr
+        return cast("Self", builder.select(select_expr))
+
+    def sum_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add SUM function to SELECT clause.
+
+        Args:
+            column: The column to sum.
+            alias: Optional alias for the sum.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        sum_expr = exp.Sum(this=col_expr)
+        select_expr = exp.alias_(sum_expr, alias) if alias else sum_expr
+        return cast("Self", builder.select(select_expr))
+
+    def avg_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add AVG function to SELECT clause.
+
+        Args:
+            column: The column to average.
+            alias: Optional alias for the average.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        avg_expr = exp.Avg(this=col_expr)
+        select_expr = exp.alias_(avg_expr, alias) if alias else avg_expr
+        return cast("Self", builder.select(select_expr))
+
+    def max_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add MAX function to SELECT clause.
+
+        Args:
+            column: The column to find the maximum of.
+            alias: Optional alias for the maximum.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        max_expr = exp.Max(this=col_expr)
+        select_expr = exp.alias_(max_expr, alias) if alias else max_expr
+        return cast("Self", builder.select(select_expr))
+
+    def min_(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add MIN function to SELECT clause.
+
+        Args:
+            column: The column to find the minimum of.
+            alias: Optional alias for the minimum.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        min_expr = exp.Min(this=col_expr)
+        select_expr = exp.alias_(min_expr, alias) if alias else min_expr
+        return cast("Self", builder.select(select_expr))
+
+    def array_agg(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add ARRAY_AGG aggregate function to SELECT clause.
+
+        Args:
+            column: The column to aggregate into an array.
+            alias: Optional alias for the result.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        array_agg_expr = exp.ArrayAgg(this=col_expr)
+        select_expr = exp.alias_(array_agg_expr, alias) if alias else array_agg_expr
+        return cast("Self", builder.select(select_expr))
+
+    def bool_and(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add BOOL_AND aggregate function to SELECT clause (PostgreSQL, DuckDB, etc).
+
+        Args:
+            column: The boolean column to aggregate.
+            alias: Optional alias for the result.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Note:
+            Uses exp.Anonymous for BOOL_AND. Not all dialects support this function.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        bool_and_expr = exp.Anonymous(this="BOOL_AND", expressions=[col_expr])
+        select_expr = exp.alias_(bool_and_expr, alias) if alias else bool_and_expr
+        return cast("Self", builder.select(select_expr))
+
+    def bool_or(self, column: Union[str, exp.Expression], alias: Optional[str] = None) -> Self:
+        """Add BOOL_OR aggregate function to SELECT clause (PostgreSQL, DuckDB, etc).
+
+        Args:
+            column: The boolean column to aggregate.
+            alias: Optional alias for the result.
+
+        Returns:
+            The current builder instance for method chaining.
+
+        Note:
+            Uses exp.Anonymous for BOOL_OR. Not all dialects support this function.
+        """
+        builder = cast("SelectBuilderProtocol", self)
+        col_expr = exp.column(column) if isinstance(column, str) else column
+        bool_or_expr = exp.Anonymous(this="BOOL_OR", expressions=[col_expr])
+        select_expr = exp.alias_(bool_or_expr, alias) if alias else bool_or_expr
+        return cast("Self", builder.select(select_expr))