Execute SQL

Overview

Run SQL queries against databases managed by Bytebase.

Before writing SQL, call get_schema(database=...) to see the current shape.

Prerequisites

• Know the instance and database name
• Have bb.sql.query permission

Workflow

1. Get the schema:

   Copy

   search_api(operationId="SQLService/Query")
   

2. List databases (if needed):

   Copy

   call_api(operationId="DatabaseService/ListDatabases", body={
     "parent": "workspaces/{id}",
     "filter": "name.contains(\"db_name\")"
   })
   

   Filter examples:

   • name.contains("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.contains("user") - combine filters

   Extract dataSourceId from instanceResource.dataSources in the response. Prefer type: "READ_ONLY" over type: "ADMIN" when available.

3. Execute SQL:

   Copy

   call_api(operationId="SQLService/Query", body={
     "name": "instances/{instance-id}/databases/{database-name}",
     "dataSourceId": "{data-source-id}",
     "statement": "SELECT * FROM users LIMIT 10"
   })
   

   dataSourceId is required.

Notes

• Query results may contain masked values due to data masking policies. Do not remove or modify masked values.
  • Full mask: ******
  • Partial mask: **rn** (only "rn" visible)
• Displaying partial masks: Use backticks or code blocks when presenting results. Without escaping, markdown interprets **text** as bold formatting.

Common Errors

Error	Cause	Fix
data source id is required	Missing dataSourceId field	Get dataSourceId from instanceResource.dataSources in database listing
database not found	Wrong instance/database name	List databases first
permission denied	Missing bb.sql.query	Check user permissions
syntax error	Invalid SQL	Check SQL syntax for the database engine