Skip to content

docs: update export related docs #913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tianzhou merged 14 commits into from
Oct 14, 2025
Merged

docs: update export related docs #913

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
53384dc
update export changelog
adela-bytebase Oct 14, 2025
c0474ec
update roles with changes to export
adela-bytebase Oct 14, 2025
2c007e7
update
adela-bytebase Oct 14, 2025
ea3a150
update
adela-bytebase Oct 14, 2025
0568642
update
adela-bytebase Oct 14, 2025
481e412
update export
adela-bytebase Oct 14, 2025
26fd2b5
update
adela-bytebase Oct 14, 2025
865dcfb
update environment policies
adela-bytebase Oct 14, 2025
6ec20b6
Update mintlify/security/database-permission/overview.mdx
adela-bytebase Oct 14, 2025
404e784
update
adela-bytebase Oct 14, 2025
c8b2255
update
adela-bytebase Oct 14, 2025
7685a92
update
adela-bytebase Oct 14, 2025
2cbce7c
update changelog
adela-bytebase Oct 14, 2025
c7cdf8a
update
adela-bytebase Oct 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 39 additions & 41 deletions mintlify/administration/roles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,9 @@ Bytebase provides two types of roles:

**Project roles:**
- `Project Owner` - Full control over project resources
- `Project Developer` - Create and manage database changes
- `Project Developer` - Create and manage database changes; create Export issues for one-time exports
- `Project Releaser` - Approve and release changes
- `SQL Editor User` - Query databases (formerly `Project Querier`)
- `Project Exporter` - Export data
- `SQL Editor User` (formerly `Project Querier`) - Query in SQL Editor; export results directly from the Editor
- `Project Viewer` - Read-only access

#### Custom Roles
Expand Down Expand Up @@ -130,23 +129,22 @@ By default, the first registered user is granted the `Admin` role, all following

Any user can create project. By default, the project creator is granted the `Project Owner` role. `Workspace DBA` and `Workspace Admin` assume the `Project Owner` role for all projects.

| Project Permission | SQL Editor User | Project Exporter | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ---------------------------- | --------------- | ---------------- | ----------------- | ------------- | ------------- | --------------- |
| Change project role | | | | ✔️ | ✔️ | ✔️ |
| Edit project | | | | ✔️ | ✔️ | ✔️ |
| Archive project | | | | ✔️ | ✔️ | ✔️ |
| Configure UI/GitOps workflow | | | | ✔️ | ✔️ | ✔️ |
| Project Permission | SQL Editor User | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ---------------------------- | --------------- | ----------------- | ------------- | ------------- | --------------- |
| Change project role | | | ✔️ | ✔️ | ✔️ |
| Edit project | | | ✔️ | ✔️ | ✔️ |
| Archive project | | | ✔️ | ✔️ | ✔️ |
| Configure UI/GitOps workflow | | | ✔️ | ✔️ | ✔️ |

### Database Permissions

Bytebase does not define database specific roles. Whether a user can perform certain action to the database is based on the user's Workspace role and the role of the project owning the database.

| Database Permission | SQL Editor User | Project Exporter | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ------------------- | --------------- | ---------------- | ----------------- | ------------- | ------------- | --------------- |
| Query | ✔️ | | | ✔️ | ✔️ | ✔️ |
| Export | | ✔️ | | ✔️ | ✔️ | ✔️ |
| Edit database label | | | | ✔️ | ✔️ | ✔️ |
| Transfer database | | | | ✔️ | ✔️ | ✔️ |
| Database Permission | SQL Editor User | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ------------------- | --------------- | ----------------- | ------------- | ------------- | --------------- |
| Query | ✔️ | | ✔️ | ✔️ | ✔️ |
| Edit database label | | | ✔️ | ✔️ | ✔️ |
| Transfer database | | | ✔️ | ✔️ | ✔️ |

### Sheet Permissions

Expand All @@ -158,40 +156,40 @@ User can save sheets from [SQL Editor](/sql-editor/overview). A sheet always bel

#### Private Sheet

| Permission | Creator | SQL Editor User | Project Exporter | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ---------- | ------- | --------------- | ---------------- | ----------------- | ------------- | ------------- | --------------- |
| Star | ✔️ | | | | | | |
| Read | ✔️ | | | | | | |
| Write | ✔️ | | | | | | |
| Delete | ✔️ | | | | | | |
| Permission | Creator | SQL Editor User | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ---------- | ------- | --------------- | ----------------- | ------------- | ------------- | --------------- |
| Star | ✔️ | | | | | |
| Read | ✔️ | | | | | |
| Write | ✔️ | | | | | |
| Delete | ✔️ | | | | | |

#### Project Sheet

| Permission | Creator | SQL Editor User | Project Exporter | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ---------- | ------- | --------------- | ---------------- | ----------------- | ------------- | ------------- | --------------- |
| Star | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Read | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Write | ✔️ | | | | ✔️ | ✔️ | ✔️ |
| Delete | ✔️ | | | | ✔️ | ✔️ | ✔️ |
| Permission | Creator | SQL Editor User | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ---------- | ------- | --------------- | ----------------- | ------------- | ------------- | --------------- |
| Star | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Read | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Write | ✔️ | | | ✔️ | ✔️ | ✔️ |
| Delete | ✔️ | | | ✔️ | ✔️ | ✔️ |

#### Public Sheet

| Permission | Creator | SQL Editor User | Project Exporter | Project Developer | Project Owner | Others |
| ---------- | ------- | --------------- | ---------------- | ----------------- | ------------- | ------ |
| Star | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Read | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Write | ✔️ | | | | ✔️ | |
| Delete | ✔️ | | | | ✔️ | |
| Permission | Creator | SQL Editor User | Project Developer | Project Owner | Others |
| ---------- | ------- | --------------- | ----------------- | ------------- | ------ |
| Star | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Read | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Write | ✔️ | | | ✔️ | |
| Delete | ✔️ | | | ✔️ | |

### Issue Permissions

| Issue Permission | Assignee | Creator | SQL Editor User | Project Exporter | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ------------------------- | -------- | ------- | --------------- | ---------------- | ----------------- | ------------- | ------------- | --------------- |
| Create issue | N/A | N/A | | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Change issue status | ✔️ | | | | | Depends\* | ✔️ | ✔️ |
| Edit name and description | ✔️ | ✔️ | | | | | ✔️ | ✔️ |
| Edit SQL Statement | | ✔️ | | | | | | |
| Subscribe/Unsubscribe | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Add comment | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Issue Permission | Assignee | Creator | SQL Editor User | Project Developer | Project Owner | Workspace DBA | Workspace Admin |
| ------------------------- | -------- | ------- | --------------- | ----------------- | ------------- | ------------- | --------------- |
| Create issue | N/A | N/A | | ✔️ | ✔️ | ✔️ | ✔️ |
| Change issue status | ✔️ | | | | Depends\* | ✔️ | ✔️ |
| Edit name and description | ✔️ | ✔️ | | | | ✔️ | ✔️ |
| Edit SQL Statement | | ✔️ | | | | | |
| Subscribe/Unsubscribe | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Add comment | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |

\* `Project Owner` can change issue status when the current active [Environment Rollout Policy](/change-database/environment-policy/rollout-policy) is set to **Require manual rolling out**.
15 changes: 5 additions & 10 deletions mintlify/change-database/environment-policy/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ Configure and manage your database environments including policies, permissions,

You can configure any color for an environment either by inputting in **HEX** tab or choosing one in the palette.

![env-color](/content/docs/administration/environment-policy/env-color.webp)

SQL Editor then displays the configured color tab.

![env-color-sql-editor](/content/docs/administration/environment-policy/env-color-sql-editor.webp)
Expand All @@ -20,8 +18,6 @@ SQL Editor then displays the configured color tab.

Once you mark an environment as a production environment, Bytebase will attach a shield icon 🛡️ besides the environment name.

![tier-envs](/content/docs/administration/environment-policy/tier-envs.webp)

## Rollout policy

Control who can deploy changes to each environment and whether deployments happen automatically or require manual approval.
Expand All @@ -45,15 +41,14 @@ Configure environment-specific restrictions for SQL Editor operations:
- **Restrict data copying in SQL Editor**: Only Workspace Admins and DBAs can copy data from query results
- **Restrict querying admin data sources**: Limit access to administrative data sources in the SQL Editor

## Statement execution mode
## Statement execution

Even if you have `sql.dml` and `sql.ddl` [database permissions](/security/database-permission/overview/), you can only run read-only statements such as `SELECT` in SQL Editor by default. If you attempt to run mutation DML or DDL, it will prompt you to submit an issue.
By default, users with **SQL Editor User** role or `sql.dml` and `sql.ddl` [database permissions](/security/database-permission/overview/) can execute DDL and DML statements directly in SQL Editor. To restrict statement execution to SELECT-only queries and require users to create issues for data modifications, turn on the following **statement execution** settings (**Default**: `off`/`off`):

![prompt-issue](/content/docs/administration/environment-policy/prompt-issue.webp)
- Disallow running DDL statements in the SQL editor
- Disallow running data-modifying DML statements in the SQL Editor

If you want to run those statements directly in SQL Editor, you need to turn on the **statement execution** setting.

![statement-execution](/content/docs/administration/environment-policy/statement-execution.webp)
![prompt-issue](/content/docs/administration/environment-policy/prompt-issue.webp)

## Delete an environment

Expand Down
4 changes: 2 additions & 2 deletions mintlify/changelog/bytebase-3-11-0.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ import InstallUpgrade from '/snippets/install/install-upgrade.mdx';

- **Environment rollout policy update**
- **Issue Creators** and **Last Issue Approvers** can no longer roll out issues. Manual rollouts now require specifying workspace/project roles or users with the `bb.taskRuns.create` permission.
- The force rollout mechanism has been replaced by configurable rollout requirements:
- The force rollout mechanism has been replaced by [configurable rollout requirements](/change-database/environment-policy/rollout-policy#configurable-rollout-requirements):
- **Require Issue Approval** – ensures issues must be approved before rollout can proceed (default: enabled).
- **Plan Check Enforcement** – controls rollout behavior based on plan check results (default: block on errors only).

- Deprecate `bb.sql.export` permission and `roles/projectExporter` role.
- Deprecate `bb.sql.export` permission and `roles/projectExporter` role. It’s merged into `SQL Editor User` role, which now can export directly in SQL Editor; Developer can still create Export issue as before.
- Deprecate `request.row_limit` in the project IAM policy. Use `maximum_result_rows` in `QueryDataPolicy` instead.

- **API**
Expand Down
Binary file removed mintlify/content/docs/administration/environment-policy/env-color.webp
View file
Open in desktop
Binary file not shown.
Binary file removed mintlify/content/docs/administration/environment-policy/statement-execution.webp
View file
Open in desktop
Binary file not shown.
Binary file removed mintlify/content/docs/administration/environment-policy/tier-envs.webp
View file
Open in desktop
Binary file not shown.
Binary file removed ...content/docs/security/database-permission/export/sql-editor-request-export.webp
View file
Open in desktop
Binary file not shown.
7 changes: 1 addition & 6 deletions mintlify/onboarding/sql-editor-data-access-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,10 @@ the project.

<Tip>

`SQL Editor User` is a built-in role that allows users to run `EXPLAIN` and `SELECT`. If you want to allow users
to run `EXPLAIN` only, you can create a [custom role](/administration/roles) with `bb.sql.explain` permission.
`SQL Editor User` is a built-in role that allows users to run `EXPLAIN`, `SELECT` and export data. If you want to allow users to run `EXPLAIN` only, you can create a [custom role](/administration/roles) with `bb.sql.explain` permission.

</Tip>

### Fine-Grained Export

Export is a special case of query access. You need to grant the `Project Exporter` role to the user inside the project.

### Just-In-Time Access

You may disallow any production access by default and only allow temporary access on-demand. Users can this request temporary access
Expand Down
25 changes: 9 additions & 16 deletions mintlify/security/database-permission/export.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,21 @@
---
title: One-Time Export
title: Export Data
---

Except for requesting or being assigned `Project Exporter` role to export data repeatedly, you can also request a one-time export in **Export Center**.
There are two ways to export data:

## One-time Export Request

Approval flow matches the `Export Data` in [custom approval](/change-database/approval/) if configured.
- As **SQL Editor User**, you can export directly from SQL Editor.
- As **Project Developer**, you can request a one-time export in **Export Center**.

### Request from SQL Editor
## Export directly from SQL Editor

Data can be exported directly from the SQL Editor result panel if you have the export permission for the data.
As **SQL Editor User**, after you run a query, you can export the result by clicking **Export** button. The exported data still respects the masking policy to mask exported columns.

![sql-editor](/content/docs/security/database-permission/export/sql-editor.webp)

Without the export permission, you can request a one-time export via **Request Export**.

![sql-editor-request-export](/content/docs/security/database-permission/export/sql-editor-request-export.webp)

You will be redirected to an issue page. **Create** the issue. After approval, you'll be able to export the data one time.

![sql-editor-export](/content/docs/security/database-permission/export/sql-editor-export.webp)
## One-time Export Request

### Request from Export Center
As **Project Developer**, you can request a one-time export in **Export Center**. Approval flow matches the `Export Data` in [custom approval](/change-database/approval/) if configured.

Enter **Export Center** within a project, where you **Request Export**, select a database and click **Next**.

Expand All @@ -32,7 +25,7 @@ You'll be creating an issue. Enable **Encrypt** and set **Password** if needed,

![export-preview](/content/docs/security/database-permission/export/export-preview.webp)

After approval, you can click **Export** to download the exported file _once_.
After approval, you can click **Export** to download the exported file **unlimited times** within 24 hours.

![export](/content/docs/security/database-permission/export/export.webp)

Expand Down
Loading