Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.goindex 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.CallToolRequeoutput, 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, iif 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.goindex 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 stringresult 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 queryErrorrequire.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