feat: support PostgreSQL-dialect databases (#443)

The driver now supports both GoogleSQL and PostgreSQL databases.

The driver automatically detects the dialect of the database that it is connected to,
and adjusts the query parameter styles and comments that it accepts accordingly.

Author: olavloite

README.md

@@ -5,6 +5,8 @@
 [Google Cloud Spanner](https://cloud.google.com/spanner) driver for
 Go's [database/sql](https://golang.org/pkg/database/sql/) package.
 
+This driver can be used with both Spanner GoogleSQL and Spanner PostgreSQL databases.
+
 ```go
 import _ "github.com/googleapis/go-sql-spanner"
 
@@ -13,8 +15,8 @@ if err != nil {
     log.Fatal(err)
 }
 
-// Print tweets with more than 500 likes.
-rows, err := db.QueryContext(ctx, "SELECT id, text FROM tweets WHERE likes > @likes", sql.Named("likes", 500))
+// Print singers with more than 500 likes.
+rows, err := db.QueryContext(ctx, "SELECT id, name FROM singers WHERE likes > ?", 500)
 if err != nil {
     log.Fatal(err)
 }
@@ -55,6 +57,17 @@ db.ExecContext(ctx, "INSERT INTO tweets (id, text, rts) VALUES (@id, @text, @rts
 	sql.Named("id", id), sql.Named("text", text), sql.Named("rts", 10000))
 ```
 
+### Using PostgreSQL-style positional arguments
+
+When connected to a PostgreSQL-dialect Spanner database, you can also use PostgreSQL-style
+query parameters `$1, $2, ..., $n`. These query parameters are handled as positional parameters.
+
+```go
+db.QueryContext(ctx, "SELECT id, text FROM tweets WHERE likes > $1", 500)
+
+db.ExecContext(ctx, "INSERT INTO tweets (id, text, rts) VALUES ($1, $2, $3)", id, text, 10000)
+```
+
 ### Using named parameters with positional arguments (not recommended)
 Named parameters can also be used in combination with positional arguments,
 but this is __not recommended__, as the behavior can be hard to predict if
@@ -215,10 +228,19 @@ $ export SPANNER_EMULATOR_HOST=localhost:9010
 
 ## Spanner PostgreSQL Interface
 
-This driver only works with the Spanner GoogleSQL dialect. For the
-Spanner PostgreSQL dialect, any PostgreSQL driver that implements the
-[database/sql](https://golang.org/pkg/database/sql/) interface can be used
-in combination with
+This driver works with both Spanner GoogleSQL and PostgreSQL dialects.
+The driver automatically detects the dialect of the database that it is connected to.
+
+Note that the types of query parameters that are supported depends on the dialect of the
+database that the driver is connected to:
+1. Positional parameters (`?`): Supported for both dialects.
+2. Named parameters (`@id`, `@name`, ...): Supported for both dialects.
+3. PostgreSQL-style positional parameters (`$1`, `$2`, ...): Only supported for PostgreSQL databases.
+
+### Alternatives
+
+You can also use Spanner PostgreSQL dialect databases with any off-the-shelf PostgreSQL driver that
+implements the [database/sql](https://golang.org/pkg/database/sql/) interface in combination with
 [PGAdapter](https://cloud.google.com/spanner/docs/pgadapter).
 
 For example, the [pgx](https://github.com/jackc/pgx) driver can be used in combination with

examples/emulator_runner.go

@@ -44,6 +44,10 @@ var containerId string
 // 3. Execute the sample function against the emulator.
 // 4. Stop the Docker container with the emulator.
 func RunSampleOnEmulator(sample func(string, string, string) error, ddlStatements ...string) {
+	RunSampleOnEmulatorWithDialect(sample, databasepb.DatabaseDialect_GOOGLE_STANDARD_SQL, ddlStatements...)
+}
+
+func RunSampleOnEmulatorWithDialect(sample func(string, string, string) error, dialect databasepb.DatabaseDialect, ddlStatements ...string) {
 	var err error
 	if err = startEmulator(); err != nil {
 		log.Fatalf("failed to start emulator: %v", err)
@@ -53,7 +57,7 @@ func RunSampleOnEmulator(sample func(string, string, string) error, ddlStatement
 		stopEmulator()
 		log.Fatalf("failed to create instance on emulator: %v", err)
 	}
-	if err = createSampleDB(projectId, instanceId, databaseId, ddlStatements...); err != nil {
+	if err = createSampleDB(projectId, instanceId, databaseId, dialect, ddlStatements...); err != nil {
 		stopEmulator()
 		log.Fatalf("failed to create database on emulator: %v", err)
 	}
@@ -146,17 +150,24 @@ func createInstance(projectId, instanceId string) error {
 	return nil
 }
 
-func createSampleDB(projectId, instanceId, databaseId string, statements ...string) error {
+func createSampleDB(projectId, instanceId, databaseId string, dialect databasepb.DatabaseDialect, statements ...string) error {
 	ctx := context.Background()
 	databaseAdminClient, err := database.NewDatabaseAdminClient(ctx)
 	if err != nil {
 		return err
 	}
 	defer databaseAdminClient.Close()
+	var createStatement string
+	if dialect == databasepb.DatabaseDialect_POSTGRESQL {
+		createStatement = fmt.Sprintf(`CREATE DATABASE "%s"`, databaseId)
+	} else {
+		createStatement = fmt.Sprintf("CREATE DATABASE `%s`", databaseId)
+	}
 	opDB, err := databaseAdminClient.CreateDatabase(ctx, &databasepb.CreateDatabaseRequest{
 		Parent:          fmt.Sprintf("projects/%s/instances/%s", projectId, instanceId),
-		CreateStatement: fmt.Sprintf("CREATE DATABASE `%s`", databaseId),
+		CreateStatement: createStatement,
 		ExtraStatements: statements,
+		DatabaseDialect: dialect,
 	})
 	if err != nil {
 		return err

examples/postgresql/main.go

@@ -0,0 +1,59 @@
+// Copyright 2025 Google LLC All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"cloud.google.com/go/spanner/admin/database/apiv1/databasepb"
+	_ "github.com/googleapis/go-sql-spanner"
+	"github.com/googleapis/go-sql-spanner/examples"
+)
+
+// Sample application that uses a PostgreSQL-dialect Spanner database.
+//
+// Execute the sample with the command `go run main.go` from this directory.
+func helloWorldFromPostgreSQL(projectId, instanceId, databaseId string) error {
+	ctx := context.Background()
+	db, err := sql.Open("spanner", fmt.Sprintf("projects/%s/instances/%s/databases/%s", projectId, instanceId, databaseId))
+	if err != nil {
+		return fmt.Errorf("failed to open database connection: %v", err)
+	}
+	defer db.Close()
+
+	rows, err := db.QueryContext(ctx, "SELECT $1::varchar as message", "Hello World from Spanner PostgreSQL")
+	if err != nil {
+		return fmt.Errorf("failed to execute query: %v", err)
+	}
+	defer rows.Close()
+
+	var msg string
+	for rows.Next() {
+		if err := rows.Scan(&msg); err != nil {
+			return fmt.Errorf("failed to scan row values: %v", err)
+		}
+		fmt.Printf("%s\n", msg)
+	}
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("failed to execute query: %v", err)
+	}
+	return nil
+}
+
+func main() {
+	examples.RunSampleOnEmulatorWithDialect(helloWorldFromPostgreSQL, databasepb.DatabaseDialect_POSTGRESQL)
+}