dialect/sql: added support for replace clause

Author: LostImagin4tion

dialect/sql/builder.go

@@ -146,7 +146,10 @@ type InsertBuilder struct {
 	returning []string
 	values    [][]any
 	conflict  *conflict
-	isUpsert  bool // YDB-specific: use UPSERT instead of INSERT
+
+	// YDB-specific:
+	isUpsert  bool // use UPSERT instead of INSERT
+	isReplace bool // use REPLACE instead of INSERT
 }
 
 // Insert creates a builder for the `INSERT INTO` statement.
@@ -174,6 +177,21 @@ func Upsert(table string) *InsertBuilder {
 	return &InsertBuilder{table: table, isUpsert: true}
 }
 
+// Replace creates a builder for the `REPLACE INTO` statement.
+// REPLACE overwrites entire rows based on primary key comparison.
+// For existing rows, the entire row is replaced (unspecified columns get default values).
+// For missing rows, new rows are inserted.
+//
+//	Replace("users").
+//		Columns("id", "name", "age").
+//		Values(1, "a8m", 10).
+//		Values(2, "foo", 20)
+//
+// Note: REPLACE is only supported in YDB dialect.
+func Replace(table string) *InsertBuilder {
+	return &InsertBuilder{table: table, isReplace: true}
+}
+
 // Schema sets the database name for the insert table.
 func (i *InsertBuilder) Schema(name string) *InsertBuilder {
 	i.schema = name
@@ -454,17 +472,23 @@ func (i *InsertBuilder) Query() (string, []any) {
 	return query, args
 }
 
-// QueryErr returns query representation of an `INSERT INTO` or `UPSERT INTO`
-// statement and any error occurred in building the statement.
+// QueryErr returns query representation of an `INSERT INTO`, `UPSERT INTO`,
+// or `REPLACE INTO` statement and any error occurred in building the statement.
 func (i *InsertBuilder) QueryErr() (string, []any, error) {
 	b := i.Builder.clone()
 
 	if i.isUpsert {
 		if !b.ydb() {
-			b.AddError(fmt.Errorf("UPSERT: unsupported dialect: %q", b.dialect))
+			b.AddError(fmt.Errorf("UPSERT INTO: unsupported dialect: %q", b.dialect))
 			return "", nil, b.Err()
 		}
 		b.WriteString("UPSERT INTO ")
+	} else if i.isReplace {
+		if !b.ydb() {
+			b.AddError(fmt.Errorf("REPLACE INTO: unsupported dialect: %q", b.dialect))
+			return "", nil, b.Err()
+		}
+		b.WriteString("REPLACE INTO ")
 	} else {
 		b.WriteString("INSERT INTO ")
 	}
@@ -3657,6 +3681,19 @@ func (d *DialectBuilder) Upsert(table string) *InsertBuilder {
 	return b
 }
 
+// Replace creates an InsertBuilder for the REPLACE statement with the configured dialect.
+// REPLACE is only supported in YDB dialect.
+//
+//	Dialect(dialect.YDB).
+//		Replace("users").
+//		Columns("id", "name", "age").
+//		Values(1, "a8m", 10)
+func (d *DialectBuilder) Replace(table string) *InsertBuilder {
+	b := Replace(table)
+	b.SetDialect(d.dialect)
+	return b
+}
+
 // Update creates a UpdateBuilder for the configured dialect.
 //
 //	Dialect(dialect.Postgres).

dialect/sql/builder_test.go

@@ -1734,6 +1734,47 @@ AND "users"."id1" < "users"."id2") AND "users"."id1" <= "users"."id2"`, "\n", ""
 				driver.NamedValue{Name: "p2", Value: "john@example.com"},
 			},
 		},
+		{
+			input: Dialect(dialect.YDB).
+				Replace("users").
+				Columns("id", "name", "age").
+				Values(1, "a8m", 10),
+			wantQuery: "REPLACE INTO `users` (`id`, `name`, `age`) VALUES ($p0, $p1, $p2)",
+			wantArgs: []any{
+				driver.NamedValue{Name: "p0", Value: 1},
+				driver.NamedValue{Name: "p1", Value: "a8m"},
+				driver.NamedValue{Name: "p2", Value: 10},
+			},
+		},
+		{
+			input: Dialect(dialect.YDB).
+				Replace("users").
+				Columns("id", "name", "age").
+				Values(1, "a8m", 10).
+				Values(2, "foo", 20),
+			wantQuery: "REPLACE INTO `users` (`id`, `name`, `age`) VALUES ($p0, $p1, $p2), ($p3, $p4, $p5)",
+			wantArgs: []any{
+				driver.NamedValue{Name: "p0", Value: 1},
+				driver.NamedValue{Name: "p1", Value: "a8m"},
+				driver.NamedValue{Name: "p2", Value: 10},
+				driver.NamedValue{Name: "p3", Value: 2},
+				driver.NamedValue{Name: "p4", Value: "foo"},
+				driver.NamedValue{Name: "p5", Value: 20},
+			},
+		},
+		{
+			input: Dialect(dialect.YDB).
+				Replace("orders").
+				Columns("order_id", "status", "amount").
+				Values(1001, "shipped", 500).
+				Returning("*"),
+			wantQuery: "REPLACE INTO `orders` (`order_id`, `status`, `amount`) VALUES ($p0, $p1, $p2) RETURNING *",
+			wantArgs: []any{
+				driver.NamedValue{Name: "p0", Value: 1001},
+				driver.NamedValue{Name: "p1", Value: "shipped"},
+				driver.NamedValue{Name: "p2", Value: 500},
+			},
+		},
 		{
 			input: Dialect(dialect.YDB).
 				Update("users").