sqlspec 0.15.0__tar.gz → 0.16.0__tar.gz

{sqlspec-0.15.0 → sqlspec-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.15.0
+Version: 0.16.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/

{sqlspec-0.15.0 → sqlspec-0.16.0}/pyproject.toml

@@ -13,7 +13,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.9, <4.0"
-version = "0.15.0"
+version = "0.16.0"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/_sql.py

@@ -4,17 +4,65 @@ Provides both statement builders (select, insert, update, etc.) and column expre
 """
 
 import logging
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 import sqlglot
 from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from sqlglot.errors import ParseError as SQLGlotParseError
 
-from sqlspec.builder import Column, Delete, Insert, Merge, Select, Truncate, Update
+from sqlspec.builder import (
+    AlterTable,
+    Column,
+    CommentOn,
+    CreateIndex,
+    CreateMaterializedView,
+    CreateSchema,
+    CreateTable,
+    CreateTableAsSelect,
+    CreateView,
+    Delete,
+    DropIndex,
+    DropSchema,
+    DropTable,
+    DropView,
+    Insert,
+    Merge,
+    RenameTable,
+    Select,
+    Truncate,
+    Update,
+)
 from sqlspec.exceptions import SQLBuilderError
 
-__all__ = ("Case", "Column", "Delete", "Insert", "Merge", "SQLFactory", "Select", "Truncate", "Update", "sql")
+if TYPE_CHECKING:
+    from sqlspec.core.statement import SQL
+
+__all__ = (
+    "AlterTable",
+    "Case",
+    "Column",
+    "CommentOn",
+    "CreateIndex",
+    "CreateMaterializedView",
+    "CreateSchema",
+    "CreateTable",
+    "CreateTableAsSelect",
+    "CreateView",
+    "Delete",
+    "DropIndex",
+    "DropSchema",
+    "DropTable",
+    "DropView",
+    "Insert",
+    "Merge",
+    "RenameTable",
+    "SQLFactory",
+    "Select",
+    "Truncate",
+    "Update",
+    "sql",
+)
 
 logger = logging.getLogger("sqlspec")
 
@@ -212,6 +260,174 @@ class SQLFactory:
             return builder.into(table_or_sql)
         return builder
 
+    # ===================
+    # DDL Statement Builders
+    # ===================
+
+    def create_table(self, table_name: str, dialect: DialectType = None) -> "CreateTable":
+        """Create a CREATE TABLE builder.
+
+        Args:
+            table_name: Name of the table to create
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateTable builder instance
+        """
+        builder = CreateTable(table_name)
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_table_as_select(self, dialect: DialectType = None) -> "CreateTableAsSelect":
+        """Create a CREATE TABLE AS SELECT builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateTableAsSelect builder instance
+        """
+        builder = CreateTableAsSelect()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_view(self, dialect: DialectType = None) -> "CreateView":
+        """Create a CREATE VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateView builder instance
+        """
+        builder = CreateView()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_materialized_view(self, dialect: DialectType = None) -> "CreateMaterializedView":
+        """Create a CREATE MATERIALIZED VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateMaterializedView builder instance
+        """
+        builder = CreateMaterializedView()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_index(self, index_name: str, dialect: DialectType = None) -> "CreateIndex":
+        """Create a CREATE INDEX builder.
+
+        Args:
+            index_name: Name of the index to create
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateIndex builder instance
+        """
+        return CreateIndex(index_name, dialect=dialect or self.dialect)
+
+    def create_schema(self, dialect: DialectType = None) -> "CreateSchema":
+        """Create a CREATE SCHEMA builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateSchema builder instance
+        """
+        builder = CreateSchema()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def drop_table(self, table_name: str, dialect: DialectType = None) -> "DropTable":
+        """Create a DROP TABLE builder.
+
+        Args:
+            table_name: Name of the table to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropTable builder instance
+        """
+        return DropTable(table_name, dialect=dialect or self.dialect)
+
+    def drop_view(self, dialect: DialectType = None) -> "DropView":
+        """Create a DROP VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropView builder instance
+        """
+        return DropView(dialect=dialect or self.dialect)
+
+    def drop_index(self, index_name: str, dialect: DialectType = None) -> "DropIndex":
+        """Create a DROP INDEX builder.
+
+        Args:
+            index_name: Name of the index to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropIndex builder instance
+        """
+        return DropIndex(index_name, dialect=dialect or self.dialect)
+
+    def drop_schema(self, dialect: DialectType = None) -> "DropSchema":
+        """Create a DROP SCHEMA builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropSchema builder instance
+        """
+        return DropSchema(dialect=dialect or self.dialect)
+
+    def alter_table(self, table_name: str, dialect: DialectType = None) -> "AlterTable":
+        """Create an ALTER TABLE builder.
+
+        Args:
+            table_name: Name of the table to alter
+            dialect: Optional SQL dialect
+
+        Returns:
+            AlterTable builder instance
+        """
+        builder = AlterTable(table_name)
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def rename_table(self, dialect: DialectType = None) -> "RenameTable":
+        """Create a RENAME TABLE builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            RenameTable builder instance
+        """
+        builder = RenameTable()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def comment_on(self, dialect: DialectType = None) -> "CommentOn":
+        """Create a COMMENT ON builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CommentOn builder instance
+        """
+        builder = CommentOn()
+        builder.dialect = dialect or self.dialect
+        return builder
+
     # ===================
     # SQL Analysis Helpers
     # ===================
@@ -363,8 +579,8 @@ class SQLFactory:
     # ===================
 
     @staticmethod
-    def raw(sql_fragment: str) -> exp.Expression:
-        """Create a raw SQL expression from a string fragment.
+    def raw(sql_fragment: str, **parameters: Any) -> "Union[exp.Expression, SQL]":
+        """Create a raw SQL expression from a string fragment with optional parameters.
 
         This method makes it explicit that you are passing raw SQL that should
         be parsed and included directly in the query. Useful for complex expressions,
@@ -372,30 +588,30 @@ class SQLFactory:
 
         Args:
             sql_fragment: Raw SQL string to parse into an expression.
+            **parameters: Named parameters for parameter binding.
 
         Returns:
-            SQLGlot expression from the parsed SQL fragment.
+            SQLGlot expression from the parsed SQL fragment (if no parameters).
+            SQL statement object (if parameters provided).
 
         Raises:
             SQLBuilderError: If the SQL fragment cannot be parsed.
 
         Example:
             ```python
-            # Raw column expression with alias
-            query = sql.select(
-                sql.raw("user.id AS u_id"), "name"
-            ).from_("users")
+            # Raw expression without parameters (current behavior)
+            expr = sql.raw("COALESCE(name, 'Unknown')")
 
-            # Raw function call
-            query = sql.select(
-                sql.raw("COALESCE(name, 'Unknown')")
-            ).from_("users")
+            # Raw SQL with named parameters (new functionality)
+            stmt = sql.raw(
+                "LOWER(name) LIKE LOWER(:pattern)", pattern=f"%{query}%"
+            )
 
-            # Raw complex expression
-            query = (
-                sql.select("*")
-                .from_("orders")
-                .where(sql.raw("DATE(created_at) = CURRENT_DATE"))
+            # Raw complex expression with parameters
+            expr = sql.raw(
+                "price BETWEEN :min_price AND :max_price",
+                min_price=100,
+                max_price=500,
             )
 
             # Raw window function
@@ -407,16 +623,23 @@ class SQLFactory:
             ).from_("employees")
             ```
         """
-        try:
-            parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
-            if parsed is not None:
-                return parsed
-            if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
-                return exp.to_identifier(sql_fragment)
-            return exp.Literal.string(sql_fragment)
-        except Exception as e:
-            msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
-            raise SQLBuilderError(msg) from e
+        if not parameters:
+            # Original behavior - return pure expression
+            try:
+                parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
+                if parsed is not None:
+                    return parsed
+                if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
+                    return exp.to_identifier(sql_fragment)
+                return exp.Literal.string(sql_fragment)
+            except Exception as e:
+                msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
+                raise SQLBuilderError(msg) from e
+
+        # New behavior - return SQL statement with parameters
+        from sqlspec.core.statement import SQL
+
+        return SQL(sql_fragment, parameters)
 
     # ===================
     # Aggregate Functions

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/builder/_insert.py

@@ -119,7 +119,18 @@ class Insert(QueryBuilder, ReturningClauseMixin, InsertValuesMixin, InsertFromSe
             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]
+        param_names = []
+        for i, value in enumerate(values):
+            # Try to use column name if available, otherwise use position-based name
+            if self._columns and i < len(self._columns):
+                column_name = (
+                    str(self._columns[i]).split(".")[-1] if "." in str(self._columns[i]) else str(self._columns[i])
+                )
+                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)
+            param_names.append(param_name)
         value_placeholders = tuple(exp.var(name) for name in param_names)
 
         current_values_expression = insert_expr.args.get("expression")

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/builder/_parsing_utils.py

@@ -109,7 +109,11 @@ def parse_condition_expression(
         if value is None:
             return exp.Is(this=column_expr, expression=exp.null())
         if builder and has_parameter_builder(builder):
-            _, param_name = builder.add_parameter(value)
+            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))

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/builder/mixins/_insert_operations.py

@@ -78,11 +78,21 @@ class InsertValuesMixin:
         except AttributeError:
             pass
         row_exprs = []
-        for v in values:
+        for i, v in enumerate(values):
             if isinstance(v, exp.Expression):
                 row_exprs.append(v)
             else:
-                _, param_name = self.add_parameter(v)  # type: ignore[attr-defined]
+                # Try to use column name if available, otherwise use position-based name
+                try:
+                    _columns = self._columns  # type: ignore[attr-defined]
+                    if _columns and i < len(_columns):
+                        column_name = str(_columns[i]).split(".")[-1] if "." in str(_columns[i]) else str(_columns[i])
+                        param_name = self._generate_unique_parameter_name(column_name)  # type: ignore[attr-defined]
+                    else:
+                        param_name = self._generate_unique_parameter_name(f"value_{i + 1}")  # type: ignore[attr-defined]
+                except AttributeError:
+                    param_name = self._generate_unique_parameter_name(f"value_{i + 1}")  # type: ignore[attr-defined]
+                _, param_name = self.add_parameter(v, name=param_name)  # type: ignore[attr-defined]
                 row_exprs.append(exp.var(param_name))
         values_expr = exp.Values(expressions=[row_exprs])
         self._expression.set("expression", values_expr)

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/builder/mixins/_merge_operations.py

@@ -172,7 +172,11 @@ class MergeMatchedClauseMixin:
         """
         update_expressions: list[exp.EQ] = []
         for col, val in set_values.items():
-            param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
+            column_name = col if isinstance(col, str) else str(col)
+            if "." in column_name:
+                column_name = column_name.split(".")[-1]
+            param_name = self._generate_unique_parameter_name(column_name)  # type: ignore[attr-defined]
+            param_name = self.add_parameter(val, name=param_name)[1]  # type: ignore[attr-defined]
             update_expressions.append(exp.EQ(this=exp.column(col), expression=exp.var(param_name)))
 
         when_args: dict[str, Any] = {"matched": True, "then": exp.Update(expressions=update_expressions)}
@@ -270,8 +274,12 @@ class MergeNotMatchedClauseMixin:
                 raise SQLBuilderError(msg)
 
             parameterized_values: list[exp.Expression] = []
-            for val in values:
-                param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
+            for i, val in enumerate(values):
+                column_name = columns[i] if isinstance(columns[i], str) else str(columns[i])
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)  # type: ignore[attr-defined]
+                param_name = self.add_parameter(val, name=param_name)[1]  # type: ignore[attr-defined]
                 parameterized_values.append(exp.var(param_name))
 
             insert_args["this"] = exp.Tuple(expressions=[exp.column(c) for c in columns])
@@ -336,7 +344,11 @@ class MergeNotMatchedBySourceClauseMixin:
         """
         update_expressions: list[exp.EQ] = []
         for col, val in set_values.items():
-            param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
+            column_name = col if isinstance(col, str) else str(col)
+            if "." in column_name:
+                column_name = column_name.split(".")[-1]
+            param_name = self._generate_unique_parameter_name(column_name)  # type: ignore[attr-defined]
+            param_name = self.add_parameter(val, name=param_name)[1]  # type: ignore[attr-defined]
             update_expressions.append(exp.EQ(this=exp.column(col), expression=exp.var(param_name)))
 
         when_args: dict[str, Any] = {

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/builder/mixins/_select_operations.py

@@ -563,7 +563,8 @@ class CaseBuilder:
             CaseBuilder: The current builder instance for method chaining.
         """
         cond_expr = exp.condition(condition) if isinstance(condition, str) else condition
-        param_name = self._parent.add_parameter(value)[1]
+        param_name = self._parent._generate_unique_parameter_name("case_when_value")
+        param_name = self._parent.add_parameter(value, name=param_name)[1]
         value_expr = exp.Placeholder(this=param_name)
 
         when_clause = exp.When(this=cond_expr, then=value_expr)
@@ -582,7 +583,8 @@ class CaseBuilder:
         Returns:
             CaseBuilder: The current builder instance for method chaining.
         """
-        param_name = self._parent.add_parameter(value)[1]
+        param_name = self._parent._generate_unique_parameter_name("case_else_value")
+        param_name = self._parent.add_parameter(value, name=param_name)[1]
         value_expr = exp.Placeholder(this=param_name)
         self._case_expr.set("default", value_expr)
         return self

{sqlspec-0.15.0 → sqlspec-0.16.0}/sqlspec/builder/mixins/_update_operations.py

@@ -81,7 +81,12 @@ class UpdateSetClauseMixin:
                     for p_name, p_value in val.parameters.items():
                         self.add_parameter(p_value, name=p_name)  # type: ignore[attr-defined]
             else:
-                param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
+                column_name = col if isinstance(col, str) else str(col)
+                # Extract just the column part if table.column format
+                if "." in column_name:
+                    column_name = column_name.split(".")[-1]
+                param_name = self._generate_unique_parameter_name(column_name)  # type: ignore[attr-defined]
+                param_name = self.add_parameter(val, name=param_name)[1]  # type: ignore[attr-defined]
                 value_expr = exp.Placeholder(this=param_name)
             assignments.append(exp.EQ(this=col_expr, expression=value_expr))
         elif (len(args) == 1 and isinstance(args[0], Mapping)) or kwargs:
@@ -97,7 +102,12 @@ class UpdateSetClauseMixin:
                         for p_name, p_value in val.parameters.items():
                             self.add_parameter(p_value, name=p_name)  # type: ignore[attr-defined]
                 else:
-                    param_name = self.add_parameter(val)[1]  # type: ignore[attr-defined]
+                    # Extract column name for parameter naming
+                    column_name = col if isinstance(col, str) else str(col)
+                    if "." in column_name:
+                        column_name = column_name.split(".")[-1]
+                    param_name = self._generate_unique_parameter_name(column_name)  # type: ignore[attr-defined]
+                    param_name = self.add_parameter(val, name=param_name)[1]  # type: ignore[attr-defined]
                     value_expr = exp.Placeholder(this=param_name)
                 assignments.append(exp.EQ(this=exp.column(col), expression=value_expr))
         else: