feat: add spanner-execute-sql tool (#576)

This tool can be used across spanner sources. `spanner-execute-sql` config is as below: ``` tools: spanner_execute_sql_tool: kind: "spanner-execute-sql" source: my-spanner-source description: Use this tool to execute sql. ``` The `spanner-execute-sql` tool takes one parameter. Example request as follow: ``` curl -X POST -H "Content-Type: application/json" -d '{"sql": "SELECT 1"}' http://127.0.0.1:5000/api/tool/spanner_execute_sql_tool/invoke ``` --------- Co-authored-by: Yuan <45984206+Yuan325@users.noreply.github.com>
2026-01-10 07:58:12 -05:00 · 2025-05-20 03:18:11 +05:30
parent 8590061ae4
commit d65747a2dc
5 changed files with 519 additions and 2 deletions
--- a/docs/en/resources/tools/spanner-execute-sql.md
+++ b/docs/en/resources/tools/spanner-execute-sql.md
@@ -0,0 +1,37 @@
+---
+title: "spanner-execute-sql"
+type: docs
+weight: 1
+description: > 
+  A "spanner-execute-sql" tool executes a SQL statement against a Spanner
+  database.
+---
+
+## About
+
+A `spanner-execute-sql` tool executes a SQL statement against a Spanner
+database. It's compatible with any of the following sources:
+
+- [spanner](../sources/spanner.md)
+
+`spanner-execute-sql` takes one input parameter `sql` and run the sql
+statement against the `source`.
+
+## Example
+
+```yaml
+tools:
+ execute_sql_tool:
+    kind: spanner-execute-sql
+    source: my-spanner-instance
+    description: Use this tool to execute sql statement.
+```
+
+## Reference
+
+| **field**   |                  **type**                  | **required** | **description**                                                                                  |
+|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
+| kind        |                   string                   |     true     | Must be "spanner-execute-sql".                                                                          |
+| source      |                   string                   |     true     | Name of the source the SQL should execute on.                                                    |
+| description |                   string                   |     true     | Description of the tool that is passed to the LLM.                                               |
+| readOnly    |                   bool                     |     false    | When set to `true`, the `statement` is run as a read-only transaction. Default: `false`.         |
--- a/internal/server/config.go
+++ b/internal/server/config.go
@@ -51,6 +51,7 @@ import (
 	"github.com/googleapis/genai-toolbox/internal/tools/postgresexecutesql"
 	"github.com/googleapis/genai-toolbox/internal/tools/postgressql"
 	"github.com/googleapis/genai-toolbox/internal/tools/spanner"
+	"github.com/googleapis/genai-toolbox/internal/tools/spannerexecutesql"
 	"github.com/googleapis/genai-toolbox/internal/tools/sqlitesql"
 	"github.com/googleapis/genai-toolbox/internal/util"
 )
@@ -419,6 +420,12 @@ func (c *ToolConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(interfac
 				return fmt.Errorf("unable to parse as %q: %w", kind, err)
 			}
 			(*c)[name] = actual
+		case spannerexecutesql.ToolKind:
+			actual := spannerexecutesql.Config{Name: name}
+			if err := dec.DecodeContext(ctx, &actual); err != nil {
+				return fmt.Errorf("unable to parse as %q: %w", kind, err)
+			}
+			(*c)[name] = actual
 		case couchbasetool.ToolKind:
 			actual := couchbasetool.Config{Name: name}
 			if err := dec.DecodeContext(ctx, &actual); err != nil {
--- a/internal/tools/spannerexecutesql/spannerexecutesql.go
+++ b/internal/tools/spannerexecutesql/spannerexecutesql.go
@@ -0,0 +1,179 @@
+// Copyright 2024 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
+//
+//     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 spannerexecutesql
+
+import (
+	"context"
+	"fmt"
+
+	"cloud.google.com/go/spanner"
+	"github.com/googleapis/genai-toolbox/internal/sources"
+	spannerdb "github.com/googleapis/genai-toolbox/internal/sources/spanner"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+	"google.golang.org/api/iterator"
+)
+
+const ToolKind string = "spanner-execute-sql"
+
+type compatibleSource interface {
+	SpannerClient() *spanner.Client
+	DatabaseDialect() string
+}
+
+// validate compatible sources are still compatible
+var _ compatibleSource = &spannerdb.Source{}
+
+var compatibleSources = [...]string{spannerdb.SourceKind}
+
+type Config struct {
+	Name         string   `yaml:"name" validate:"required"`
+	Kind         string   `yaml:"kind" validate:"required"`
+	Source       string   `yaml:"source" validate:"required"`
+	Description  string   `yaml:"description" validate:"required"`
+	AuthRequired []string `yaml:"authRequired"`
+	ReadOnly     bool     `yaml:"readOnly"`
+}
+
+// validate interface
+var _ tools.ToolConfig = Config{}
+
+func (cfg Config) ToolConfigKind() string {
+	return ToolKind
+}
+
+func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error) {
+	// verify source exists
+	rawS, ok := srcs[cfg.Source]
+	if !ok {
+		return nil, fmt.Errorf("no source named %q configured", cfg.Source)
+	}
+
+	// verify the source is compatible
+	s, ok := rawS.(compatibleSource)
+	if !ok {
+		return nil, fmt.Errorf("invalid source for %q tool: source kind must be one of %q", ToolKind, compatibleSources)
+	}
+
+	sqlParameter := tools.NewStringParameter("sql", "The sql to execute.")
+	parameters := tools.Parameters{sqlParameter}
+
+	mcpManifest := tools.McpManifest{
+		Name:        cfg.Name,
+		Description: cfg.Description,
+		InputSchema: parameters.McpManifest(),
+	}
+
+	// finish tool setup
+	t := Tool{
+		Name:         cfg.Name,
+		Kind:         ToolKind,
+		Parameters:   parameters,
+		AuthRequired: cfg.AuthRequired,
+		ReadOnly:     cfg.ReadOnly,
+		Client:       s.SpannerClient(),
+		dialect:      s.DatabaseDialect(),
+		manifest:     tools.Manifest{Description: cfg.Description, Parameters: parameters.Manifest(), AuthRequired: cfg.AuthRequired},
+		mcpManifest:  mcpManifest,
+	}
+	return t, nil
+}
+
+// validate interface
+var _ tools.Tool = Tool{}
+
+type Tool struct {
+	Name         string           `yaml:"name"`
+	Kind         string           `yaml:"kind"`
+	AuthRequired []string         `yaml:"authRequired"`
+	Parameters   tools.Parameters `yaml:"parameters"`
+	ReadOnly     bool             `yaml:"readOnly"`
+	Client       *spanner.Client
+	dialect      string
+	manifest     tools.Manifest
+	mcpManifest  tools.McpManifest
+}
+
+// processRows iterates over the spanner.RowIterator and converts each row to a map[string]any.
+func processRows(iter *spanner.RowIterator) ([]any, error) {
+	var out []any
+	defer iter.Stop()
+
+	for {
+		row, err := iter.Next()
+		if err == iterator.Done {
+			break
+		}
+		if err != nil {
+			return nil, fmt.Errorf("unable to parse row: %w", err)
+		}
+
+		vMap := make(map[string]any)
+		cols := row.ColumnNames()
+		for i, c := range cols {
+			vMap[c] = row.ColumnValue(i)
+		}
+		out = append(out, vMap)
+	}
+	return out, nil
+}
+
+func (t Tool) Invoke(ctx context.Context, params tools.ParamValues) ([]any, error) {
+	sliceParams := params.AsSlice()
+	sql, ok := sliceParams[0].(string)
+	if !ok {
+		return nil, fmt.Errorf("unable to get cast %s", sliceParams[0])
+	}
+
+	var results []any
+	var opErr error
+	stmt := spanner.Statement{SQL: sql}
+
+	if t.ReadOnly {
+		iter := t.Client.Single().Query(ctx, stmt)
+		results, opErr = processRows(iter)
+	} else {
+		_, opErr = t.Client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
+			var err error
+			iter := txn.Query(ctx, stmt)
+			results, err = processRows(iter)
+			if err != nil {
+				return err
+			}
+			return nil
+		})
+	}
+
+	if opErr != nil {
+		return nil, fmt.Errorf("unable to execute query: %w", opErr)
+	}
+
+	return results, nil
+}
+
+func (t Tool) ParseParams(data map[string]any, claims map[string]map[string]any) (tools.ParamValues, error) {
+	return tools.ParseParams(t.Parameters, data, claims)
+}
+
+func (t Tool) Manifest() tools.Manifest {
+	return t.manifest
+}
+
+func (t Tool) McpManifest() tools.McpManifest {
+	return t.mcpManifest
+}
+
+func (t Tool) Authorized(verifiedAuthServices []string) bool {
+	return tools.IsAuthorized(t.AuthRequired, verifiedAuthServices)
+}
--- a/internal/tools/spannerexecutesql/spannerexecutesql_test.go
+++ b/internal/tools/spannerexecutesql/spannerexecutesql_test.go
@@ -0,0 +1,95 @@
+// Copyright 2024 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
+//
+//     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 spannerexecutesql_test
+
+import (
+	"testing"
+
+	yaml "github.com/goccy/go-yaml"
+	"github.com/google/go-cmp/cmp"
+	"github.com/googleapis/genai-toolbox/internal/server"
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+	"github.com/googleapis/genai-toolbox/internal/tools/spannerexecutesql"
+)
+
+func TestParseFromYamlExecuteSql(t *testing.T) {
+	ctx, err := testutils.ContextWithNewLogger()
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	tcs := []struct {
+		desc string
+		in   string
+		want server.ToolConfigs
+	}{
+		{
+			desc: "basic example",
+			in: `
+			tools:
+				example_tool:
+					kind: spanner-execute-sql
+					source: my-spanner-instance
+					description: some description
+			`,
+			want: server.ToolConfigs{
+				"example_tool": spannerexecutesql.Config{
+					Name:         "example_tool",
+					Kind:         spannerexecutesql.ToolKind,
+					Source:       "my-spanner-instance",
+					Description:  "some description",
+					AuthRequired: []string{},
+					ReadOnly:     false,
+				},
+			},
+		},
+		{
+			desc: "read only set to true",
+			in: `
+			tools:
+				example_tool:
+					kind: spanner-execute-sql
+					source: my-spanner-instance
+					description: some description
+					readOnly: true
+			`,
+			want: server.ToolConfigs{
+				"example_tool": spannerexecutesql.Config{
+					Name:         "example_tool",
+					Kind:         spannerexecutesql.ToolKind,
+					Source:       "my-spanner-instance",
+					Description:  "some description",
+					AuthRequired: []string{},
+					ReadOnly:     true,
+				},
+			},
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			got := struct {
+				Tools server.ToolConfigs `yaml:"tools"`
+			}{}
+			// Parse contents
+			err := yaml.UnmarshalContext(ctx, testutils.FormatYaml(tc.in), &got)
+			if err != nil {
+				t.Fatalf("unable to unmarshal: %s", err)
+			}
+			if diff := cmp.Diff(tc.want, got.Tools); diff != "" {
+				t.Fatalf("incorrect parse: diff %v", diff)
+			}
+		})
+	}
+
+}
--- a/tests/spanner/spanner_integration_test.go
+++ b/tests/spanner/spanner_integration_test.go
@@ -15,8 +15,12 @@
 package spanner

 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"fmt"
+	"io"
+	"net/http"
 	"os"
 	"regexp"
 	"strings"
@@ -97,8 +101,8 @@ func TestSpannerToolEndpoints(t *testing.T) {
 	}

 	// create table name with UUID
-	tableNameParam := "param_table_" + strings.Replace(uuid.New().String(), "-", "", -1)
-	tableNameAuth := "auth_table_" + strings.Replace(uuid.New().String(), "-", "", -1)
+	tableNameParam := "param_table_" + strings.ReplaceAll(uuid.New().String(), "-", "")
+	tableNameAuth := "auth_table_" + strings.ReplaceAll(uuid.New().String(), "-", "")

 	// set up data for param tool
 	create_statement1, insert_statement1, tool_statement1, params1 := getSpannerParamToolInfo(tableNameParam)
@@ -118,6 +122,7 @@ func TestSpannerToolEndpoints(t *testing.T) {

 	// Write config into a file and pass it to command
 	toolsFile := tests.GetToolsConfig(sourceConfig, SPANNER_TOOL_KIND, tool_statement1, tool_statement2)
+	toolsFile = addSpannerExecuteSqlConfig(t, toolsFile)

 	cmd, cleanup, err := tests.StartCmd(ctx, toolsFile, args...)
 	if err != nil {
@@ -142,6 +147,7 @@ func TestSpannerToolEndpoints(t *testing.T) {

 	tests.RunToolInvokeTest(t, select1Want, invokeParamWant)
 	tests.RunMCPToolCallMethod(t, mcpInvokeParamWant, failInvocationWant)
+	runSpannerExecuteSqlToolInvokeTest(t, select1Want, invokeParamWant, tableNameParam, tableNameAuth)
 }

 // getSpannerToolInfo returns statements and param for my-param-tool for spanner-sql kind
@@ -214,3 +220,196 @@ func setupSpannerTable(t *testing.T, ctx context.Context, adminClient *database.
 		}
 	}
 }
+
+// addSpannerExecuteSqlConfig gets the tools config for `spanner-execute-sql`
+func addSpannerExecuteSqlConfig(t *testing.T, config map[string]any) map[string]any {
+	tools, ok := config["tools"].(map[string]any)
+	if !ok {
+		t.Fatalf("unable to get tools from config")
+	}
+	tools["my-exec-sql-tool-read-only"] = map[string]any{
+		"kind":        "spanner-execute-sql",
+		"source":      "my-instance",
+		"description": "Tool to execute sql",
+		"readOnly":    true,
+	}
+	tools["my-exec-sql-tool"] = map[string]any{
+		"kind":        "spanner-execute-sql",
+		"source":      "my-instance",
+		"description": "Tool to execute sql",
+	}
+	tools["my-auth-exec-sql-tool"] = map[string]any{
+		"kind":        "spanner-execute-sql",
+		"source":      "my-instance",
+		"description": "Tool to execute sql",
+		"authRequired": []string{
+			"my-google-auth",
+		},
+	}
+	config["tools"] = tools
+	return config
+}
+
+func runSpannerExecuteSqlToolInvokeTest(t *testing.T, select_1_want, invokeParamWant, tableNameParam, tableNameAuth string) {
+	// Get ID token
+	idToken, err := tests.GetGoogleIdToken(tests.ClientId)
+	if err != nil {
+		t.Fatalf("error getting Google ID token: %s", err)
+	}
+
+	// Test tool invoke endpoint
+	invokeTcs := []struct {
+		name          string
+		api           string
+		requestHeader map[string]string
+		requestBody   io.Reader
+		want          string
+		isErr         bool
+	}{
+		{
+			name:          "invoke my-exec-sql-tool-read-only",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool-read-only/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"SELECT 1"}`)),
+			want:          select_1_want,
+			isErr:         false,
+		},
+		{
+			name:          "invoke my-exec-sql-tool-read-only with data present in table",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool-read-only/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(fmt.Sprintf("{\"sql\":\"SELECT * FROM %s WHERE id = 3 OR name = 'Alice'\"}", tableNameParam))),
+			want:          invokeParamWant,
+			isErr:         false,
+		},
+		{
+			name:          "invoke my-exec-sql-tool-read-only create table",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool-read-only/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"CREATE TABLE t (id SERIAL PRIMARY KEY, name TEXT)"}`)),
+			isErr:         true,
+		},
+		{
+			name:          "invoke my-exec-sql-tool-read-only drop table",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool-read-only/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"DROP TABLE t"}`)),
+			isErr:         true,
+		},
+		{
+			name:          "invoke my-exec-sql-tool-read-only insert entry",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool-read-only/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(fmt.Sprintf("{\"sql\":\"INSERT INTO %s (id, name) VALUES (4, 'test_name')\"}", tableNameParam))),
+			isErr:         true,
+		},
+		{
+			name:          "invoke my-exec-sql-tool without body",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{}`)),
+			isErr:         true,
+		},
+		{
+			name:          "invoke my-exec-sql-tool",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"SELECT 1"}`)),
+			want:          select_1_want,
+			isErr:         false,
+		},
+		{
+			name:          "invoke my-exec-sql-tool create table",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"CREATE TABLE t (id SERIAL PRIMARY KEY, name TEXT)"}`)),
+			isErr:         true,
+		},
+		{
+			name:          "invoke my-exec-sql-tool drop table",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"DROP TABLE t"}`)),
+			isErr:         true,
+		},
+		{
+			name:          "invoke my-exec-sql-tool insert entry",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(fmt.Sprintf("{\"sql\":\"INSERT INTO %s (id, name) VALUES (4, 'test_name')\"}", tableNameParam))),
+			want:          "null",
+			isErr:         false,
+		},
+		{
+			name:          "invoke my-exec-sql-tool without body",
+			api:           "http://127.0.0.1:5000/api/tool/my-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{}`)),
+			isErr:         true,
+		},
+		{
+			name:          "Invoke my-auth-exec-sql-tool with auth token",
+			api:           "http://127.0.0.1:5000/api/tool/my-auth-exec-sql-tool/invoke",
+			requestHeader: map[string]string{"my-google-auth_token": idToken},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"SELECT 1"}`)),
+			isErr:         false,
+			want:          select_1_want,
+		},
+		{
+			name:          "Invoke my-auth-exec-sql-tool with invalid auth token",
+			api:           "http://127.0.0.1:5000/api/tool/my-auth-exec-sql-tool/invoke",
+			requestHeader: map[string]string{"my-google-auth_token": "INVALID_TOKEN"},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"SELECT 1"}`)),
+			isErr:         true,
+		},
+		{
+			name:          "Invoke my-auth-exec-sql-tool without auth token",
+			api:           "http://127.0.0.1:5000/api/tool/my-auth-exec-sql-tool/invoke",
+			requestHeader: map[string]string{},
+			requestBody:   bytes.NewBuffer([]byte(`{"sql":"SELECT 1"}`)),
+			isErr:         true,
+		},
+	}
+	for _, tc := range invokeTcs {
+		t.Run(tc.name, func(t *testing.T) {
+			// Send Tool invocation request
+			req, err := http.NewRequest(http.MethodPost, tc.api, tc.requestBody)
+			if err != nil {
+				t.Fatalf("unable to create request: %s", err)
+			}
+			req.Header.Add("Content-type", "application/json")
+			for k, v := range tc.requestHeader {
+				req.Header.Add(k, v)
+			}
+			resp, err := http.DefaultClient.Do(req)
+			if err != nil {
+				t.Fatalf("unable to send request: %s", err)
+			}
+			defer resp.Body.Close()
+
+			if resp.StatusCode != http.StatusOK {
+				if tc.isErr {
+					return
+				}
+				bodyBytes, _ := io.ReadAll(resp.Body)
+				t.Fatalf("response status code is not 200, got %d: %s", resp.StatusCode, string(bodyBytes))
+			}
+
+			// Check response body
+			var body map[string]interface{}
+			err = json.NewDecoder(resp.Body).Decode(&body)
+			if err != nil {
+				t.Fatalf("error parsing response body")
+			}
+
+			got, ok := body["result"].(string)
+			if !ok {
+				t.Fatalf("unable to find result in response body")
+			}
+
+			if got != tc.want {
+				t.Fatalf("unexpected value: got %q, want %q", got, tc.want)
+			}
+		})
+	}
+}