sqlspec 0.16.1__cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/builder/_ddl_utils.py

@@ -0,0 +1,103 @@
+"""DDL builder utilities."""
+
+from typing import TYPE_CHECKING, Optional
+
+from sqlglot import exp
+
+if TYPE_CHECKING:
+    from sqlspec.builder._ddl import ColumnDefinition, ConstraintDefinition
+
+__all__ = ("build_column_expression", "build_constraint_expression")
+
+
+def build_column_expression(col: "ColumnDefinition") -> "exp.Expression":
+    """Build SQLGlot expression for a column definition."""
+    col_def = exp.ColumnDef(this=exp.to_identifier(col.name), kind=exp.DataType.build(col.dtype))
+
+    constraints: list[exp.ColumnConstraint] = []
+
+    if col.not_null:
+        constraints.append(exp.ColumnConstraint(kind=exp.NotNullColumnConstraint()))
+
+    if col.primary_key:
+        constraints.append(exp.ColumnConstraint(kind=exp.PrimaryKeyColumnConstraint()))
+
+    if col.unique:
+        constraints.append(exp.ColumnConstraint(kind=exp.UniqueColumnConstraint()))
+
+    if col.default is not None:
+        default_expr: Optional[exp.Expression] = None
+        if isinstance(col.default, str):
+            if col.default.upper() in {"CURRENT_TIMESTAMP", "CURRENT_DATE", "CURRENT_TIME"} or "(" in col.default:
+                default_expr = exp.maybe_parse(col.default)
+            else:
+                default_expr = exp.convert(col.default)
+        else:
+            default_expr = exp.convert(col.default)
+
+        constraints.append(exp.ColumnConstraint(kind=default_expr))
+
+    if col.check:
+        check_expr = exp.Check(this=exp.maybe_parse(col.check))
+        constraints.append(exp.ColumnConstraint(kind=check_expr))
+
+    if col.comment:
+        constraints.append(exp.ColumnConstraint(kind=exp.CommentColumnConstraint(this=exp.convert(col.comment))))
+
+    if col.generated:
+        generated_expr = exp.GeneratedAsIdentityColumnConstraint(this=exp.maybe_parse(col.generated))
+        constraints.append(exp.ColumnConstraint(kind=generated_expr))
+
+    if col.collate:
+        constraints.append(exp.ColumnConstraint(kind=exp.CollateColumnConstraint(this=exp.to_identifier(col.collate))))
+
+    if constraints:
+        col_def.set("constraints", constraints)
+
+    return col_def
+
+
+def build_constraint_expression(constraint: "ConstraintDefinition") -> "Optional[exp.Expression]":
+    """Build SQLGlot expression for a table constraint."""
+    if constraint.constraint_type == "PRIMARY KEY":
+        pk_cols = [exp.to_identifier(col) for col in constraint.columns]
+        pk_constraint = exp.PrimaryKey(expressions=pk_cols)
+
+        if constraint.name:
+            return exp.Constraint(this=exp.to_identifier(constraint.name), expression=pk_constraint)
+        return pk_constraint
+
+    if constraint.constraint_type == "FOREIGN KEY":
+        fk_cols = [exp.to_identifier(col) for col in constraint.columns]
+        ref_cols = [exp.to_identifier(col) for col in constraint.references_columns]
+
+        fk_constraint = exp.ForeignKey(
+            expressions=fk_cols,
+            reference=exp.Reference(
+                this=exp.to_table(constraint.references_table) if constraint.references_table else None,
+                expressions=ref_cols,
+                on_delete=constraint.on_delete,
+                on_update=constraint.on_update,
+            ),
+        )
+
+        if constraint.name:
+            return exp.Constraint(this=exp.to_identifier(constraint.name), expression=fk_constraint)
+        return fk_constraint
+
+    if constraint.constraint_type == "UNIQUE":
+        unique_cols = [exp.to_identifier(col) for col in constraint.columns]
+        unique_constraint = exp.UniqueKeyProperty(expressions=unique_cols)
+
+        if constraint.name:
+            return exp.Constraint(this=exp.to_identifier(constraint.name), expression=unique_constraint)
+        return unique_constraint
+
+    if constraint.constraint_type == "CHECK":
+        check_expr = exp.Check(this=exp.maybe_parse(constraint.condition) if constraint.condition else None)
+
+        if constraint.name:
+            return exp.Constraint(this=exp.to_identifier(constraint.name), expression=check_expr)
+        return check_expr
+
+    return None

sqlspec/builder/_delete.py

@@ -0,0 +1,76 @@
+"""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 typing import Any, Optional
+
+from sqlglot import exp
+
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder.mixins import DeleteFromClauseMixin, ReturningClauseMixin, WhereClauseMixin
+from sqlspec.core.result import SQLResult
+from sqlspec.exceptions import SQLBuilderError
+
+__all__ = ("Delete",)
+
+
+class Delete(QueryBuilder, 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.
+    """
+
+    __slots__ = ("_table",)
+    _expression: Optional[exp.Expression]
+
+    def __init__(self, table: Optional[str] = None, **kwargs: Any) -> None:
+        """Initialize DELETE with optional table.
+
+        Args:
+            table: Target table name
+            **kwargs: Additional QueryBuilder arguments
+        """
+        super().__init__(**kwargs)
+        self._initialize_expression()
+
+        self._table = None
+
+        if table:
+            self.from_(table)
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult]":
+        """Get the expected result type for DELETE operations.
+
+        Returns:
+            The ExecuteResult type for DELETE statements.
+        """
+        return SQLResult
+
+    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:
+            msg = "DELETE requires a table to be specified. Use from() to set the table."
+            raise SQLBuilderError(msg)
+
+        return super().build()

sqlspec/builder/_insert.py

@@ -0,0 +1,256 @@
+"""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 typing import TYPE_CHECKING, Any, Final, Optional
+
+from sqlglot import exp
+from typing_extensions import Self
+
+from sqlspec.builder._base import QueryBuilder
+from sqlspec.builder.mixins import InsertFromSelectMixin, InsertIntoClauseMixin, InsertValuesMixin, ReturningClauseMixin
+from sqlspec.core.result import SQLResult
+from sqlspec.exceptions import SQLBuilderError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+
+__all__ = ("Insert",)
+
+ERR_MSG_TABLE_NOT_SET: Final[str] = "The target table must be set using .into() before adding values."
+ERR_MSG_VALUES_COLUMNS_MISMATCH: Final[str] = (
+    "Number of values ({values_len}) does not match the number of specified columns ({columns_len})."
+)
+ERR_MSG_INTERNAL_EXPRESSION_TYPE: Final[str] = "Internal error: expression is not an Insert instance as expected."
+ERR_MSG_EXPRESSION_NOT_INITIALIZED: Final[str] = "Internal error: base expression not initialized."
+
+
+class Insert(QueryBuilder, 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.
+    """
+
+    __slots__ = ("_columns", "_table", "_values_added_count")
+
+    def __init__(self, table: Optional[str] = None, **kwargs: Any) -> None:
+        """Initialize INSERT with optional table.
+
+        Args:
+            table: Target table name
+            **kwargs: Additional QueryBuilder arguments
+        """
+        super().__init__(**kwargs)
+
+        # Initialize Insert-specific attributes
+        self._table: Optional[str] = None
+        self._columns: list[str] = []
+        self._values_added_count: int = 0
+
+        self._initialize_expression()
+
+        if table:
+            self.into(table)
+
+    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]":
+        """Specifies the expected result type for an INSERT query.
+
+        Returns:
+            The type of result expected for INSERT operations.
+        """
+        return SQLResult
+
+    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, **kwargs: 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 (...), (...)`.
+
+        Supports:
+        - values(val1, val2, val3)
+        - values(col1=val1, col2=val2)
+        - values(mapping)
+
+        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.
+            **kwargs: Column-value pairs for named values.
+
+        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)
+
+        if kwargs:
+            if values:
+                msg = "Cannot mix positional values with keyword values."
+                raise SQLBuilderError(msg)
+            return self.values_from_dict(kwargs)
+
+        if len(values) == 1:
+            try:
+                values_0 = values[0]
+                if hasattr(values_0, "items"):
+                    return self.values_from_dict(values_0)
+            except (AttributeError, TypeError):
+                pass
+
+        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)
+
+        value_placeholders: list[exp.Expression] = []
+        for i, value in enumerate(values):
+            if isinstance(value, exp.Expression):
+                value_placeholders.append(value)
+            else:
+                if self._columns and i < len(self._columns):
+                    column_str = str(self._columns[i])
+                    column_name = column_str.rsplit(".", maxsplit=1)[-1] if "." in column_str else column_str
+                    param_name = self._generate_unique_parameter_name(column_name)
+                else:
+                    param_name = self._generate_unique_parameter_name(f"value_{i + 1}")
+                _, param_name = self.add_parameter(value, name=param_name)
+                value_placeholders.append(exp.var(param_name))
+
+        tuple_expr = exp.Tuple(expressions=value_placeholders)
+        if self._values_added_count == 0:
+            insert_expr.set("expression", exp.Values(expressions=[tuple_expr]))
+        else:
+            current_values = insert_expr.args.get("expression")
+            if isinstance(current_values, exp.Values):
+                current_values.expressions.append(tuple_expr)
+            else:
+                insert_expr.set("expression", exp.Values(expressions=[tuple_expr]))
+
+        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)
+
+        data_keys = list(data.keys())
+        if not self._columns:
+            self.columns(*data_keys)
+        elif set(self._columns) != set(data_keys):
+            msg = f"Dictionary keys {set(data_keys)} do not match existing columns {set(self._columns)}."
+            raise SQLBuilderError(msg)
+
+        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
+
+        first_dict = data[0]
+        if not self._columns:
+            self.columns(*first_dict.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)
+
+        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()
+        insert_expr.set("on", exp.OnConflict(this=None, expressions=[]))
+        return self
+
+    def on_duplicate_key_update(self, **_: Any) -> "Self":
+        """Adds an ON DUPLICATE KEY UPDATE clause (MySQL syntax).
+
+        Args:
+            **_: Column-value pairs to update on duplicate key.
+
+        Returns:
+            The current builder instance for method chaining.
+        """
+        return self

sqlspec/builder/_merge.py

@@ -0,0 +1,71 @@
+"""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 typing import Any, Optional
+
+from sqlglot import exp
+
+from sqlspec.builder._base import QueryBuilder
+from sqlspec.builder.mixins import (
+    MergeIntoClauseMixin,
+    MergeMatchedClauseMixin,
+    MergeNotMatchedBySourceClauseMixin,
+    MergeNotMatchedClauseMixin,
+    MergeOnClauseMixin,
+    MergeUsingClauseMixin,
+)
+from sqlspec.core.result import SQLResult
+
+__all__ = ("Merge",)
+
+
+class Merge(
+    QueryBuilder,
+    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.
+    """
+
+    __slots__ = ()
+    _expression: Optional[exp.Expression]
+
+    def __init__(self, target_table: Optional[str] = None, **kwargs: Any) -> None:
+        """Initialize MERGE with optional target table.
+
+        Args:
+            target_table: Target table name
+            **kwargs: Additional QueryBuilder arguments
+        """
+        super().__init__(**kwargs)
+        self._initialize_expression()
+
+        if target_table:
+            self.into(target_table)
+
+    @property
+    def _expected_result_type(self) -> "type[SQLResult]":
+        """Return the expected result type for this builder.
+
+        Returns:
+            The SQLResult type for MERGE statements.
+        """
+        return SQLResult
+
+    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/builder/_parsing_utils.py

@@ -0,0 +1,140 @@
+"""Centralized parsing utilities for SQLSpec builders.
+
+This module provides common parsing functions to handle complex SQL expressions
+that users might pass as strings to various builder methods.
+"""
+
+import contextlib
+from typing import Any, Final, Optional, Union, cast
+
+from sqlglot import exp, maybe_parse, parse_one
+
+from sqlspec.utils.type_guards import has_expression_attr, has_parameter_builder
+
+
+def parse_column_expression(column_input: Union[str, exp.Expression, Any]) -> exp.Expression:
+    """Parse a column input that might be a complex expression.
+
+    Handles cases like:
+    - Simple column names: "name" -> Column(this=name)
+    - Qualified names: "users.name" -> Column(table=users, this=name)
+    - Aliased columns: "name AS user_name" -> Alias(this=Column(name), alias=user_name)
+    - Function calls: "MAX(price)" -> Max(this=Column(price))
+    - Complex expressions: "CASE WHEN ... END" -> Case(...)
+    - Custom Column objects from our builder
+
+    Args:
+        column_input: String, SQLGlot expression, or Column object
+
+    Returns:
+        exp.Expression: Parsed SQLGlot expression
+    """
+    if isinstance(column_input, exp.Expression):
+        return column_input
+
+    if has_expression_attr(column_input):
+        try:
+            attr_value = column_input._expression
+            if isinstance(attr_value, exp.Expression):
+                return attr_value
+        except AttributeError:
+            pass
+
+    return exp.maybe_parse(column_input) or exp.column(str(column_input))
+
+
+def parse_table_expression(table_input: str, explicit_alias: Optional[str] = None) -> exp.Expression:
+    """Parses a table string that can be a name, a name with an alias, or a subquery string."""
+    with contextlib.suppress(Exception):
+        parsed = parse_one(f"SELECT * FROM {table_input}")
+        if isinstance(parsed, exp.Select) and parsed.args.get("from"):
+            from_clause = cast("exp.From", parsed.args.get("from"))
+            table_expr = from_clause.this
+
+            if explicit_alias:
+                return exp.alias_(table_expr, explicit_alias)  # type:ignore[no-any-return]
+            return table_expr  # type:ignore[no-any-return]
+
+    return exp.to_table(table_input, alias=explicit_alias)
+
+
+def parse_order_expression(order_input: Union[str, exp.Expression]) -> exp.Expression:
+    """Parse an ORDER BY expression that might include direction.
+
+    Handles cases like:
+    - Simple column: "name" -> Column(this=name)
+    - With direction: "name DESC" -> Ordered(this=Column(name), desc=True)
+    - Qualified: "users.name ASC" -> Ordered(this=Column(table=users, this=name), desc=False)
+    - Function: "COUNT(*) DESC" -> Ordered(this=Count(this=Star), desc=True)
+
+    Args:
+        order_input: String or SQLGlot expression for ORDER BY
+
+    Returns:
+        exp.Expression: Parsed SQLGlot expression (usually Ordered or Column)
+    """
+    if isinstance(order_input, exp.Expression):
+        return order_input
+
+    with contextlib.suppress(Exception):
+        parsed = maybe_parse(str(order_input), into=exp.Ordered)
+        if parsed:
+            return parsed
+
+    return parse_column_expression(order_input)
+
+
+def parse_condition_expression(
+    condition_input: Union[str, exp.Expression, tuple[str, Any]], builder: "Any" = None
+) -> exp.Expression:
+    """Parse a condition that might be complex SQL.
+
+    Handles cases like:
+    - Simple conditions: "name = 'John'" -> EQ(Column(name), Literal('John'))
+    - Tuple format: ("name", "John") -> EQ(Column(name), Literal('John'))
+    - Complex conditions: "age > 18 AND status = 'active'" -> And(GT(...), EQ(...))
+    - Function conditions: "LENGTH(name) > 5" -> GT(Length(Column(name)), Literal(5))
+
+    Args:
+        condition_input: String, tuple, or SQLGlot expression for condition
+        builder: Optional builder instance for parameter binding
+
+    Returns:
+        exp.Expression: Parsed SQLGlot expression (usually a comparison or logical op)
+    """
+    if isinstance(condition_input, exp.Expression):
+        return condition_input
+
+    tuple_condition_parts: Final[int] = 2
+    if isinstance(condition_input, tuple) and len(condition_input) == tuple_condition_parts:
+        column, value = condition_input
+        column_expr = parse_column_expression(column)
+        if value is None:
+            return exp.Is(this=column_expr, expression=exp.null())
+        if builder and has_parameter_builder(builder):
+            from sqlspec.builder.mixins._where_clause import _extract_column_name
+
+            column_name = _extract_column_name(column)
+            param_name = builder._generate_unique_parameter_name(column_name)
+            _, param_name = builder.add_parameter(value, name=param_name)
+            return exp.EQ(this=column_expr, expression=exp.Placeholder(this=param_name))
+        if isinstance(value, str):
+            return exp.EQ(this=column_expr, expression=exp.convert(value))
+        if isinstance(value, (int, float)):
+            return exp.EQ(this=column_expr, expression=exp.convert(str(value)))
+        return exp.EQ(this=column_expr, expression=exp.convert(str(value)))
+
+    if not isinstance(condition_input, str):
+        condition_input = str(condition_input)
+
+    try:
+        return exp.condition(condition_input)
+    except Exception:
+        try:
+            parsed = exp.maybe_parse(condition_input)  # type: ignore[var-annotated]
+            return parsed or exp.condition(condition_input)
+        except Exception:
+            return exp.condition(condition_input)
+
+
+__all__ = ("parse_column_expression", "parse_condition_expression", "parse_order_expression", "parse_table_expression")