Skip to content

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

fix(mcp): improve query skill documentation (#18505)

p0ny525eaf6004e1
diff --git a/backend/api/mcp/skills/query.md b/backend/api/mcp/skills/query.md
index 267d54858e..a494ed707e 100644
--- a/backend/api/mcp/skills/query.md
+++ b/backend/api/mcp/skills/query.md
@@ -12,7 +12,7 @@ Run SQL queries against databases managed by Bytebase.
## Prerequisites
- Know the instance and database name
-- Have `bb.databases.query` permission
+- Have `bb.sql.query` permission
## Workflow
@@ -21,13 +21,21 @@ Run SQL queries against databases managed by Bytebase.
search_api(operationId="SQLService/Query")
```
-2. **List databases in project** (if needed):
+2. **List databases** (if needed):
```
call_api(operationId="DatabaseService/ListDatabases", body={
- "parent": "projects/{project-id}"
+ "parent": "workspaces/-",
+ "filter": "name.matches(\"db_name\")"
})
```
+ Filter examples:
+ - `name.matches("employee")` - database name contains "employee"
+ - `project == "projects/{project-id}"` - databases in a project
+ - `instance == "instances/{instance-id}"` - databases in an instance
+ - `engine == "MYSQL"` - MySQL databases only
+ - `environment == "environments/prod" && name.matches("user")` - combine filters
+
3. **Execute SQL**:
```
call_api(operationId="SQLService/Query", body={
@@ -36,10 +44,14 @@ Run SQL queries against databases managed by Bytebase.
})
```
+## Notes
+
+- Query results may contain masked values shown as `******` due to data masking policies. Do not remove or modify masked values.
+
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| database not found | Wrong instance/database name | List databases first |
-| permission denied | Missing bb.databases.query | Check user permissions |
+| permission denied | Missing bb.sql.query | Check user permissions |
| syntax error | Invalid SQL | Check SQL syntax for the database engine |