Skip to content

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

fix(mcp): report what ran when a query_database request fails (#21705)

Vincent Huang5567e5ce99e5
diff --git a/backend/api/mcp/tool_query.go b/backend/api/mcp/tool_query.go
index e41871f6bb..ed6c824e72 100644
--- a/backend/api/mcp/tool_query.go
+++ b/backend/api/mcp/tool_query.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"fmt"
"net/http"
+ "slices"
"strings"
"time"
@@ -122,6 +123,10 @@ func (s *Server) handleQueryDatabase(ctx context.Context, req *mcp.CallToolReque
output, err := s.executeQuery(queryCtx, resolved, input, limit)
if err != nil {
+ var qe *queryError
+ if errors.As(err, &qe) {
+ return formatQueryError(qe), nil, nil
+ }
return formatToolError(err), nil, nil
}
@@ -230,10 +235,11 @@ func (s *Server) executeQuery(ctx context.Context, resolved *resolvedDatabase, i
}
resp, err := s.apiRequest(ctx, "/bytebase.v1.SQLService/Query", body)
if err != nil {
+ // The call can end partway through a batch, as when queryTimeout passes.
return nil, &toolError{
Code: "QUERY_ERROR",
Message: fmt.Sprintf("query request failed: %s", err.Error()),
- Suggestion: "check network connectivity and try again",
+ Suggestion: whatRanUnknown,
}
}
if resp.Status >= 400 {
@@ -241,11 +247,17 @@ func (s *Server) executeQuery(ctx context.Context, resolved *resolvedDatabase, i
if errMsg == "" {
errMsg = fmt.Sprintf("HTTP %d", resp.Status)
}
- // A refusal at this level gets no advice: no access grant lifts a
- // missing bb.databases.get, which the ACL checks first, or an MCP policy.
suggestion := ""
- if resp.Status != http.StatusForbidden && resp.Status != http.StatusUnauthorized {
+ switch {
+ case resp.Status >= http.StatusInternalServerError:
+ // A 5xx can follow statements that ran, as when a SQL Server batch
+ // fails partway: its driver then returns no result.
+ suggestion = whatRanUnknown
+ case resp.Status != http.StatusForbidden && resp.Status != http.StatusUnauthorized:
suggestion = "check your SQL syntax and try again"
+ default:
+ // A refusal at this level gets no advice: no access grant lifts a
+ // missing bb.databases.get, which the ACL checks first, or an MCP policy.
}
return nil, &toolError{
Code: "QUERY_ERROR",
@@ -267,22 +279,10 @@ func (s *Server) executeQuery(ctx context.Context, resolved *resolvedDatabase, i
}, nil
}
- result := qr.Results[0]
- if result.Error != "" {
- suggestion := "check your SQL syntax and try again"
- if result.PermissionDenied != nil {
- // MCP sessions cannot file role requests, so the only advice is a grant.
- suggestion = ""
- if denied := result.PermissionDenied; grantLifts(denied.RequiredPermissions) && withinDatabase(denied.Resources, resolved.resourceName) {
- suggestion = grantAdvice(input.Statement, result.Statement)
- }
- }
- return nil, &toolError{
- Code: "QUERY_ERROR",
- Message: result.Error,
- Suggestion: suggestion,
- }
+ if failed := failedResult(qr.Results); failed >= 0 {
+ return nil, queryFailure(qr.Results, failed, resolved.resourceName)
}
+ result := qr.Results[0]
// Flatten rows.
rows := make([][]any, 0, len(result.Rows))
@@ -312,6 +312,81 @@ func (s *Server) executeQuery(ctx context.Context, resolved *resolvedDatabase, i
}, nil
}
+const whatRanUnknown = "Bytebase cannot always tell which statements of a failed request ran; if it held a write, check the data before you retry"
+
+// queryError is a failed query_database request.
+type queryError struct {
+ Code string `json:"code"`
+ Message string `json:"message"`
+ Suggestion string `json:"suggestion,omitempty"`
+ // FailedStatement is what Bytebase reported as failed: one statement, or
+ // the whole request where Query runs it as one unit, as on SQL Server.
+ FailedStatement string `json:"failedStatement,omitempty"`
+ // Ran can name FailedStatement too, when its error came after it ran. It
+ // names a SQL Server procedure call once per result set the call returned:
+ // the driver gives each later set the call's statement.
+ Ran []string `json:"ran,omitempty"`
+}
+
+func (e *queryError) Error() string {
+ return fmt.Sprintf("%s: %s", e.Code, e.Message)
+}
+
+// formatQueryError formats a queryError into an MCP error result.
+func formatQueryError(err *queryError) *mcp.CallToolResult {
+ jsonBytes, _ := json.MarshalIndent(err, "", " ")
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{&mcp.TextContent{Text: string(jsonBytes)}},
+ IsError: true,
+ }
+}
+
+// ran reports whether the result's statement ran. A result with column names
+// came from a result set, so its statement ran even when an error follows, as
+// when the size limit cuts it short or masking withholds its rows.
+func (r queryResult) ran() bool {
+ return r.Error == "" || len(r.ColumnNames) > 0
+}
+
+// failedResult returns the index of the result to report as failed: the first
+// whose statement did not run, else the first with an error, or -1.
+func failedResult(results []queryResult) int {
+ if i := slices.IndexFunc(results, func(r queryResult) bool { return !r.ran() }); i >= 0 {
+ return i
+ }
+ return slices.IndexFunc(results, func(r queryResult) bool { return r.Error != "" })
+}
+
+// queryFailure reports a request whose failed result is results[failed].
+func queryFailure(results []queryResult, failed int, database string) *queryError {
+ qe := &queryError{
+ Code: "QUERY_ERROR",
+ Message: results[failed].Error,
+ FailedStatement: strings.TrimSpace(results[failed].Statement),
+ }
+ for _, r := range results {
+ if r.ran() {
+ qe.Ran = append(qe.Ran, strings.TrimSpace(r.Statement))
+ }
+ }
+ denied := results[failed].PermissionDenied
+ // The access check refuses a statement before it runs, so a denial with
+ // nothing in ran changed nothing and gets no caution.
+ var advice []string
+ if len(qe.Ran) > 0 {
+ advice = append(advice, "Bytebase ran the statements in ran, in a session that has since closed; check the data before you retry")
+ } else if denied == nil {
+ advice = append(advice, whatRanUnknown)
+ }
+ // MCP sessions cannot file role requests, so a grant is the only access
+ // advice a denial gets.
+ if denied != nil && grantLifts(denied.RequiredPermissions) && withinDatabase(denied.Resources, database) {
+ advice = append(advice, grantAdvice)
+ }
+ qe.Suggestion = strings.Join(advice, "; ")
+ return qe
+}
+
// maskedColumns pairs each masked column with its reason. Query aligns masked
// with the columns by index and sends {} for an unmasked column, and the list
// can be shorter than the columns, leaving the rest unmasked (doMaskResult in
@@ -442,16 +517,7 @@ func withinDatabase(resources []string, database string) bool {
return true
}
-// grantAdvice names the refused statement when the input was a batch. Query
-// runs a batch one statement at a time and stops at the first refusal
-// (queryRetryStopOnError), and a grant applies only to the exact read-only
-// statement it names (hashAccessGrantQuery).
-func grantAdvice(input, refused string) string {
- const howTo = "(the project must allow just-in-time access); otherwise the user requests access in the SQL Editor"
- refused = strings.TrimSpace(refused)
- if refused == "" || refused == strings.TrimSpace(input) {
- return "in a Read-write session, request an access grant for this statement with request_access_grant " + howTo
- }
- return fmt.Sprintf("the batch stopped at %q: in a Read-write session, request an access grant for that statement alone "+
- "with request_access_grant and, once approved, run it by itself %s", refused, howTo)
-}
+// grantAdvice advises on a refusal an access grant lifts. A grant applies only
+// to the exact read-only statement it names (hashAccessGrantQuery).
+const grantAdvice = "in a Read-write session, request an access grant for failedStatement with request_access_grant and, " +
+ "once approved, run it by itself (the project must allow just-in-time access); otherwise the user requests access in the SQL Editor"
diff --git a/backend/api/mcp/tool_query_test.go b/backend/api/mcp/tool_query_test.go
index 5fded9bae4..8f2c97f086 100644
--- a/backend/api/mcp/tool_query_test.go
+++ b/backend/api/mcp/tool_query_test.go
@@ -682,6 +682,8 @@ func TestQueryDatabase_TableAccessDenialAdvisesAnAccessGrant(t *testing.T) {
databases := []map[string]any{
makeDatabase("projects/hr/instances/prod-pg/databases/employee_db", "projects/hr/instances/prod-pg", "projects/hr", "POSTGRES", "ds-admin-1"),
}
+ const wantGrant = "in a Read-write session, request an access grant for failedStatement with request_access_grant and, " +
+ "once approved, run it by itself (the project must allow just-in-time access); otherwise the user requests access in the SQL Editor"
for name, tt := range map[string]struct {
statement string
result map[string]any
@@ -696,8 +698,7 @@ func TestQueryDatabase_TableAccessDenialAdvisesAnAccessGrant(t *testing.T) {
"resources": []string{"projects/hr/instances/prod-pg/databases/employee_db/schemas/public/tables/employee"},
},
},
- want: "in a Read-write session, request an access grant for this statement with request_access_grant " +
- "(the project must allow just-in-time access); otherwise the user requests access in the SQL Editor",
+ want: wantGrant,
},
// A grant must name a read-only statement and applies only to that exact
// statement, so the batch as a whole can neither be granted nor use the grant.
@@ -711,20 +712,18 @@ func TestQueryDatabase_TableAccessDenialAdvisesAnAccessGrant(t *testing.T) {
"resources": []string{"projects/hr/instances/prod-pg/databases/employee_db/schemas/public/tables/employee"},
},
},
- want: `the batch stopped at "SELECT first_name FROM employee;": in a Read-write session, request an access grant for that statement alone ` +
- "with request_access_grant and, once approved, run it by itself " +
- "(the project must allow just-in-time access); otherwise the user requests access in the SQL Editor",
+ want: wantGrant,
},
"the access check refused a metadata read": {
result: map[string]any{
- "error": "permission_denied: permission denied to access resources: projects/hr/instances/prod-pg/databases/employee_db",
+ "error": "permission_denied: permission denied to access resources: projects/hr/instances/prod-pg/databases/employee_db",
+ "statement": "SELECT first_name FROM employee",
"permissionDenied": map[string]any{
"requiredPermissions": []string{"bb.sql.info"},
"resources": []string{"projects/hr/instances/prod-pg/databases/employee_db"},
},
},
- want: "in a Read-write session, request an access grant for this statement with request_access_grant " +
- "(the project must allow just-in-time access); otherwise the user requests access in the SQL Editor",
+ want: wantGrant,
},
// A grant from request_access_grant targets the queried database only.
"the access check refused a table in another database": {
@@ -764,7 +763,7 @@ func TestQueryDatabase_TableAccessDenialAdvisesAnAccessGrant(t *testing.T) {
},
"a statement the engine rejected": {
result: map[string]any{"error": `syntax error at or near "SELEC"`},
- want: "check your SQL syntax and try again",
+ want: "Bytebase cannot always tell which statements of a failed request ran; if it held a write, check the data before you retry",
},
} {
t.Run(name, func(t *testing.T) {
@@ -788,7 +787,7 @@ func TestQueryDatabase_TableAccessDenialAdvisesAnAccessGrant(t *testing.T) {
})
require.NoError(t, err)
require.True(t, result.IsError)
- var denial toolError
+ var denial queryError
require.NoError(t, json.Unmarshal([]byte(result.Content[0].(*mcpsdk.TextContent).Text), &denial))
require.Equal(t, tt.result["error"], denial.Message)
require.Equal(t, tt.want, denial.Suggestion)
@@ -846,8 +845,211 @@ func TestQueryDatabase_Timeout(t *testing.T) {
dataSourceID: "ds-admin-1",
}
_, err := s.executeQuery(ctx, resolved, QueryInput{Statement: "SELECT 1"}, 100)
- require.Error(t, err)
- require.Contains(t, err.Error(), "QUERY_ERROR")
+ var te *toolError
+ require.ErrorAs(t, err, &te)
+ require.Equal(t, "QUERY_ERROR", te.Code)
+ require.Equal(t, "Bytebase cannot always tell which statements of a failed request ran; if it held a write, check the data before you retry", te.Suggestion)
+}
+
+// Query returns a result per statement and stops at the first failure, so the
+// failure can follow results for statements that ran. The splitter keeps the
+// whitespace before each statement after the first.
+func TestQueryDatabase_FailureReportsWhatRan(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod-pg/databases/employee_db", "instances/prod-pg", "projects/hr-system", "POSTGRES", "ds-admin-1"),
+ }
+ const (
+ ranAdvice = "Bytebase ran the statements in ran, in a session that has since closed; check the data before you retry"
+ unknownAdvice = "Bytebase cannot always tell which statements of a failed request ran; if it held a write, check the data before you retry"
+ withheld = "Rows returned by a procedure call or an OUTPUT clause are hidden because data masking can't be applied to them."
+ wantGrant = "in a Read-write session, request an access grant for failedStatement with request_access_grant and, " +
+ "once approved, run it by itself (the project must allow just-in-time access); otherwise the user requests access in the SQL Editor"
+ )
+ for name, tt := range map[string]struct {
+ statement string
+ results []map[string]any
+ wantMessage string
+ wantFailed string
+ wantRan []string
+ wantSuggestion string
+ }{
+ "a later statement failed": {
+ statement: "INSERT INTO t VALUES (1); INSERT INTO t VALUES (2); INSERT INTO t VALUES (1), (3);",
+ results: []map[string]any{
+ {"columnNames": []string{"Affected Rows"}, "statement": "INSERT INTO t VALUES (1);"},
+ {"columnNames": []string{"Affected Rows"}, "statement": " INSERT INTO t VALUES (2);"},
+ {"error": `duplicate key value violates unique constraint "t_pkey"`, "statement": " INSERT INTO t VALUES (1), (3);"},
+ },
+ wantFailed: "INSERT INTO t VALUES (1), (3);",
+ wantRan: []string{"INSERT INTO t VALUES (1);", "INSERT INTO t VALUES (2);"},
+ wantSuggestion: ranAdvice,
+ },
+ "the first statement of a batch failed": {
+ statement: "UPDATE t SET a = 1; UPDATE t SET b = 2;",
+ results: []map[string]any{
+ {"error": `column "a" does not exist`, "statement": "UPDATE t SET a = 1;"},
+ },
+ wantFailed: "UPDATE t SET a = 1;",
+ wantSuggestion: unknownAdvice,
+ },
+ "a single statement failed": {
+ statement: "UPDATE t SET a = 1",
+ results: []map[string]any{
+ {"error": `column "a" does not exist`, "statement": "UPDATE t SET a = 1"},
+ },
+ wantFailed: "UPDATE t SET a = 1",
+ wantSuggestion: unknownAdvice,
+ },
+ "the access check refused a read after a statement ran": {
+ statement: "INSERT INTO t VALUES (1); SELECT first_name FROM employee;",
+ results: []map[string]any{
+ {"columnNames": []string{"Affected Rows"}, "statement": "INSERT INTO t VALUES (1);"},
+ {
+ "error": "permission_denied: permission denied to access resources: [instances/prod-pg/databases/employee_db/schemas/public/tables/employee]",
+ "statement": " SELECT first_name FROM employee;",
+ "permissionDenied": map[string]any{
+ "requiredPermissions": []string{"bb.sql.select"},
+ "resources": []string{"instances/prod-pg/databases/employee_db/schemas/public/tables/employee"},
+ },
+ },
+ },
+ wantFailed: "SELECT first_name FROM employee;",
+ wantRan: []string{"INSERT INTO t VALUES (1);"},
+ wantSuggestion: ranAdvice + "; " + wantGrant,
+ },
+ "the access check refused a write after a statement ran": {
+ statement: "INSERT INTO t VALUES (1); DROP TABLE t;",
+ results: []map[string]any{
+ {"columnNames": []string{"Affected Rows"}, "statement": "INSERT INTO t VALUES (1);"},
+ {
+ "error": "permission_denied: permission denied to access resources: [instances/prod-pg/databases/employee_db/schemas/public/tables/t]",
+ "statement": " DROP TABLE t;",
+ "permissionDenied": map[string]any{"requiredPermissions": []string{"bb.sql.ddl"}},
+ },
+ },
+ wantFailed: "DROP TABLE t;",
+ wantRan: []string{"INSERT INTO t VALUES (1);"},
+ wantSuggestion: ranAdvice,
+ },
+ "a read over the size limit before a failed statement": {
+ statement: "SELECT * FROM big; INSERT INTO t VALUES (1), (3);",
+ results: []map[string]any{
+ {"columnNames": []string{"id"}, "error": "Output of query exceeds max allowed output size of 10MB", "statement": "SELECT * FROM big;"},
+ {"error": `duplicate key value violates unique constraint "t_pkey"`, "statement": " INSERT INTO t VALUES (1), (3);"},
+ },
+ wantFailed: "INSERT INTO t VALUES (1), (3);",
+ wantRan: []string{"SELECT * FROM big;"},
+ wantSuggestion: ranAdvice,
+ },
+ "rows withheld from a write that ran": {
+ statement: "INSERT INTO t OUTPUT inserted.id VALUES (1); UPDATE t SET a = 1;",
+ results: []map[string]any{
+ {
+ "columnNames": []string{"id"},
+ "error": "Rows returned by a procedure call or an OUTPUT clause are hidden because data masking can't be applied to them.",
+ "statement": "INSERT INTO t OUTPUT inserted.id VALUES (1);",
+ },
+ {"columnNames": []string{"Affected Rows"}, "statement": " UPDATE t SET a = 1;"},
+ },
+ wantMessage: "Rows returned by a procedure call or an OUTPUT clause are hidden because data masking can't be applied to them.",
+ wantFailed: "INSERT INTO t OUTPUT inserted.id VALUES (1);",
+ wantRan: []string{"INSERT INTO t OUTPUT inserted.id VALUES (1);", "UPDATE t SET a = 1;"},
+ wantSuggestion: ranAdvice,
+ },
+ "a procedure call that returned two result sets is named once per set": {
+ statement: "EXEC dbo.two_sets;\nGO\nUPDATE dbo.t SET id = id OUTPUT inserted.id;\nSELECT id FROM dbo.t WHERE id = 1;",
+ results: []map[string]any{
+ {"columnNames": []string{"id"}, "error": withheld, "statement": "EXEC dbo.two_sets;"},
+ {"columnNames": []string{"id"}, "error": withheld, "statement": "UPDATE dbo.t SET id = id OUTPUT inserted.id;"},
+ {"columnNames": []string{"id"}, "statement": "SELECT id FROM dbo.t WHERE id = 1;"},
+ {"columnNames": []string{"s"}, "error": withheld, "statement": "EXEC dbo.two_sets;"},
+ },
+ wantMessage: withheld,
+ wantFailed: "EXEC dbo.two_sets;",
+ wantRan: []string{
+ "EXEC dbo.two_sets;", "UPDATE dbo.t SET id = id OUTPUT inserted.id;", "SELECT id FROM dbo.t WHERE id = 1;", "EXEC dbo.two_sets;",
+ },
+ wantSuggestion: ranAdvice,
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ s := newTestServerWithMock(t, mockQueryServer(databases, map[string]any{"results": tt.results}))
+
+ result, _, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: tt.statement,
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError)
+ var failure queryError
+ require.NoError(t, json.Unmarshal([]byte(result.Content[0].(*mcpsdk.TextContent).Text), &failure))
+ wantMessage := tt.wantMessage
+ if wantMessage == "" {
+ wantMessage = fmt.Sprint(tt.results[len(tt.results)-1]["error"])
+ }
+ require.Equal(t, wantMessage, failure.Message)
+ require.Equal(t, tt.wantFailed, failure.FailedStatement)
+ require.Equal(t, tt.wantRan, failure.Ran)
+ require.Equal(t, tt.wantSuggestion, failure.Suggestion)
+ })
+ }
+}
+
+// Query answers some failures with an HTTP error and no result. A 5xx can
+// follow statements that ran; a 4xx refuses the request before it runs.
+func TestQueryDatabase_HTTPErrorAdvice(t *testing.T) {
+ for name, tt := range map[string]struct {
+ engine string
+ status int
+ body map[string]any
+ wantSuggestion string
+ }{
+ "a SQL Server batch failed partway": {
+ engine: "MSSQL",
+ status: http.StatusInternalServerError,
+ body: map[string]any{"code": "internal", "message": "Violation of PRIMARY KEY constraint 'PK_t'."},
+ wantSuggestion: "Bytebase cannot always tell which statements of a failed request ran; if it held a write, check the data before you retry",
+ },
+ "a PostgreSQL request failed with no result": {
+ engine: "POSTGRES",
+ status: http.StatusInternalServerError,
+ body: map[string]any{"code": "internal", "message": "failed to get database connection: connection refused"},
+ wantSuggestion: "Bytebase cannot always tell which statements of a failed request ran; if it held a write, check the data before you retry",
+ },
+ "Query refused a statement it could not parse": {
+ engine: "POSTGRES",
+ status: http.StatusBadRequest,
+ body: map[string]any{"code": "invalid_argument", "message": `syntax error at or near "SELEC"`},
+ wantSuggestion: "check your SQL syntax and try again",
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ databases := []map[string]any{
+ makeDatabase("instances/prod/databases/employee_db", "instances/prod", "projects/hr-system", tt.engine, "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(tt.status)
+ _ = json.NewEncoder(w).Encode(tt.body)
+ return
+ }
+ mockListDatabases(databases).ServeHTTP(w, r)
+ })
+ s := newTestServerWithMock(t, handler)
+
+ result, _, err := s.handleQueryDatabase(testContext(), nil, QueryInput{
+ Database: "employee_db",
+ Statement: "INSERT INTO t VALUES (1); INSERT INTO t VALUES (2);",
+ })
+ require.NoError(t, err)
+ require.True(t, result.IsError)
+ var failure toolError
+ require.NoError(t, json.Unmarshal([]byte(result.Content[0].(*mcpsdk.TextContent).Text), &failure))
+ require.Equal(t, tt.body["message"], failure.Message)
+ require.Equal(t, tt.wantSuggestion, failure.Suggestion)
+ })
+ }
}
// protoQueryResponse encodes resp with protojson.MarshalOptions{}, the options