chore: allow query parameters starting with underscore (#516)

The database/sql package does not allow query parameter names to start with an underscore.
Spanner however allows this. Query parameters that start with an underscore can be wrapped
in a SpannerNamedArg to work around this limitation.

This feature is primarily intended for use with other programming languages than Go, as
frameworks written in Go will know about the limitation in database/sql that query parameters
may not start with an underscore.

Author: olavloite

driver_with_mockserver_test.go

@@ -2099,6 +2099,39 @@ func TestQueryWithDuplicateNamedParameter(t *testing.T) {
 	}
 }
 
+func TestQueryWithDuplicateNamedParameterStartingWithUnderscore(t *testing.T) {
+	t.Parallel()
+
+	db, server, teardown := setupTestDBConnection(t)
+	defer teardown()
+
+	// database/sql does not allow named arguments to start with an underscore.
+	// The Spanner database/sql driver allows a workaround for this by specifying those named arguments with a
+	// SpannerNamedArg.
+	s := "insert into users (id, name) values (@__name, @__name)"
+	_ = server.TestSpanner.PutStatementResult(s, &testutil.StatementResult{
+		Type:        testutil.StatementResultUpdateCount,
+		UpdateCount: 1,
+	})
+	_, err := db.Exec(s, sql.Named("p__name", SpannerNamedArg{NameInQuery: "__name", Value: "foo"}), sql.Named("p__name", SpannerNamedArg{NameInQuery: "__name", Value: "bar"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Verify that 'bar' is used for both instances of the parameter @__name.
+	requests := drainRequestsFromServer(server.TestSpanner)
+	sqlRequests := requestsOfType(requests, reflect.TypeOf(&sppb.ExecuteSqlRequest{}))
+	if len(sqlRequests) != 1 {
+		t.Fatalf("sql requests count mismatch\nGot: %v\nWant: %v", len(sqlRequests), 1)
+	}
+	req := sqlRequests[0].(*sppb.ExecuteSqlRequest)
+	if g, w := len(req.Params.Fields), 1; g != w {
+		t.Fatalf("params count mismatch\n Got: %v\nWant: %v", g, w)
+	}
+	if g, w := req.Params.Fields["__name"].GetStringValue(), "bar"; g != w {
+		t.Fatalf("param value mismatch\n Got: %v\nWant: %v", g, w)
+	}
+}
+
 func TestQueryWithReusedNamedParameter(t *testing.T) {
 	t.Parallel()
 
@@ -2129,6 +2162,36 @@ func TestQueryWithReusedNamedParameter(t *testing.T) {
 	}
 }
 
+func TestQueryWithReusedNamedParameterStartingWithUnderscore(t *testing.T) {
+	t.Parallel()
+
+	db, server, teardown := setupTestDBConnection(t)
+	defer teardown()
+
+	s := "insert into users (id, name) values (@__name, @__name)"
+	_ = server.TestSpanner.PutStatementResult(s, &testutil.StatementResult{
+		Type:        testutil.StatementResultUpdateCount,
+		UpdateCount: 1,
+	})
+	_, err := db.Exec(s, sql.Named("p__name", SpannerNamedArg{NameInQuery: "__name", Value: "foo"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Verify that 'foo' is used for both instances of the parameter @__name.
+	requests := drainRequestsFromServer(server.TestSpanner)
+	sqlRequests := requestsOfType(requests, reflect.TypeOf(&sppb.ExecuteSqlRequest{}))
+	if len(sqlRequests) != 1 {
+		t.Fatalf("sql requests count mismatch\nGot: %v\nWant: %v", len(sqlRequests), 1)
+	}
+	req := sqlRequests[0].(*sppb.ExecuteSqlRequest)
+	if g, w := len(req.Params.Fields), 1; g != w {
+		t.Fatalf("params count mismatch\n Got: %v\nWant: %v", g, w)
+	}
+	if g, w := req.Params.Fields["__name"].GetStringValue(), "foo"; g != w {
+		t.Fatalf("param value mismatch\n Got: %v\nWant: %v", g, w)
+	}
+}
+
 func TestQueryWithReusedPositionalParameter(t *testing.T) {
 	t.Parallel()
 

stmt.go

@@ -24,6 +24,15 @@ import (
 	"google.golang.org/grpc/status"
 )
 
+// SpannerNamedArg can be used for query parameters with a name that (might) start
+// with an underscore. The generic database/sql package does not allow query parameters
+// to start with an underscore, but Spanner allows this, and this struct can be used to
+// work around the limitation in database/sql.
+type SpannerNamedArg struct {
+	NameInQuery string
+	Value       any
+}
+
 var _ driver.Stmt = &stmt{}
 var _ driver.StmtExecContext = &stmt{}
 var _ driver.StmtQueryContext = &stmt{}
@@ -80,12 +89,17 @@ func prepareSpannerStmt(parser *parser.StatementParser, q string, args []driver.
 	}
 	ss := spanner.NewStatement(q)
 	for i, v := range args {
+		value := v.Value
 		name := args[i].Name
+		if sa, ok := args[i].Value.(SpannerNamedArg); ok {
+			name = sa.NameInQuery
+			value = sa.Value
+		}
 		if name == "" && len(names) > i {
 			name = names[i]
 		}
 		if name != "" {
-			ss.Params[name] = convertParam(v.Value)
+			ss.Params[name] = convertParam(value)
 		}
 	}
 	// Verify that all parameters have a value.