Database governance built for humans and agents — controlling changes and access across every major database.
Restore bb.sql.export and remove disable_export
- Status: proposal for review
- Date: 2026-10-28
- Tracking issue: TBD
- Decision record: ADR 0006
- Line references point at
afffc8914a.
Decision
- Who may export is controlled by
bb.sql.exportalone.SQLService.Exportrequires it on the data it reads, checked with the same database, schema, table and expiration conditions asbb.sql.select. Export does not also requirebb.sql.select. - A user holds
bb.sql.exportthrough a role binding (standing) or through an active access grant withexport: truefor the exact query (temporary, approved). disable_exportis removed. The workspace setting disappears from the UI, the server stops storing the value, and the migration strips it from stored policies. The v1 field stays, deprecated, until a later release deletes it: reads returnfalse, and writes that set it totrueare rejected with a message that points to export roles.- A new built-in role, SQL Editor Exporter (
roles/sqlEditorExporter), holds SQL Editor Read User's permissions plusbb.sql.export. Workspace Admin, Workspace DBA and Project Owner also holdbb.sql.export. SQL Editor User and SQL Editor Read User do not. - The server enforces the permission for every caller: console, API and MCP.
- A one-time migration keeps export for users who export today through SQL Editor User or SQL
Editor Read User. Workspaces that allow export without approval give those users a SQL Editor
Exporter binding. Workspaces that require approval get no new standing export, so approved
access grants stay the only export path for ordinary users. The migration does not change
custom roles: holders of custom roles with
bb.sql.selectlose export until an administrator addsbb.sql.exportto the role.
Background
Bytebase removed bb.sql.export and roles/projectExporter in #17470. Today:
Exportis gated at the interceptor bybb.databases.getonly (proto/v1/v1/sql_service.proto:89). Past that, it runs the same per-statement check asQuery(backend/api/v1/sql_service.go:1629), so anyone who can run aSELECTcan export its result.disable_exportis a workspace-level flag, labeled "Allow data export without approval" in workspace settings. Turning that toggle off sets the flag. With the flag set, the SQL Editor hides the Export button unless the user holds an active export grant for the query, and offers "Request export" instead (frontend/src/modules/sql-editor/components/ResultView/ResultView.tsx:154,ResultPanel/BatchQuerySelect.tsx:167). There is no administrator exemption. The flag therefore means "export requires approval", and it is only a UI rule: the backend never reads it, so the API and MCP export with it set. The 2026-09 API audit lists this as X1 (docs/design/v1-api-audit-2026-09.md:116).- An access grant with
export: trueskips the role check on its target databases (sql_service.go:1176,:1564). Theexportfield exists because there was no export permission for the grant to stand in for.
An administrator therefore cannot say "this person may query but not export". The one export
control that exists applies to every user at once and is not enforced. Once bb.sql.export
exists, "export requires approval" is expressed by assigning roles without it, and the flag has
nothing left to decide.
Goals
- Control who may export per person and per database, schema and table, like query access.
- Enforce it on the server for every caller.
- Keep one control for export: role bindings and access grants, with no workspace flag that overlaps them.
- On upgrade, keep export for users who export through SQL Editor User or SQL Editor Read User:
standing export where the workspace allows export without approval, and approval-only export
where it requires approval. Holders of custom roles with
bb.sql.selectlose export until an administrator addsbb.sql.exportto the role.
Non-goals
- A workspace switch that turns off all export. If customers ask for one, it gets a new field;
disable_exportis not reused. - Non-local export destinations and their settings, such as
disable_local_export. - Per-export row limits as a role condition (
request.row_limitin the 2025 model). Row and size caps stay inQueryDataPolicy. - Changing how
Queryis authorized. - Downgrading after the migration. It is not supported.
Product behavior
Who can export
| Role | bb.sql.export |
Reason |
|---|---|---|
| Workspace Admin, Workspace DBA, Project Owner | Yes | All three hold bb.projects.setIamPolicy and could grant it to themselves. Withholding it would be cosmetic. |
| SQL Editor User, SQL Editor Read User | No | Export becomes an explicit grant. |
| SQL Editor Exporter (new) | Yes | "Query databases and export results, without DDL or DML access." |
| Custom roles | As configured | The migration does not change custom roles. |
SQL Editor Exporter can be stacked on SQL Editor User to add export to someone who can write.
A custom role with bb.sql.export but no bb.sql.select is valid. Its holder can export through
the API or MCP but not from the SQL Editor, where Export works on a query result.
To require approval for export, an administrator assigns roles without bb.sql.export. Users
then request export through an access grant in projects with just-in-time access enabled
(Enterprise plan).
Removing the workspace setting
- The workspace SQL Editor setting "Allow data export without approval" is removed.
GetPolicyreturnsdisable_export = falsefor every query data policy.UpdatePolicyacceptsdisable_export = falseand ignores it. It rejectstruewithINVALID_ARGUMENT: "disable_export is removed. Export requires the bb.sql.export permission; to require approval for export, assign roles without it." A stale Terraform config or script therefore fails at apply with instructions, instead of showing a diff that never converges.
SQL Editor
Holds bb.sql.export (role or matching grant) |
Project allows just-in-time access | Result panel shows |
|---|---|---|
| Yes | Either | Export |
| No | Yes | Request export |
| No | No | Neither |
The SQL Editor checks bb.sql.export per database, including database-scoped binding conditions.
Schema and table conditions are checked only by the server, and a denied export shows its error.
Access grants
An approved grant with export: true gives bb.sql.export for one read-only query on its target
databases until it expires. Requests follow existing rules:
- Creating a request needs
bb.accessGrants.create(held by Workspace Member, so every user) and a project with just-in-time access enabled. - Approval rules can route export requests with
request.data_export. - Activating a grant directly needs
bb.accessGrants.activate. Only Admin, DBA and Project Owner hold it, and all three already holdbb.sql.export.
Assigning roles
- Member forms offer database scoping for roles with
bb.sql.export, as they do forbb.sql.select. - Workspace setup gives invitees SQL Editor Exporter instead of SQL Editor Read User, alongside
Project Developer, so invitees in new workspaces export as they do today
(
frontend/src/routes/auth/workspace-setup/finish.ts:90). - "Request query" keeps requesting SQL Editor Read User.
Technical design
Permission and roles
- Add
SQLExport = "bb.sql.export"tobackend/common/permission/permission.goandpermission.yaml. Custom-role validation reads the YAML, soCreateRoleandUpdateRoleaccept it with no further change. - In
backend/store/predefined_roles.go, addSQLExportto Workspace Admin, Workspace DBA and Project Owner, and addSQLEditorExporterRole = "sqlEditorExporter". - The frontend permission union is generated from the YAML
(
frontend/src/types/iam/permission-generated.ts).
Export check
The per-statement access check runs with an export flag, captured in the accessCheckWithGrant
closure so accessCheckFunc keeps its signature.
| Statement type | Query (unchanged) |
Export |
|---|---|---|
| Select, including column-level checks | bb.sql.select |
bb.sql.export |
Info schema (SHOW and similar) |
bb.sql.info |
bb.sql.export |
| Unknown on engines without the new ACL (select fallback) | bb.sql.select |
bb.sql.export |
No spans (engines without a span extractor, sql_service.go:1613) |
bb.sql.select |
bb.sql.export |
| Explain | bb.sql.explain |
bb.sql.explain |
| DML, DDL | bb.sql.dml, bb.sql.ddl |
Unchanged |
Explain keeps bb.sql.explain because its output is a plan, not table data, and grants still do
not cover it. EXPLAIN ANALYZE checks its statement, so its reads require bb.sql.export.
On engines that classify statements, DML and DDL keep their own permissions, so Export does
not become a way to change data. This matters on MySQL, where Export skips read-only
validation (sql_service.go:1180). Engines with neither statement classification nor a
validator are an existing exception: on Databricks, a write produces no spans and passes the
database-level select check through both Query and Export today
(docs/design/mcp-capability-ladder.md:160). Under this design Export checks bb.sql.export
there, so an export-only custom role can run such a write through Export, as a select role can
today. For an MCP session, Export refuses every statement Bytebase cannot show is a read,
Databricks included (mcp_sql_write.go). The console keeps the exception.
The CEL input is unchanged: database, schema and table per source column (sql_service.go:1756),
and the database-level fallback. hasDatabaseAccessRights strips the environment condition for
non-DDL/DML permissions today, and bb.sql.export is treated the same way.
An export grant satisfies bb.sql.export on its target databases. It is looked up with
requireExport=true, as today. The code should express this as "the grant satisfies
bb.sql.export" rather than "the grant skips the role check", so a later export rule applies to
grant holders too.
API and docs
proto/v1/v1/org_policy_service.proto: markdisable_export[deprecated = true]with the comment "Deprecated: export is controlled by the bb.sql.export permission. Always false; setting it to true is rejected."convertToQueryDataPolicyPayloadrejectstrueand drops the value. Delete the field in a later release, after the provider stops sending it.proto/store/store/policy.proto: deletedisable_exportand reserve field 2 and its name. RemoveDisableExportfromstore.EffectiveQueryDataPolicyand the v1 converter.proto/v1/v1/sql_service.proto: document thatExportrequiresbb.sql.export.proto/v1/v1/access_grant_service.proto: theexportfield "grantsbb.sql.exportfor this query until the grant expires."proto/v1/v1/iam_policy.proto: list export in the roles thatresource.*conditions apply to.- Remove the stale
roles/EXPORTERexamples inissue_service.protoandstore/issue.proto, and the "EXPORTER role" comment atsql_service.go:1227. - Mark X1 resolved and update line 680 of
docs/design/v1-api-audit-2026-09.md. Exportstays a WRITE-class MCP method. The export row indocs/design/mcp-capability-ladder.mdshould say the user's ownbb.sql.exportapplies.
Frontend
- Export gates in
ResultView.tsxandBatchQuerySelect.tsxfollow the SQL Editor table above. Standing export is decided per database withisDatabaseV1Queryable(database, ["bb.sql.export"]), anduseExportGrantBypassruns for the databases that lack it, instead of when the flag is set. - Remove the toggle from
routes/workspace/general/SQLEditorSection.tsx, its "data-export" strings in all five locales (frontend/src/locales/en-US.json), and its tests. - Remove
disableExportfromuseSQLEditorQueryDataPolicy(modules/sql-editor/hooks/useSQLEditorState.ts). - Add the new role to
types/iam/role.ts,lib/role.tsandutils/role.ts, with strings in all five locales. - Add
roles/sqlEditorExporterto the role table in the agent's grant-permission skill (modules/agent/logic/skills/grantPermission.ts), so the agent can grant export. - Add
bb.sql.exporttoroleHasDatabaseLimitationinlib/project-member/utils.ts. - Replace SQL Editor Read User with SQL Editor Exporter in
INVITEE_PROJECT_ROLES(routes/auth/workspace-setup/finish.ts).
Migration
One SQL file, backend/migrator/migration/3.25/0000##sql_export_permission.sql; 3.24.0 shipped
with 3.24/0000 to 0002. Update TestLatestVersion. LATEST.sql does not change because
role permissions, IAM bindings and policies are JSONB. The migrator runs the file in one
transaction (backend/migrator/migrator.go:227).
A workspace is approval-only when its workspace-level QUERY_DATA policy stores
disableExport = true, whether or not it is enforced: GetPolicy ignores enforce
(backend/store/policy.go:751), so the SQL Editor honored the value either way. Every other
workspace is export-enabled.
Steps:
- Fail if a custom role already uses the id
sqlEditorExporter. Role ids are unique across workspaces (LATEST.sql:98), and built-in roles shadow custom roles with the same id (backend/store/role.go:152), so continuing would silently change that role's meaning. The new server cannot start until the conflict is gone, and a role id cannot be renamed, so the error message gives the fix: on the previous version, create a replacement custom role, move its bindings, and delete the conflicting role. Check Cloud data for the id before release. - In export-enabled workspaces, for every workspace or project IAM binding of SQL Editor User or SQL Editor Read User, add a SQL Editor Exporter binding with the same members and condition.
- Remove the
disableExportkey from everyQUERY_DATApolicy, at workspace and project level, enforced or not.
Approval-only workspaces get no new bindings. Ordinary users there keep exporting only through approved grants. Custom roles are not changed in any workspace. Built-in role definitions live in Go and need no migration.
DO $$
DECLARE
conflicting_workspace text;
BEGIN
SELECT workspace INTO conflicting_workspace FROM role WHERE resource_id = 'sqlEditorExporter';
IF FOUND THEN
RAISE EXCEPTION 'custom role "sqlEditorExporter" in workspace "%" conflicts with a new built-in role. On the previous Bytebase version, create a replacement custom role, move its bindings, and delete "sqlEditorExporter".', conflicting_workspace;
END IF;
END $$;
CREATE TEMP TABLE approval_only_workspace ON COMMIT DROP AS
SELECT workspace FROM policy
WHERE resource_type = 'WORKSPACE' AND type = 'QUERY_DATA'
AND COALESCE((payload ->> 'disableExport')::boolean, false);
WITH added AS (
SELECT p.workspace, p.resource_type, p.resource,
jsonb_agg(jsonb_set(b, '{role}', '"roles/sqlEditorExporter"') ORDER BY ord) AS bindings
FROM policy p,
jsonb_array_elements(p.payload -> 'bindings') WITH ORDINALITY AS t(b, ord)
WHERE p.type = 'IAM'
AND p.resource_type IN ('WORKSPACE', 'PROJECT')
AND p.workspace NOT IN (SELECT workspace FROM approval_only_workspace)
AND b ->> 'role' IN ('roles/sqlEditorUser', 'roles/sqlEditorReadUser')
GROUP BY p.workspace, p.resource_type, p.resource
)
UPDATE policy p
SET payload = jsonb_set(p.payload, '{bindings}', (p.payload -> 'bindings') || added.bindings)
FROM added
WHERE p.type = 'IAM' AND p.workspace = added.workspace
AND p.resource_type = added.resource_type AND p.resource = added.resource;
UPDATE policy
SET payload = payload - 'disableExport'
WHERE type = 'QUERY_DATA' AND payload ? 'disableExport';
Copying the binding and changing only the role carries members (users, groups, allUsers) and
the condition over exactly, including database, schema, table and expiration scope. A member who
holds both SQL Editor roles receives two exporter bindings, which is harmless. Access grants and
approval rules are not touched.
Resulting behavior
| Who | Export-enabled workspace | Approval-only workspace |
|---|---|---|
| SQL Editor User, SQL Editor Read User | Export, through the added binding | Request export, then export after approval (unchanged)* |
Custom roles with bb.sql.select |
No export until an admin adds bb.sql.export to the role |
Request export (unchanged)* |
| Admin, DBA, Project Owner | Export | Export without a grant |
| Export grant holders | Export | Export (unchanged) |
| API and MCP callers | Same as the SQL Editor | Same as the SQL Editor |
* In projects with just-in-time access enabled (Enterprise plan). Elsewhere, Request export is not offered, as today.
Accepted behavior changes
- Workspace Admin, Workspace DBA and Project Owner hold
bb.sql.exportin every workspace. In export-enabled workspaces they could already export, so nothing changes. In approval-only workspaces they needed an approved grant, which they could approve themselves, and now export directly. The release note must state this. - In approval-only workspaces, API and MCP callers need
bb.sql.exportor a matching export grant, where before anyone with select could export. This closes X1. - In export-enabled workspaces, holders of custom roles with
bb.sql.selectlose export until an administrator addsbb.sql.exportto the role. The release note must state this. - The workspace export setting is gone. To stop a user exporting, remove export from their roles; to stop export through grants in a project, turn off just-in-time access there. The release note must state this.
- Writes that set
disable_export = trueare rejected. - Custom roles with
bb.sql.infoorbb.sql.explainbut notbb.sql.selectcould exportSHOWoutput before and cannot after. Giving thembb.sql.exportwould grant export of all data, which is broader than what they had. - New SQL Editor User or Read User assignments, and role requests approved after the upgrade, do not include export. Assign SQL Editor Exporter as well.
Terraform and compatibility
The Terraform provider manages the whole IAM policy of a parent through bytebase_iam_policy,
custom roles and their permission sets through bytebase_role, and disable_export through
bytebase_policy. The migration changes IAM policies and query data policies, so
bytebase_iam_policy and bytebase_policy can drift. It does not change custom roles.
- IAM drift (export-enabled workspaces).
terraform planwants to remove the added exporter bindings. Applying it takes export away from SQL Editor users. This failure removes access and never adds it, which is why the migration adds bindings instead of rewriting roles. disable_export(approval-only workspaces). A config that setsdisable_export = trueshows afalse → truechange, and applying it fails with the rejection message. A config that setsfalsekeeps applying until the provider drops the attribute.- Order of operations. A config cannot reference
roles/sqlEditorExporterbefore the server knows the role.
Provider release, shipped with the server release:
- Mark
disable_exportdeprecated in the provider schema, stop sending it, and document its removal. - Document the paired binding pattern below and remove the obsolete export row-limit condition.
- Confirm that role names are not validated against a fixed list.
Upgrade runbook for Terraform users:
- Pause automatic
terraform apply. - Upgrade Bytebase.
- Run
terraform plan. - In export-enabled workspaces, add every exporter binding the plan wants to remove: for each
SQL Editor binding that should keep export, a binding with the same members and condition and
role = "roles/sqlEditorExporter". - Remove
disable_exportfrom everybytebase_policyconfig. - Resume automatic apply when the plan is clean.
binding {
role = "roles/sqlEditorUser"
members = ["group:[email protected]"]
condition { database = "instances/prod/databases/app" }
}
binding {
role = "roles/sqlEditorExporter"
members = ["group:[email protected]"]
condition { database = "instances/prod/databases/app" }
}
Testing
- Migration (
backend/migrator/migration_test.go): one export-enabled and one approval-only workspace, each with a custom role with and withoutbb.sql.select, a conditioned SQL Editor User binding, a group SQL Editor Read User binding, and workspace and project IAM policies. Include a third workspace with a non-enforced disabled policy, and a project-level query data policy that storesdisableExport. Assert exact payloads: the approval-only workspace has no new bindings; the export-enabled workspace has the added bindings; the third workspace is treated as approval-only; every custom role, with or withoutbb.sql.select, is unchanged in every workspace; no query data policy keeps adisableExportkey, their other fields andenforceare unchanged. Assert that the id collision raises. - Export authorization (
backend/api/v1):- A select-only user cannot export.
- A user with only
bb.sql.export, scoped to one table, exports that table, is refused on another table, and cannotQuery. - An export grant allows export without the permission.
- A role with
bb.sql.exportbut nobb.sql.dmlcannot run DML throughExporton MySQL. Queryis unaffected.
- Policy API (
backend/api/v1):UpdatePolicyrejectsdisable_export = trueand acceptsfalse;GetPolicyreturnsfalse. - Roles (
backend/store): the new built-in role exists and its permissions are valid. - Frontend:
ResultView,BatchQuerySelect,useExportGrantBypass,RequestExportButton,SQLEditorSection, the project-member utils and workspace setup.ResultView.test.tsxmocks every permission check as false today, so its cases need updating. - Provider: a migrated binding round-trips through
bytebase_iam_policy, and its CEL condition parses back into the samedatabase,schemaandtablesfields.
Alternatives considered
Keep disable_export as a switch that turns off all export
The field would keep its name and change meaning from "export requires approval" to "no export
for anyone", including administrators and grant holders, with per-destination settings added
beside it later. This keeps a one-click stop for all export. It also gives export two controls
whose overlap administrators must reason about, and it changes what an existing field means: a
stale config or script that writes true, meaning "approval required" before the upgrade, would
silently stop all export after it. A kill switch can come later as a new field if customers ask.
Enforce disable_export on the server with its current meaning
With the flag set, only grant holders could export, for every caller. This closes X1 without a migration. It keeps a workspace-wide rule that decides who may export beside the role bindings that also decide it, so "can this person export" would depend on both, and it still could not express "this person may query but not export" in a workspace that allows export.
Ignore writes of disable_export = true
Accepting and dropping the value keeps old configs applying. terraform plan would then show a
false → true change on every run, and the administrator is never told the setting is gone.
Give bb.sql.export in every workspace
The migration could add exporter bindings in approval-only workspaces too. That would hand standing export to every SQL Editor user in workspaces that chose to require approval.
Add bb.sql.export to custom roles with select
This keeps export for holders of custom roles in export-enabled workspaces. It also rewrites
roles that administrators own, often through Terraform bytebase_role, whose next plan would
want to undo the change.
Add an Exporter binding beside custom-role bindings
This keeps export without touching the roles. It also grants the rest of SQL Editor Exporter's permissions (database sync, IAM policy read, explain, info, saved queries, database groups and catalogs), which a narrow custom role may not include.
Require bb.sql.select and bb.sql.export
Export would only narrow select, so "who can read this table" stays one question. We chose export
alone because it gives administrators one permission to reason about for export, and it matches
the 2025 model. The cost is that bb.sql.export is itself a read grant.
Remove export from access grants
Users who need export would request SQL Editor Exporter through role requests, so bindings alone
answer who can export. An approved role covers every query in its scope rather than one, which
is broader than today's per-query grant. It also removes the "Request export" flow, which is the
only export path in approval-only workspaces, and empties request.data_export approval rules.
Swap roles, or create per-workspace role copies
Built-in roles carry meaning beyond their permissions. Approval flows route to
roles/projectOwner by name (backend/store/workspace.go:128), Workspace Admin lookup protects the
last admin (backend/api/v1/user_service.go:495), and "Request query" asks for a built-in role by
name. Copies would drift from the built-in definitions and require the custom-roles license. A
Terraform apply would also revert a swap.
Bring back roles/projectExporter
Customers may have created a custom role with that id since 2025, and a built-in role would shadow it. A new id also avoids confusion with the 2025 role, whose permission set differs from SQL Editor Exporter.
Open items
- Cloud id check. Confirm before release that no Cloud workspace has a custom role with the
id
sqlEditorExporter. - Provider role names. Confirm that the provider does not validate role names against a fixed list.
- Opting out of export requests. If a customer wants grants for query but not export, add a project setting such as "allow export in access grant requests". Not planned until asked.