perf: use statement cache to avoid repeated SQL string parsing (#445)

A statement cache has been added to the driver to prevent SQL strings from being
parsed repeatedly for each execution. Instead, a SQL string is parsed once and the
results of this parsing is added to an internal cache. Only the parse result is
added to the cache, and not the results of the actual execution of the statement.

Author: olavloite

driver.go

@@ -515,6 +515,11 @@ func createConnector(d *Driver, connectorConfig ConnectorConfig) (*connector, er
 			connectorConfig.StatementCacheSize = val
 		}
 	}
+	if strval, ok := connectorConfig.Params[strings.ToLower("DisableStatementCache")]; ok {
+		if val, err := strconv.ParseBool(strval); err == nil {
+			connectorConfig.DisableStatementCache = val
+		}
+	}
 
 	// Check if it is Spanner gorm that is creating the connection.
 	// If so, we should set a different user-agent header than the

driver_test.go

@@ -177,6 +177,21 @@ func TestExtractDnsParts(t *testing.T) {
 				UserAgent:         userAgent,
 			},
 		},
+		{
+			input: "projects/p/instances/i/databases/d?StatementCacheSize=100;",
+			wantConnectorConfig: ConnectorConfig{
+				Project:  "p",
+				Instance: "i",
+				Database: "d",
+				Params: map[string]string{
+					"statementcachesize": "100",
+				},
+			},
+			wantSpannerConfig: spanner.ClientConfig{
+				SessionPoolConfig: spanner.DefaultSessionPoolConfig,
+				UserAgent:         userAgent,
+			},
+		},
 		{
 			input: "spanner.googleapis.com/projects/p/instances/i/databases/d?minSessions=200;maxSessions=1000;numChannels=10;disableRouteToLeader=true;enableEndToEndTracing=true;disableNativeMetrics=true;rpcPriority=Medium;optimizerVersion=1;optimizerStatisticsPackage=latest;databaseRole=child",
 			wantConnectorConfig: ConnectorConfig{

driver_with_mockserver_test.go

@@ -38,6 +38,7 @@ import (
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/google/uuid"
 	"github.com/googleapis/go-sql-spanner/testutil"
+	lru "github.com/hashicorp/golang-lru"
 	"google.golang.org/api/option"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/metadata"
@@ -72,6 +73,117 @@ func TestPingContext_Fails(t *testing.T) {
 	}
 }
 
+func TestStatementCacheSize(t *testing.T) {
+	t.Parallel()
+
+	db, server, teardown := setupTestDBConnectionWithParams(t, "StatementCacheSize=2")
+	defer teardown()
+
+	c, err := db.Conn(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error for connection: %v", err)
+	}
+	var cache *lru.Cache
+	if err := c.Raw(func(driverConn any) error {
+		sc, ok := driverConn.(*conn)
+		if !ok {
+			return fmt.Errorf("driverConn is not a Spanner conn")
+		}
+		cache = sc.parser.statementsCache
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error for raw: %v", err)
+	}
+
+	// The cache should initially be empty.
+	if g, w := cache.Len(), 0; g != w {
+		t.Fatalf("cache size mismatch\n Got: %v\nWant: %v", g, w)
+	}
+
+	for n := 0; n < 3; n++ {
+		rows, err := db.QueryContext(context.Background(), testutil.SelectFooFromBar)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for rows.Next() {
+		}
+		if err := rows.Close(); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	// Executing the same query multiple times should add the statement once to the cache.
+	if g, w := cache.Len(), 1; g != w {
+		t.Fatalf("cache size mismatch\n Got: %v\nWant: %v", g, w)
+	}
+
+	// Executing another statement should add yet another statement to the cache.
+	if _, err := db.ExecContext(context.Background(), testutil.UpdateBarSetFoo); err != nil {
+		t.Fatal(err)
+	}
+	if g, w := cache.Len(), 2; g != w {
+		t.Fatalf("cache size mismatch\n Got: %v\nWant: %v", g, w)
+	}
+
+	// Executing yet another statement should evict the oldest result from the cache and add this.
+	query := "insert into test (id) values (1)"
+	server.TestSpanner.PutStatementResult(query, &testutil.StatementResult{
+		Type:        testutil.StatementResultUpdateCount,
+		UpdateCount: 1,
+	})
+	if _, err := db.ExecContext(context.Background(), query); err != nil {
+		t.Fatal(err)
+	}
+	// The cache size should still be 2.
+	if g, w := cache.Len(), 2; g != w {
+		t.Fatalf("cache size mismatch\n Got: %v\nWant: %v", g, w)
+	}
+}
+
+func TestDisableStatementCache(t *testing.T) {
+	t.Parallel()
+
+	db, _, teardown := setupTestDBConnectionWithParams(t, "DisableStatementCache=true")
+	defer teardown()
+
+	c, err := db.Conn(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error for connection: %v", err)
+	}
+	var cache *lru.Cache
+	if err := c.Raw(func(driverConn any) error {
+		sc, ok := driverConn.(*conn)
+		if !ok {
+			return fmt.Errorf("driverConn is not a Spanner conn")
+		}
+		cache = sc.parser.statementsCache
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error for raw: %v", err)
+	}
+
+	// There should be no cache.
+	if cache != nil {
+		t.Fatalf("statement cache should be disabled")
+	}
+
+	// Executing queries and other statements should work without a cache.
+	for n := 0; n < 3; n++ {
+		rows, err := db.QueryContext(context.Background(), testutil.SelectFooFromBar)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for rows.Next() {
+		}
+		if err := rows.Close(); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if _, err := db.ExecContext(context.Background(), testutil.UpdateBarSetFoo); err != nil {
+		t.Fatal(err)
+	}
+}
+
 func TestSimpleQuery(t *testing.T) {
 	t.Parallel()
 

examples/statement-cache/main.go

@@ -0,0 +1,86 @@
+// Copyright 2025 Google LLC
+//
+// 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
+//
+//     https://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"
+
+	_ "github.com/googleapis/go-sql-spanner"
+	"github.com/googleapis/go-sql-spanner/examples"
+)
+
+var createTableStatement = "CREATE TABLE Singers (SingerId INT64, Name STRING(MAX)) PRIMARY KEY (SingerId)"
+
+// Sample showing how to customize the size of the internal statement cache
+// of the Spanner database/sql driver. The driver needs to determine the
+// number of query parameters in each statement that is executed. This involves
+// partially parsing the SQL statement. The driver uses an internal cache for
+// this, so it does not need to reparse SQL statements that are executed
+// multiple times.
+//
+// Execute the sample with the command `go run main.go` from this directory.
+func statementCache(projectId, instanceId, databaseId string) error {
+	ctx := context.Background()
+
+	// The default statement cache size is 1,000 statements.
+	// The cache size can be changed by setting the StatementCacheSize=N
+	// parameter in the connection string.
+
+	// Add DisableStatementCache=true to the connection string if you want to
+	// disable the use of the statement cache.
+
+	// Create a database connection with statement cache size 50.
+	dsn := fmt.Sprintf("projects/%s/instances/%s/databases/%s?StatementCacheSize=50", projectId, instanceId, databaseId)
+	db, err := sql.Open("spanner", dsn)
+	if err != nil {
+		return err
+	}
+	defer db.Close()
+	fmt.Println("Created a database connection with a statement cache size of 50")
+
+	// The driver needs to determine the number and names of any query parameters
+	// in a SQL string that is executed in order to assign the query parameters correctly.
+	// To do this, the driver inspects and partially parses the SQL string. The result
+	// of this parsing is stored in the internal statement cache and is reused for
+	// subsequent executions of the same SQL string.
+	_, err = db.ExecContext(ctx,
+		"INSERT INTO Singers (SingerId, Name) VALUES (@id, @name)",
+		sql.Named("id", int64(1)),
+		sql.Named("name", "Bruce Allison"))
+	if err != nil {
+		return err
+	}
+
+	// This execution uses the exact same SQL string as the previous statement,
+	// and it will not be parsed again by the driver. Instead, the parse result
+	// of the previous execution will be used.
+	_, err = db.ExecContext(ctx,
+		"INSERT INTO Singers (SingerId, Name) VALUES (@id, @name)",
+		sql.Named("id", int64(2)),
+		sql.Named("name", "Alice Marquez"))
+	if err != nil {
+		return err
+	}
+
+	fmt.Println("Executed two SQL statements")
+
+	return nil
+}
+
+func main() {
+	examples.RunSampleOnEmulator(statementCache, createTableStatement)
+}