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

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

@@ -1,4 +1,4 @@
-# DDL builders for SQLSpec: DROP, CREATE INDEX, TRUNCATE, etc.
+"""DDL builders for SQLSpec: DROP, CREATE INDEX, TRUNCATE, etc."""
 
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Optional, Union
@@ -7,13 +7,13 @@ from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from typing_extensions import Self
 
-from sqlspec.statement.builder._base import QueryBuilder, SafeQuery
-from sqlspec.statement.builder._ddl_utils import build_column_expression, build_constraint_expression
-from sqlspec.statement.result import SQLResult
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder._ddl_utils import build_column_expression, build_constraint_expression
+from sqlspec.core.result import SQLResult
 
 if TYPE_CHECKING:
-    from sqlspec.statement.builder._column import ColumnExpression
-    from sqlspec.statement.sql import SQL, SQLConfig
+    from sqlspec.builder._column import ColumnExpression
+    from sqlspec.core.statement import SQL, StatementConfig
 
 __all__ = (
     "AlterOperation",
@@ -33,19 +33,18 @@ __all__ = (
     "DropTable",
     "DropView",
     "RenameTable",
-    "TruncateTable",
+    "Truncate",
 )
 
 
 @dataclass
-class DDLBuilder(QueryBuilder[Any]):
+class DDLBuilder(QueryBuilder):
     """Base class for DDL builders (CREATE, DROP, ALTER, etc)."""
 
     dialect: DialectType = None
     _expression: Optional[exp.Expression] = field(default=None, init=False, repr=False, compare=False, hash=False)
 
     def __post_init__(self) -> None:
-        # Override to prevent QueryBuilder from calling _create_base_expression prematurely
         pass
 
     def _create_base_expression(self) -> exp.Expression:
@@ -53,8 +52,7 @@ class DDLBuilder(QueryBuilder[Any]):
         raise NotImplementedError(msg)
 
     @property
-    def _expected_result_type(self) -> "type[SQLResult[Any]]":
-        # DDL typically returns no rows; use object for now.
+    def _expected_result_type(self) -> "type[SQLResult]":
         return SQLResult
 
     def build(self) -> "SafeQuery":
@@ -62,7 +60,7 @@ class DDLBuilder(QueryBuilder[Any]):
             self._expression = self._create_base_expression()
         return super().build()
 
-    def to_statement(self, config: "Optional[SQLConfig]" = None) -> "SQL":
+    def to_statement(self, config: "Optional[StatementConfig]" = None) -> "SQL":
         return super().to_statement(config=config)
 
 
@@ -209,10 +207,8 @@ class CreateTable(DDLBuilder):
 
     def primary_key_constraint(self, columns: "Union[str, list[str]]", name: "Optional[str]" = None) -> "Self":
         """Add a primary key constraint."""
-        # Normalize column list
         col_list = [columns] if isinstance(columns, str) else list(columns)
 
-        # Validation
         if not col_list:
             self._raise_sql_builder_error("Primary key must include at least one column")
 
@@ -362,16 +358,11 @@ class CreateTable(DDLBuilder):
         if self._tablespace:
             props.append(exp.Property(this=exp.to_identifier("TABLESPACE"), value=exp.to_identifier(self._tablespace)))
         if self._partition_by:
-            props.append(
-                exp.Property(this=exp.to_identifier("PARTITION BY"), value=exp.Literal.string(self._partition_by))
-            )
+            props.append(exp.Property(this=exp.to_identifier("PARTITION BY"), value=exp.convert(self._partition_by)))
 
         for key, value in self._table_options.items():
             if key != "engine":  # Skip already handled options
-                if isinstance(value, str):
-                    props.append(exp.Property(this=exp.to_identifier(key.upper()), value=exp.Literal.string(value)))
-                else:
-                    props.append(exp.Property(this=exp.to_identifier(key.upper()), value=exp.Literal.number(value)))
+                props.append(exp.Property(this=exp.to_identifier(key.upper()), value=exp.convert(value)))
 
         properties_node = exp.Properties(expressions=props) if props else None
 
@@ -651,7 +642,7 @@ class CreateIndex(DDLBuilder):
 
 # --- TRUNCATE TABLE ---
 @dataclass
-class TruncateTable(DDLBuilder):
+class Truncate(DDLBuilder):
     """Builder for TRUNCATE TABLE ... [CASCADE|RESTRICT] [RESTART IDENTITY|CONTINUE IDENTITY]."""
 
     _table_name: Optional[str] = None
@@ -791,16 +782,16 @@ class CreateTableAsSelect(DDLBuilder):
             self._raise_sql_builder_error("SELECT query must be set for CREATE TABLE AS SELECT.")
 
         select_expr = None
-        select_params = None
-        from sqlspec.statement.builder._select import Select
-        from sqlspec.statement.sql import SQL
+        select_parameters = None
+        from sqlspec.builder._select import Select
+        from sqlspec.core.statement import SQL
 
         if isinstance(self._select_query, SQL):
             select_expr = self._select_query.expression
-            select_params = getattr(self._select_query, "parameters", None)
+            select_parameters = getattr(self._select_query, "parameters", None)
         elif isinstance(self._select_query, Select):
             select_expr = getattr(self._select_query, "_expression", None)
-            select_params = getattr(self._select_query, "_parameters", None)
+            select_parameters = getattr(self._select_query, "_parameters", None)
 
             with_ctes = getattr(self._select_query, "_with_ctes", {})
             if with_ctes and select_expr and isinstance(select_expr, exp.Select):
@@ -813,15 +804,15 @@ class CreateTableAsSelect(DDLBuilder):
                         )
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
-            select_params = None
+            select_parameters = None
         else:
             self._raise_sql_builder_error("Unsupported type for SELECT query in CTAS.")
         if select_expr is None:
             self._raise_sql_builder_error("SELECT query must be a valid SELECT expression.")
 
         # Merge parameters from SELECT if present
-        if select_params:
-            for p_name, p_value in select_params.items():
+        if select_parameters:
+            for p_name, p_value in select_parameters.items():
                 # Always preserve the original parameter name
                 # The SELECT query already has unique parameter names
                 self._parameters[p_name] = p_value
@@ -908,27 +899,27 @@ class CreateMaterializedView(DDLBuilder):
             self._raise_sql_builder_error("SELECT query must be set for CREATE MATERIALIZED VIEW.")
 
         select_expr = None
-        select_params = None
-        from sqlspec.statement.builder._select import Select
-        from sqlspec.statement.sql import SQL
+        select_parameters = None
+        from sqlspec.builder._select import Select
+        from sqlspec.core.statement import SQL
 
         if isinstance(self._select_query, SQL):
             select_expr = self._select_query.expression
-            select_params = getattr(self._select_query, "parameters", None)
+            select_parameters = getattr(self._select_query, "parameters", None)
         elif isinstance(self._select_query, Select):
             select_expr = getattr(self._select_query, "_expression", None)
-            select_params = getattr(self._select_query, "_parameters", None)
+            select_parameters = getattr(self._select_query, "_parameters", None)
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
-            select_params = None
+            select_parameters = None
         else:
             self._raise_sql_builder_error("Unsupported type for SELECT query in materialized view.")
         if select_expr is None or not isinstance(select_expr, exp.Select):
             self._raise_sql_builder_error("SELECT query must be a valid SELECT expression.")
 
         # Merge parameters from SELECT if present
-        if select_params:
-            for p_name, p_value in select_params.items():
+        if select_parameters:
+            for p_name, p_value in select_parameters.items():
                 # Always preserve the original parameter name
                 # The SELECT query already has unique parameter names
                 self._parameters[p_name] = p_value
@@ -939,9 +930,7 @@ class CreateMaterializedView(DDLBuilder):
 
         props: list[exp.Property] = []
         if self._refresh_mode:
-            props.append(
-                exp.Property(this=exp.to_identifier("REFRESH_MODE"), value=exp.Literal.string(self._refresh_mode))
-            )
+            props.append(exp.Property(this=exp.to_identifier("REFRESH_MODE"), value=exp.convert(self._refresh_mode)))
         if self._tablespace:
             props.append(exp.Property(this=exp.to_identifier("TABLESPACE"), value=exp.to_identifier(self._tablespace)))
         if self._using_index:
@@ -949,12 +938,10 @@ class CreateMaterializedView(DDLBuilder):
                 exp.Property(this=exp.to_identifier("USING_INDEX"), value=exp.to_identifier(self._using_index))
             )
         for k, v in self._storage_parameters.items():
-            props.append(exp.Property(this=exp.to_identifier(k), value=exp.Literal.string(str(v))))
+            props.append(exp.Property(this=exp.to_identifier(k), value=exp.convert(str(v))))
         if self._with_data is not None:
             props.append(exp.Property(this=exp.to_identifier("WITH_DATA" if self._with_data else "NO_DATA")))
-        props.extend(
-            exp.Property(this=exp.to_identifier("HINT"), value=exp.Literal.string(hint)) for hint in self._hints
-        )
+        props.extend(exp.Property(this=exp.to_identifier("HINT"), value=exp.convert(hint)) for hint in self._hints)
         properties_node = exp.Properties(expressions=props) if props else None
 
         return exp.Create(
@@ -1007,27 +994,27 @@ class CreateView(DDLBuilder):
             self._raise_sql_builder_error("SELECT query must be set for CREATE VIEW.")
 
         select_expr = None
-        select_params = None
-        from sqlspec.statement.builder._select import Select
-        from sqlspec.statement.sql import SQL
+        select_parameters = None
+        from sqlspec.builder._select import Select
+        from sqlspec.core.statement import SQL
 
         if isinstance(self._select_query, SQL):
             select_expr = self._select_query.expression
-            select_params = getattr(self._select_query, "parameters", None)
+            select_parameters = getattr(self._select_query, "parameters", None)
         elif isinstance(self._select_query, Select):
             select_expr = getattr(self._select_query, "_expression", None)
-            select_params = getattr(self._select_query, "_parameters", None)
+            select_parameters = getattr(self._select_query, "_parameters", None)
         elif isinstance(self._select_query, str):
             select_expr = exp.maybe_parse(self._select_query)
-            select_params = None
+            select_parameters = None
         else:
             self._raise_sql_builder_error("Unsupported type for SELECT query in view.")
         if select_expr is None or not isinstance(select_expr, exp.Select):
             self._raise_sql_builder_error("SELECT query must be a valid SELECT expression.")
 
         # Merge parameters from SELECT if present
-        if select_params:
-            for p_name, p_value in select_params.items():
+        if select_parameters:
+            for p_name, p_value in select_parameters.items():
                 # Always preserve the original parameter name
                 # The SELECT query already has unique parameter names
                 self._parameters[p_name] = p_value
@@ -1037,7 +1024,7 @@ class CreateView(DDLBuilder):
             schema_expr = exp.Schema(expressions=[exp.column(c) for c in self._columns])
 
         props: list[exp.Property] = [
-            exp.Property(this=exp.to_identifier("HINT"), value=exp.Literal.string(h)) for h in self._hints
+            exp.Property(this=exp.to_identifier("HINT"), value=exp.convert(h)) for h in self._hints
         ]
         properties_node = exp.Properties(expressions=props) if props else None
 
@@ -1238,24 +1225,6 @@ class AlterTable(DDLBuilder):
         self._operations.append(operation)
         return self
 
-    def set_default(self, column: str, default: "Any") -> "Self":
-        """Set default value for a column."""
-        operation = AlterOperation(
-            operation_type="ALTER COLUMN SET DEFAULT",
-            column_name=column,
-            column_definition=ColumnDefinition(name=column, dtype="", default=default),
-        )
-
-        self._operations.append(operation)
-        return self
-
-    def drop_default(self, column: str) -> "Self":
-        """Remove default value from a column."""
-        operation = AlterOperation(operation_type="ALTER COLUMN DROP DEFAULT", column_name=column)
-
-        self._operations.append(operation)
-        return self
-
     def _create_base_expression(self) -> "exp.Expression":
         """Create the SQLGlot expression for ALTER TABLE."""
         if not self._operations:
@@ -1327,15 +1296,15 @@ class AlterTable(DDLBuilder):
                 if default_val.upper() in {"CURRENT_TIMESTAMP", "CURRENT_DATE", "CURRENT_TIME"} or "(" in default_val:
                     default_expr = exp.maybe_parse(default_val)
                 else:
-                    default_expr = exp.Literal.string(default_val)
+                    default_expr = exp.convert(default_val)
             elif isinstance(default_val, (int, float)):
-                default_expr = exp.Literal.number(default_val)
+                default_expr = exp.convert(default_val)
             elif default_val is True:
                 default_expr = exp.true()
             elif default_val is False:
                 default_expr = exp.false()
             else:
-                default_expr = exp.Literal.string(str(default_val))
+                default_expr = exp.convert(str(default_val))
             return exp.AlterColumn(this=exp.to_identifier(op.column_name), default=default_expr)
 
         if op_type == "ALTER COLUMN DROP DEFAULT":
@@ -1375,14 +1344,12 @@ class CommentOn(DDLBuilder):
 
     def _create_base_expression(self) -> exp.Expression:
         if self._target_type == "TABLE" and self._table and self._comment is not None:
-            return exp.Comment(
-                this=exp.to_table(self._table), kind="TABLE", expression=exp.Literal.string(self._comment)
-            )
+            return exp.Comment(this=exp.to_table(self._table), kind="TABLE", expression=exp.convert(self._comment))
         if self._target_type == "COLUMN" and self._table and self._column and self._comment is not None:
             return exp.Comment(
                 this=exp.Column(table=self._table, this=self._column),
                 kind="COLUMN",
-                expression=exp.Literal.string(self._comment),
+                expression=exp.convert(self._comment),
             )
         self._raise_sql_builder_error("Must specify target and comment for COMMENT ON statement.")
         raise AssertionError  # This line is unreachable but satisfies the linter

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

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Optional
 from sqlglot import exp
 
 if TYPE_CHECKING:
-    from sqlspec.statement.builder._ddl import ColumnDefinition, ConstraintDefinition
+    from sqlspec.builder._ddl import ColumnDefinition, ConstraintDefinition
 
 __all__ = ("build_column_expression", "build_constraint_expression")
 
@@ -31,15 +31,10 @@ def build_column_expression(col: "ColumnDefinition") -> "exp.Expression":
             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.Literal.string(col.default)
-        elif isinstance(col.default, (int, float)):
-            default_expr = exp.Literal.number(col.default)
-        elif col.default is True:
-            default_expr = exp.true()
-        elif col.default is False:
-            default_expr = exp.false()
+                default_expr = exp.convert(col.default)
         else:
-            default_expr = exp.Literal.string(str(col.default))
+            # Use exp.convert for all other types (int, float, bool, None, etc.)
+            default_expr = exp.convert(col.default)
 
         constraints.append(exp.ColumnConstraint(kind=default_expr))
 
@@ -48,7 +43,7 @@ def build_column_expression(col: "ColumnDefinition") -> "exp.Expression":
         constraints.append(exp.ColumnConstraint(kind=check_expr))
 
     if col.comment:
-        constraints.append(exp.ColumnConstraint(kind=exp.CommentColumnConstraint(this=exp.Literal.string(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))

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

@@ -9,38 +9,20 @@ from typing import Any, 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
+from sqlspec.builder._base import QueryBuilder, SafeQuery
+from sqlspec.builder.mixins import DeleteFromClauseMixin, ReturningClauseMixin, WhereClauseMixin
+from sqlspec.core.result import SQLResult
 
 __all__ = ("Delete",)
 
 
 @dataclass(unsafe_hash=True)
-class Delete(QueryBuilder[RowT], WhereClauseMixin, ReturningClauseMixin, DeleteFromClauseMixin):
+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.
-
-    Example:
-        ```python
-        # Basic DELETE
-        delete_query = Delete().from_("users").where("age < 18")
-
-        # Even more concise with constructor
-        delete_query = Delete("users").where("age < 18")
-
-        # DELETE with parameterized conditions
-        delete_query = (
-            Delete()
-            .from_("users")
-            .where_eq("status", "inactive")
-            .where_in("category", ["test", "demo"])
-        )
-        ```
     """
 
     _table: "Optional[str]" = field(default=None, init=False)
@@ -54,20 +36,19 @@ class Delete(QueryBuilder[RowT], WhereClauseMixin, ReturningClauseMixin, DeleteF
         """
         super().__init__(**kwargs)
 
-        # Initialize fields from dataclass
         self._table = None
 
         if table:
             self.from_(table)
 
     @property
-    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+    def _expected_result_type(self) -> "type[SQLResult]":
         """Get the expected result type for DELETE operations.
 
         Returns:
             The ExecuteResult type for DELETE statements.
         """
-        return SQLResult[RowT]
+        return SQLResult
 
     def _create_base_expression(self) -> "exp.Delete":
         """Create a new sqlglot Delete expression.

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

@@ -10,16 +10,10 @@ from typing import TYPE_CHECKING, Any, 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
-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
@@ -36,57 +30,11 @@ ERR_MSG_EXPRESSION_NOT_INITIALIZED = "Internal error: base expression not initia
 
 
 @dataclass(unsafe_hash=True)
-class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, InsertFromSelectMixin, InsertIntoClauseMixin):
+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.
-
-    Example:
-        ```python
-        # Basic INSERT with values
-        insert_query = (
-            Insert()
-            .into("users")
-            .columns("name", "email", "age")
-            .values("John Doe", "john@example.com", 30)
-        )
-
-        # Even more concise with constructor
-        insert_query = Insert("users").values(
-            {"name": "John", "age": 30}
-        )
-
-        # Multi-row INSERT
-        insert_query = (
-            Insert()
-            .into("users")
-            .columns("name", "email")
-            .values("John", "john@example.com")
-            .values("Jane", "jane@example.com")
-        )
-
-        # INSERT from dictionary
-        insert_query = (
-            Insert()
-            .into("users")
-            .values_from_dict(
-                {"name": "John", "email": "john@example.com"}
-            )
-        )
-
-        # INSERT from SELECT
-        insert_query = (
-            Insert()
-            .into("users_backup")
-            .from_select(
-                Select()
-                .select("name", "email")
-                .from_("users")
-                .where("active = true")
-            )
-        )
-        ```
     """
 
     _table: "Optional[str]" = field(default=None, init=False)
@@ -102,7 +50,6 @@ class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, Insert
         """
         super().__init__(**kwargs)
 
-        # Initialize fields from dataclass
         self._table = None
         self._columns = []
         self._values_added_count = 0
@@ -121,13 +68,13 @@ class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, Insert
         return exp.Insert()
 
     @property
-    def _expected_result_type(self) -> "type[SQLResult[RowT]]":
+    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[RowT]
+        return SQLResult
 
     def _get_insert_expression(self) -> exp.Insert:
         """Safely gets and casts the internal expression to exp.Insert.
@@ -172,7 +119,18 @@ class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, Insert
             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")
@@ -183,8 +141,6 @@ class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, Insert
         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.
             new_values_node = exp.Values(expressions=[exp.Tuple(expressions=list(value_placeholders))])
             insert_expr.set("expression", new_values_node)
 
@@ -212,7 +168,6 @@ class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, Insert
         if not self._columns:
             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)
 
@@ -267,12 +222,10 @@ class Insert(QueryBuilder[RowT], ReturningClauseMixin, InsertValuesMixin, Insert
             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
 

sqlspec/builder/_merge.py

@@ -0,0 +1,56 @@
+"""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.builder._base import QueryBuilder
+from sqlspec.builder.mixins import (
+    MergeIntoClauseMixin,
+    MergeMatchedClauseMixin,
+    MergeNotMatchedBySourceClauseMixin,
+    MergeNotMatchedClauseMixin,
+    MergeOnClauseMixin,
+    MergeUsingClauseMixin,
+)
+from sqlspec.core.result import SQLResult
+
+__all__ = ("Merge",)
+
+
+@dataclass(unsafe_hash=True)
+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.
+    """
+
+    @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=[]))