Query

By default, SQL Editor allows executing both read (SELECT) and write (DDL/DML) SQL statements.Running DDL or DML change statements requires the bb.sql.ddl / bb.sql.dml database permissions, granted for selected environments. Without them, SQL Editor is effectively read-only: if you attempt a DDL or DML change query, SQL Editor will direct you to create a database change plan and follow the change workflow.Workspace Admins and DBAs can always execute any SQL statements in Admin Mode.

On PostgreSQL, a statement that writes data counts as DML even when it starts with SELECT or EXPLAIN: a SELECT whose WITH clause runs INSERT, UPDATE, DELETE, or MERGE, and EXPLAIN ANALYZE of a write or of such a SELECT, which executes it. bb.sql.select alone does not run them. The DML grant is checked against the tables the statement writes, so a grant scoped to those tables is enough. SELECT ... FOR UPDATE and a plain EXPLAIN are not affected.

Autocomplete

Autocomplete depends on WebSocket. If you access Bytebase via a gateway, you need to enable WebSocket there. Here is a NGINX configuration:

http {
    server {
        ...

       location ~ ^/(v1:adminExecute|lsp) {
            proxy_pass http://bytebase.example.com;
            proxy_http_version 1.1;
            # Enables WebSocket which is required for SQL Editor autocomplete
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }
        ...
    }
}

Run query

Click the Run button or use the shortcut key (⌘ + Enter) to run your queries in the SQL Editor. If you have multiple SQL queries separated by semicolons, SQL Editor will only run the first query for now.

Oracle database links

A query that reads a table through a database link (schema.table@link) is authorized against the linked database before it runs, in SQL Editor, export, and MCP alike. It needs the same grant as querying that database directly, checked at the table level when the grant is table-scoped, and the linked database’s masking policy applies to the result.

The link reaches	Result
A database on the same instance, in the same project	Runs with your grant on that database. A denial names the resource to request.
Another instance	Refused. Query that instance directly.
A database in another project, one Bytebase does not track, or a target it cannot identify	Refused.

Bytebase identifies the link’s target from the definition it synced from the instance, by matching the host, port, and service name in the link’s connect string to a data source of exactly one instance. A link that uses a TNS alias, or one added since the last sync, cannot be identified.

Under a read-only data source whose Oracle account owns private database links, every linked read is refused, because Oracle resolves the account’s private links before the public links Bytebase synced. Run the query under the admin data source, or remove the private links from that account.

Max returned row count

SQL Editor can return at most 100,000 rows.

Max returned result size

The default query result size is 100 MB. You can change it under the Workspace settings.

Export data

Export re-runs your SQL statement against the database — it does not download the result set currently displayed in the tab. If the underlying data changed between the time you ran the query and the time you clicked Export, the exported rows will reflect the later state. To capture a specific point-in-time result set, copy the rows from the result panel or re-run the query immediately before exporting.The re-execution goes through the same row limit, data-source selection, and masking policy as the original query, so exported columns are masked if the policy is enforced.

If you have been granted export access, you can directly export query results in various formats.

Otherwise, you can request the exported data

EXPLAIN query

SQL Editor provides an Explain Query action that shows the execution plan of the selected statement without running it. Access it from the right-click menu or with ⌘ + E. On BigQuery the action is Dry Run Query. The plan opens in the result pane. For PostgreSQL, SQL Server, and Spanner it is a visual plan with Text, Diagram, Grid, and Summary tabs, plus a Query tab with the statement. Spanner plans carry no cost estimates, so they have no Summary tab. Other engines show the plan as text, or in the normal result grid when the engine returns a table, as MySQL does.

Query plan for a PostgreSQL join shown in the SQL Editor result pane with the Diagram tab selected, maximized

Click Maximize next to the result tabs to give the result pane the full editor height. Press Esc or click Restore to bring the editor back. Typing EXPLAIN yourself works too. On PostgreSQL, a plain EXPLAIN or EXPLAIN (FORMAT JSON) opens the same visual plan. EXPLAIN (FORMAT XML) and EXPLAIN (FORMAT YAML) show as text.

EXPLAIN ANALYZE executes the statement it plans. For a read, the plan shows as text, or as the visual plan with FORMAT JSON. For a write, SQL Editor runs the statement and shows the affected-row count, with no plan. It needs the permission of the statement inside it rather than bb.sql.explain: bb.sql.select for a read, and DML permission for a write. Explain Query refuses a statement that already starts with EXPLAIN ANALYZE.

Explain Query requires bb.sql.explain on the database. Through the API, QueryOption.explain_format selects TEXT, JSON, XML, or YAML. PostgreSQL accepts all four, SQL Server TEXT and XML, Spanner JSON, and every other engine with EXPLAIN support TEXT; a format the engine cannot produce returns INVALID_ARGUMENT.

Batch mode

You can batch query many databases having the same schema:

For each database, the query result will show up in its own tab:

Database Permissions

Data Masking

SQL Editor

Autocomplete