Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

feat(mcp): implement query execution for query_database tool (#19666)

Vincent Huangf002603f87ef
diff --git a/backend/api/mcp/tool_query.go b/backend/api/mcp/tool_query.go
index 7e82b8eb27..323d828850 100644
--- a/backend/api/mcp/tool_query.go
+++ b/backend/api/mcp/tool_query.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"fmt"
+ "net/http"
"strings"
"time"
@@ -415,7 +416,179 @@ func formatAmbiguousResult(database string, candidates []Candidate) *mcp.CallToo
}
}
+// queryResponse is the typed response from the SQL Query API.
+type queryResponse struct {
+ Results []queryResult `json:"results"`
+}
+
+// queryResult represents a single result set from a query.
+type queryResult struct {
+ ColumnNames []string `json:"columnNames"`
+ ColumnTypeNames []string `json:"columnTypeNames"`
+ Rows []queryRow `json:"rows"`
+ RowsCount json.Number `json:"rowsCount"`
+ Latency string `json:"latency"`
+ Error string `json:"error"`
+ Statement string `json:"statement"`
+}
+
+// queryRow represents a row of values from a query result.
+type queryRow struct {
+ Values []json.RawMessage `json:"values"`
+}
+
// executeQuery executes a SQL query against the resolved database.
-func (*Server) executeQuery(_ context.Context, _ *resolvedDatabase, _ string, _ int) (*QueryOutput, error) {
- return nil, errors.New("not implemented")
+func (s *Server) executeQuery(ctx context.Context, resolved *resolvedDatabase, statement string, limit int) (*QueryOutput, error) {
+ body := map[string]any{
+ "name": resolved.resourceName,
+ "dataSourceId": resolved.dataSourceID,
+ "statement": statement,
+ }
+ resp, err := s.apiRequest(ctx, "/bytebase.v1.SQLService/Query", body)
+ if err != nil {
+ return nil, &toolError{
+ Code: "QUERY_ERROR",
+ Message: fmt.Sprintf("query request failed: %s", err.Error()),
+ Suggestion: "check network connectivity and try again",
+ }
+ }
+ if resp.Status >= 400 {
+ errMsg := parseError(resp.Body)
+ if errMsg == "" {
+ errMsg = fmt.Sprintf("HTTP %d", resp.Status)
+ }
+ suggestion := "check your SQL syntax and try again"
+ if resp.Status == http.StatusForbidden || resp.Status == http.StatusUnauthorized {
+ suggestion = "you may not have permission to query this database — request the SQL Editor role on the project"
+ }
+ return nil, &toolError{
+ Code: "QUERY_ERROR",
+ Message: errMsg,
+ Suggestion: suggestion,
+ }
+ }
+
+ var qr queryResponse
+ if err := json.Unmarshal(resp.Body, &qr); err != nil {
+ return nil, errors.Wrap(err, "failed to parse query response")
+ }
+ if len(qr.Results) == 0 {
+ return &QueryOutput{
+ Columns: []string{},
+ ColumnTypes: []string{},
+ Rows: [][]any{},
+ }, nil
+ }
+
+ result := qr.Results[0]
+ if result.Error != "" {
+ return nil, &toolError{
+ Code: "QUERY_ERROR",
+ Message: result.Error,
+ Suggestion: "check your SQL syntax and try again",
+ }
+ }
+
+ // Flatten rows.
+ rows := make([][]any, 0, len(result.Rows))
+ for _, row := range result.Rows {
+ flat := make([]any, 0, len(row.Values))
+ for _, v := range row.Values {
+ flat = append(flat, flattenRowValue(v))
+ }
+ rows = append(rows, flat)
+ }
+
+ // Truncation.
+ truncated := len(rows) > limit
+ if truncated {
+ rows = rows[:limit]
+ }
+
+ return &QueryOutput{
+ Columns: result.ColumnNames,
+ ColumnTypes: result.ColumnTypeNames,
+ Rows: rows,
+ RowCount: len(rows),
+ Truncated: truncated,
+ LatencyMs: parseLatencyMs(result.Latency),
+ }, nil
+}
+
+// flattenRowValue extracts a plain Go value from a protojson RowValue oneof.
+// Each value is a JSON object with exactly one key like {"stringValue": "x"}.
+func flattenRowValue(raw json.RawMessage) any {
+ var m map[string]json.RawMessage
+ if json.Unmarshal(raw, &m) != nil {
+ return string(raw)
+ }
+ for key, val := range m {
+ if v, ok := unmarshalRowField(key, val); ok {
+ return v
+ }
+ }
+ return string(raw)
+}
+
+// unmarshalRowField decodes a single protojson RowValue oneof field.
+func unmarshalRowField(key string, val json.RawMessage) (any, bool) {
+ switch key {
+ case "nullValue":
+ return nil, true
+ case "boolValue":
+ return unmarshalAs[bool](val)
+ case "stringValue":
+ return unmarshalAs[string](val)
+ case "int32Value":
+ return unmarshalAs[int32](val)
+ case "int64Value":
+ // protojson encodes int64 as string.
+ if v, ok := unmarshalAs[string](val); ok {
+ return v, true
+ }
+ return unmarshalAs[int64](val)
+ case "doubleValue", "floatValue":
+ return unmarshalAs[float64](val)
+ case "timestampValue", "timestampTzValue":
+ return unmarshalTimestamp(val)
+ default:
+ if v, ok := unmarshalAs[string](val); ok {
+ return v, true
+ }
+ return string(val), true
+ }
+}
+
+// unmarshalAs attempts to decode JSON into the given type.
+func unmarshalAs[T any](val json.RawMessage) (T, bool) {
+ var v T
+ if json.Unmarshal(val, &v) == nil {
+ return v, true
+ }
+ return v, false
+}
+
+// unmarshalTimestamp extracts the string value from a timestamp object.
+func unmarshalTimestamp(val json.RawMessage) (any, bool) {
+ var ts map[string]string
+ if json.Unmarshal(val, &ts) == nil {
+ if v, ok := ts["value"]; ok {
+ return v, true
+ }
+ }
+ return nil, false
+}
+
+// parseLatencyMs parses a duration string like "0.012s" into milliseconds.
+func parseLatencyMs(latency string) int64 {
+ latency = strings.TrimSpace(latency)
+ if latency == "" {
+ return 0
+ }
+ latency = strings.TrimSuffix(latency, "s")
+ d, err := time.ParseDuration(latency + "s")
+ if err != nil {
+ return 0
+ }
+ return d.Milliseconds()
}
diff --git a/backend/api/mcp/tool_query_test.go b/backend/api/mcp/tool_query_test.go
index 14c278c6fc..afd1143d44 100644
--- a/backend/api/mcp/tool_query_test.go
+++ b/backend/api/mcp/tool_query_test.go
@@ -7,6 +7,7 @@ import (
"net/http"
"strings"
"testing"
+ "time"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/stretchr/testify/require"
@@ -128,6 +129,46 @@ func applyMockFilter(databases []map[string]any, filter string) []map[string]any
return result
}
+// makeQueryResponse builds a mock SQL Query API response.
+func makeQueryResponse(columns, columnTypes []string, rows [][]any, latency string) map[string]any {
+ apiRows := make([]map[string]any, 0, len(rows))
+ for _, row := range rows {
+ values := make([]map[string]any, 0, len(row))
+ for _, v := range row {
+ values = append(values, map[string]any{"stringValue": v})
+ }
+ apiRows = append(apiRows, map[string]any{"values": values})
+ }
+ return map[string]any{
+ "results": []map[string]any{
+ {
+ "columnNames": columns,
+ "columnTypeNames": columnTypes,
+ "rows": apiRows,
+ "rowsCount": fmt.Sprintf("%d", len(rows)),
+ "latency": latency,
+ "error": "",
+ "statement": "SELECT ...",
+ },
+ },
+ }
+}
+
+// mockQueryServer returns an HTTP handler that routes to ListDatabases or Query
+// based on the request URL path.
+func mockQueryServer(databases []map[string]any, queryResp map[string]any) http.Handler {
+ listHandler := mockListDatabases(databases)
+ return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if strings.Contains(r.URL.Path, "SQLService/Query") {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _ = json.NewEncoder(w).Encode(queryResp)
+ return
+ }
+ listHandler.ServeHTTP(w, r)
+ })
+}
+
func TestQueryDatabase_SingleMatch(t *testing.T) {
databases := []map[string]any{
makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
@@ -300,25 +341,24 @@ func TestQueryDatabase_HandleValidation(t *testing.T) {
func TestQueryDatabase_LimitNormalization(t *testing.T) {
// Verify limit is capped at maxQueryLimit via the handler.
- // We test the handler which calls resolveDatabase, so the database must not be found
- // to avoid hitting the executeQuery stub. We just verify the handler doesn't panic.
databases := []map[string]any{
makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
}
- s := newTestServerWithMock(t, mockListDatabases(databases))
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, [][]any{{"1"}}, "0.001s")
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
- // The handler resolves the database, then calls executeQuery which returns "not implemented".
- // That's expected — we verify the handler doesn't error on limit normalization.
- result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
Database: "employee_db",
Statement: "SELECT 1",
Limit: 2000,
})
- // Should return IsError result from executeQuery stub, not a limit error.
+ // Should succeed — limit capped to 1000, but only 1 row returned.
require.NoError(t, err)
- require.True(t, result.IsError)
- text := result.Content[0].(*mcpsdk.TextContent).Text
- require.Contains(t, text, "not implemented")
+ require.False(t, result.IsError)
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, 1, output.RowCount)
+ require.False(t, output.Truncated)
}
func TestQueryDatabase_ExactMatchPriority(t *testing.T) {
@@ -335,3 +375,258 @@ func TestQueryDatabase_ExactMatchPriority(t *testing.T) {
require.Equal(t, "instances/prod-pg/databases/employee", resolved.resourceName)
require.Equal(t, "ds-1", resolved.dataSourceID)
}
+
+// --- Task 5 tests: query execution ---
+
+func TestQueryDatabase_FullFlow(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ qr := makeQueryResponse(
+ []string{"id", "name"},
+ []string{"int4", "varchar"},
+ [][]any{{"1", "John"}, {"2", "Jane"}},
+ "0.012s",
+ )
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
+
+ result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id, name FROM users",
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, []string{"id", "name"}, output.Columns)
+ require.Equal(t, []string{"int4", "varchar"}, output.ColumnTypes)
+ require.Equal(t, 2, output.RowCount)
+ require.False(t, output.Truncated)
+ require.Equal(t, int64(12), output.LatencyMs)
+ require.Len(t, output.Rows, 2)
+ require.Equal(t, "1", output.Rows[0][0])
+ require.Equal(t, "John", output.Rows[0][1])
+
+ // Verify text header.
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "Result: 2 rows")
+ require.NotContains(t, text, "Truncated")
+}
+
+func TestQueryDatabase_EmptyResult(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ qr := makeQueryResponse(
+ []string{"id", "name"},
+ []string{"int4", "varchar"},
+ [][]any{},
+ "0.005s",
+ )
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
+
+ result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT * FROM users WHERE id = -1",
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Empty(t, output.Rows)
+ require.Equal(t, 0, output.RowCount)
+ require.False(t, output.Truncated)
+}
+
+func TestQueryDatabase_Truncation(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ // Generate 150 rows.
+ rows := make([][]any, 150)
+ for i := range rows {
+ rows[i] = []any{fmt.Sprintf("%d", i+1)}
+ }
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.050s")
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
+
+ result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id FROM users",
+ // Default limit is 100.
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, 100, output.RowCount)
+ require.True(t, output.Truncated)
+
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "Truncated")
+}
+
+func TestQueryDatabase_CustomLimit(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ rows := make([][]any, 100)
+ for i := range rows {
+ rows[i] = []any{fmt.Sprintf("%d", i+1)}
+ }
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.020s")
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
+
+ result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id FROM users",
+ Limit: 50,
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, 50, output.RowCount)
+ require.True(t, output.Truncated)
+}
+
+func TestQueryDatabase_LimitCappedAt1000(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ rows := make([][]any, 5)
+ for i := range rows {
+ rows[i] = []any{fmt.Sprintf("%d", i+1)}
+ }
+ qr := makeQueryResponse([]string{"id"}, []string{"int4"}, rows, "0.003s")
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
+
+ result, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id FROM users",
+ Limit: 2000,
+ })
+ require.NoError(t, err)
+ require.False(t, result.IsError)
+
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, 5, output.RowCount)
+ require.False(t, output.Truncated)
+}
+
+func TestQueryDatabase_QueryError(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if strings.Contains(r.URL.Path, "SQLService/Query") {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusBadRequest)
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "message": "syntax error at or near \"SELEC\"",
+ "code": "INVALID_ARGUMENT",
+ })
+ return
+ }
+ mockListDatabases(databases).ServeHTTP(w, r)
+ })
+ s := newTestServerWithMock(t, handler)
+
+ result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELEC * FROM users",
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError)
+
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "syntax error")
+}
+
+func TestQueryDatabase_PermissionDenied(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if strings.Contains(r.URL.Path, "SQLService/Query") {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusForbidden)
+ _ = json.NewEncoder(w).Encode(map[string]any{
+ "message": "permission denied",
+ "code": "PERMISSION_DENIED",
+ })
+ return
+ }
+ mockListDatabases(databases).ServeHTTP(w, r)
+ })
+ s := newTestServerWithMock(t, handler)
+
+ result, _, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT * FROM users",
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError)
+
+ text := result.Content[0].(*mcpsdk.TextContent).Text
+ require.Contains(t, text, "permission denied")
+}
+
+// --- Task 6 tests: masked values and timeout ---
+
+func TestQueryDatabase_MaskedValues(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ qr := makeQueryResponse(
+ []string{"id", "ssn", "name"},
+ []string{"int4", "varchar", "varchar"},
+ [][]any{{"1", "******", "**rn**"}},
+ "0.010s",
+ )
+ s := newTestServerWithMock(t, mockQueryServer(databases, qr))
+
+ _, structured, err := s.handleQueryDatabase(context.Background(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "SELECT id, ssn, name FROM users",
+ })
+ require.NoError(t, err)
+
+ output, ok := structured.(*QueryOutput)
+ require.True(t, ok)
+ require.Equal(t, "******", output.Rows[0][1])
+ require.Equal(t, "**rn**", output.Rows[0][2])
+}
+
+func TestQueryDatabase_Timeout(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if strings.Contains(r.URL.Path, "SQLService/Query") {
+ // Sleep longer than the context timeout.
+ time.Sleep(500 * time.Millisecond)
+ w.WriteHeader(http.StatusOK)
+ return
+ }
+ mockListDatabases(databases).ServeHTTP(w, r)
+ })
+ s := newTestServerWithMock(t, handler)
+
+ // Use a very short timeout.
+ ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+ defer cancel()
+
+ resolved := &resolvedDatabase{
+ resourceName: "instances/prod-pg/databases/employee_db",
+ dataSourceID: "ds-admin-1",
+ }
+ _, err := s.executeQuery(ctx, resolved, "SELECT 1", 100)
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "QUERY_ERROR")
+}
diff --git a/backend/api/mcp/tool_skill.go b/backend/api/mcp/tool_skill.go
index 0190b71aa9..c5c84bc9c4 100644
--- a/backend/api/mcp/tool_skill.go
+++ b/backend/api/mcp/tool_skill.go
@@ -30,6 +30,8 @@ type skillMeta struct {
// getSkillDescription is the description for the get_skill tool.
const getSkillDescription = `Get step-by-step guides for Bytebase tasks.
+**Tip:** Use query_database tool for SQL queries — it handles database resolution automatically.
+
**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)
Skills: query, database-change, grant-permission`