feat(spanner): add native read-only transactional support

Author: anubhav756

docs/SPANNER_README.md

@@ -67,6 +67,7 @@ export SPANNER_PROJECT="<your-gcp-project-id>"
 export SPANNER_INSTANCE="<your-spanner-instance-id>"
 export SPANNER_DATABASE="<your-spanner-database-id>"
 export SPANNER_DIALECT="googlesql" # Optional: "googlesql" or "postgresql". Defaults to "googlesql".
+export SPANNER_READONLY="true" # Optional: Restricts tools and executes queries on read-only endpoints.
 ```
 
 Add the following configuration to your MCP client (e.g., `settings.json` for Gemini CLI, `mcp_config.json` for Antigravity):

internal/prebuiltconfigs/tools/spanner.yaml

@@ -19,19 +19,24 @@ project: ${SPANNER_PROJECT}
 instance: ${SPANNER_INSTANCE}
 database: ${SPANNER_DATABASE}
 dialect: ${SPANNER_DIALECT:googlesql}
+readonly: ${SPANNER_READONLY:false}
 ---
 kind: tool
 name: execute_sql
 type: spanner-execute-sql
 source: spanner-source
 description: Use this tool to execute DML SQL. Please use the ${SPANNER_DIALECT:googlesql} interface for Spanner.
+annotations:
+  readOnlyHint: false
 ---
 kind: tool
 name: execute_sql_dql
 type: spanner-execute-sql
 source: spanner-source
 description: Use this tool to execute DQL SQL. Please use the ${SPANNER_DIALECT:googlesql} interface for Spanner.
 readOnly: true
+annotations:
+  readOnlyHint: true
 ---
 kind: tool
 name: list_tables

internal/sources/spanner/spanner.go

@@ -57,6 +57,7 @@ type Config struct {
 	Dialect        sources.Dialect `yaml:"dialect" validate:"required"`
 	Database       string          `yaml:"database" validate:"required"`
 	UseClientOAuth bool            `yaml:"useClientOAuth"`
+	ReadOnly       bool            `yaml:"readonly"`
 }
 
 func (r Config) SourceConfigType() string {
@@ -102,6 +103,10 @@ func (s *Source) ToConfig() sources.SourceConfig {
 	return s.Config
 }
 
+func (s *Source) IsReadOnlyMode() bool {
+	return s.ReadOnly
+}
+
 func (s *Source) SpannerClient() *spanner.Client {
 	return s.Client
 }
@@ -174,7 +179,7 @@ func (s *Source) RunSQL(ctx context.Context, readOnly bool, statement string, pa
 		stmt.Params = params
 	}
 
-	if readOnly {
+	if readOnly || s.ReadOnly {
 		iter := s.SpannerClient().Single().Query(ctx, stmt)
 		results, opErr = processRows(iter)
 	} else {

internal/tools/spanner/spannerexecutesql/spannerexecutesql.go

@@ -68,6 +68,12 @@ func (cfg Config) Initialize(context.Context) (tools.Tool, error) {
 		return nil, fmt.Errorf("description is required for tool %q", cfg.Name)
 	}
 
+	if cfg.Annotations != nil && cfg.Annotations.ReadOnlyHint != nil {
+		if cfg.ReadOnly != *cfg.Annotations.ReadOnlyHint {
+			return nil, fmt.Errorf("configuration conflict in tool %q: legacy readOnly=%v does not match readOnlyHint=%v", cfg.Name, cfg.ReadOnly, *cfg.Annotations.ReadOnlyHint)
+		}
+	}
+
 	sqlParameter := parameters.NewStringParameter("sql", "The sql to execute.")
 	params := parameters.Parameters{sqlParameter}
 

internal/tools/spanner/spannerexecutesql/spannerexecutesql_test.go

@@ -15,6 +15,7 @@
 package spannerexecutesql_test
 
 import (
+	"context"
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
@@ -94,3 +95,91 @@ func TestParseFromYamlExecuteSql(t *testing.T) {
 	}
 
 }
+
+func TestInitialize_ReadOnlyValidation(t *testing.T) {
+	ctx := context.Background()
+
+	ptr := func(b bool) *bool { return &b }
+
+	tcs := []struct {
+		desc        string
+		cfg         spannerexecutesql.Config
+		wantErr     bool
+		errContains string
+	}{
+		{
+			desc: "no conflict - both true",
+			cfg: spannerexecutesql.Config{
+				ConfigBase:  tools.ConfigBase{Name: "test-tool", Description: "desc"},
+				ReadOnly:    true,
+				Annotations: &tools.ToolAnnotations{ReadOnlyHint: ptr(true)},
+			},
+			wantErr: false,
+		},
+		{
+			desc: "no conflict - both false",
+			cfg: spannerexecutesql.Config{
+				ConfigBase:  tools.ConfigBase{Name: "test-tool", Description: "desc"},
+				ReadOnly:    false,
+				Annotations: &tools.ToolAnnotations{ReadOnlyHint: ptr(false)},
+			},
+			wantErr: false,
+		},
+		{
+			desc: "no conflict - readOnlyHint nil",
+			cfg: spannerexecutesql.Config{
+				ConfigBase:  tools.ConfigBase{Name: "test-tool", Description: "desc"},
+				ReadOnly:    true,
+				Annotations: &tools.ToolAnnotations{ReadOnlyHint: nil},
+			},
+			wantErr: false,
+		},
+		{
+			desc: "conflict - readOnly false, readOnlyHint true",
+			cfg: spannerexecutesql.Config{
+				ConfigBase:  tools.ConfigBase{Name: "test-tool", Description: "desc"},
+				ReadOnly:    false,
+				Annotations: &tools.ToolAnnotations{ReadOnlyHint: ptr(true)},
+			},
+			wantErr:     true,
+			errContains: "configuration conflict in tool \"test-tool\"",
+		},
+		{
+			desc: "conflict - readOnly true, readOnlyHint false",
+			cfg: spannerexecutesql.Config{
+				ConfigBase:  tools.ConfigBase{Name: "test-tool", Description: "desc"},
+				ReadOnly:    true,
+				Annotations: &tools.ToolAnnotations{ReadOnlyHint: ptr(false)},
+			},
+			wantErr:     true,
+			errContains: "configuration conflict in tool \"test-tool\"",
+		},
+	}
+
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			_, err := tc.cfg.Initialize(ctx)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got nil")
+				}
+				// Use manual substring check since strings import might not be present
+				errStr := err.Error()
+				found := false
+				for i := 0; i <= len(errStr)-len(tc.errContains); i++ {
+					if errStr[i:i+len(tc.errContains)] == tc.errContains {
+						found = true
+						break
+					}
+				}
+				if !found {
+					t.Errorf("expected error to contain %q, got: %v", tc.errContains, err)
+				}
+			} else {
+				if err != nil {
+					t.Fatalf("unexpected error: %v", err)
+				}
+			}
+		})
+	}
+}