What an audit payload may carry for a field. One enum rather than a bool per
behavior, because a field has exactly one classification.
| Name | Number | Description |
| AUDIT_BEHAVIOR_UNSPECIFIED | 0 | Recorded as sent. This is a denylist default, so an unannotated secret is written; the inventory lint turns that into a build failure. |
| SENSITIVE | 1 | A credential. It must not reach an audit payload, and the API may return it only on the response that mints it — never on a read path. |
| OMIT | 2 | Must not be recorded, for any reason other than being a credential: unbounded bodies, base64 blobs, bearer capabilities, and personal data. Unlike SENSITIVE it says nothing about the API contract. |
Authorization method for RPC calls.
| Name | Number | Description |
| AUTH_METHOD_UNSPECIFIED | 0 | Unspecified authorization method. |
| IAM | 1 | Standard IAM authorization check on organizational resources. |
| CUSTOM | 2 | Custom authorization logic. |
Why an MCP session may not call an RPC. The mechanism, not the wording: each
value names what its methods actually do, and the serving side turns that
into a sentence. A denial whose stated reason has drifted from the mechanism
is worse than a bare refusal, because it is the thing the next reader trusts
— so a method changing what it does changes its reason here.
One enum covers both refused classes, and every value belongs to exactly one
of them: values 1-8 name a mechanism that breaks the MCP boundary, which is
what FORBIDDEN means, and values 9-14 name a scope decision this phase took,
which is what EXCLUDED means. The distinction is real and lives on the class
annotation — a FORBIDDEN mechanism is a durable never, an EXCLUDED scope
decision is what a future admin-capable ceiling would argue with, one
population at a time. Splitting it across two enums as well only made the
nonsense states representable: a method could carry both, or carry the kind
that contradicts its class. Neither is expressible now, and the one check
left — the reason belongs to the class it is used on — is a table the gate
already keeps for the wording.
| Name | Number | Description |
| MCP_DENIAL_REASON_UNSPECIFIED | 0 | No reason recorded. The method is still denied — mcp_method_class is what enforces — and the denial falls back to generic wording. CI rejects this on a method classified FORBIDDEN or EXCLUDED. |
| MINTS_CREDENTIAL | 1 | Puts a token for the caller's own principal in the response body. |
| RESETS_CREDENTIAL | 2 | Drives the out-of-band reset flow that sets or delivers the secret a login or a credential change accepts. |
| TAKES_OVER_ACCOUNT | 3 | Rewrites an account's own credentials, which would let the session log in as that account. |
| ENDS_SESSION | 4 | Destroys the human's own login session. |
| ENDS_MEMBERSHIP | 5 | Destroys the caller's own workspace membership and mints a plain workspace token on the way out. |
| MINTS_CREDENTIAL_FOR_OTHERS | 6 | Leaves someone holding a principal the caller is not — by issuing its credential, carrying an existing one out to a host the caller named, choosing what will later be trusted to mint one, or redirecting where one gets delivered. |
| REWRITES_SESSION_BOUNDARY | 7 | Rewrites the workspace configuration that governs the session making the call — the MCP switch itself, the sign-in and SSO settings, the mail relay that carries credential resets, and the AI endpoint the stored API key is sent to. A session that can widen its own ceiling is not bounded by it. |
| DRIVES_THE_APPROVAL_DECISION | 8 | Can let a change or an access request pass its approval without an approver deciding it: re-running the finding that sets the approval, which can clear the issue outright, or activating an access grant directly. |
| ADMINISTERS_THE_WORKSPACE | 9 | Administers the workspace rather than doing database work: identity, credentials, access control, governance policy, billing, workspace and instance configuration, project lifecycle, and the operator's own audit trail. |
| READS_OTHER_USERS_SQL | 10 | Returns SQL that other people wrote. The permission gating it reads as an ordinary list permission, so the exclusion is per method rather than per permission: these methods span the workspace or ignore the per-object sharing that keeps a saved query private. |
| OPENS_AN_ADMIN_CONNECTION | 11 | Opens an admin-credentialed connection to the customer's database and returns live session state from it — including other sessions' in-flight, unmasked SQL. It shares a plain read permission with sibling methods that only read Bytebase's own store. |
| SENDS_DATA_TO_A_THIRD_PARTY | 12 | Spends a stored workspace credential on an outbound call to a third party, which puts whatever the caller passes outside the product. |
| RETURNS_A_STORED_SECRET | 13 | Returns a stored secret in its response body today. These are ordinary reads that belong in a serving class on their merits, and each is here because of a leak that a redaction on the read path would close — the product already redacts the same values elsewhere. This reason is therefore the one that is meant to go away: fixing the leak moves the method to READ, as a reviewed widening, rather than leaving a quiet exposure the moment the ceiling starts serving. No method carries it. The three leaks it was written for — project webhook URLs, the MySQL-family grant text, and the MFA enrollment secrets — are redacted on the read path, and their eight methods are READ. The value stays because the category is real and the next read found leaking should carry it rather than an invented one, and because retiring an enum value costs a reserved number for nothing. |
| REDRAWS_GOVERNANCE_BOUNDARY | 14 | Changes which rules govern a database, or which databases a change that targets a database group runs on. Approval, SQL review and access rules key on a database's project and environment, and so do the masking rules that decide what a query returns. A database group selects databases by an expression that can read their environment and labels, and a change that targets a group runs on whichever databases the group selects when its rollout tasks are created. An agent that could redraw these would choose the checks on its own changes. |
Classification of an RPC for MCP (AI agent) sessions. The effective
authorization of an MCP session is this classification intersected with the
caller's own RBAC: it can only ever narrow what the human could do, never
widen it.
Every value is enforced, at the gate on the internal MCP chain. READ and
WRITE are the serving classes the workspace's MCP capability ceiling selects
between, EXCLUDED and FORBIDDEN are served by no ceiling, and an unclassified
method is refused rather than served. Annotating a method is therefore a
change to what an MCP session can reach, taking effect on the next request.
READ and WRITE methods are also disclosed to workspace admins, as capability
rows on the Access policy page, so annotating a method changes what the
product promises as well as what it serves.
| Name | Number | Description |
| MCP_METHOD_CLASS_UNSPECIFIED | 0 | Not yet classified, and refused. CI rejects this value on any v1 RPC, so it survives only inside a build that has not been linted: a new RPC is classified before it can ship, and one that somehow reaches an MCP session unclassified is denied rather than guessed at. |
| READ | 1 | Served to a read-only MCP session and above. |
| WRITE | 2 | Served to a read-write MCP session only. This is a serving mode, not a verb: a method that only reads still belongs here when a read-only session has no business calling it — taking a copy of data out of the product, or generating migration DDL from a schema the caller supplied. |
| FORBIDDEN | 3 | Never reachable by an MCP session, whatever the caller's own permissions are. These methods escape the MCP boundary rather than merely exercising a permission: a human with the permission uses the console; an agent acting for them does not get to. |
| EXCLUDED | 4 | Served by no MCP capability ceiling this phase ships, and not a durable never. These are workspace administration, the writes that change which rules govern a database, and the handful of methods that do something materially worse than the plain read permission they share suggests. The line against FORBIDDEN is reversibility. An admin-capable ceiling, if one is ever built, could legitimately serve an EXCLUDED method — that is a product decision nobody has made. It could never serve a FORBIDDEN one, because FORBIDDEN names a mechanism that breaks the MCP boundary itself. Keeping them apart is what stops a future widening from having to re-litigate the credential-minting set alongside the ordinary admin API. |
| Extension | Type | Base | Number | Description |
| audit_behavior | AuditBehavior | .google.protobuf.FieldOptions | 100010 | How the audit log treats this field. |
| allow_without_credential | bool | .google.protobuf.MethodOptions | 100000 | Whether the method allows access without authentication credentials. |
| audit | bool | .google.protobuf.MethodOptions | 100003 | Whether to audit calls to this method. |
| auth_method | AuthMethod | .google.protobuf.MethodOptions | 100002 | The authorization method to use for this RPC. |
| mcp_denial_reason | MCPDenialReason | .google.protobuf.MethodOptions | 100005 | Why an MCP session may not call the method. Meaningful only alongside mcp_method_class = FORBIDDEN or EXCLUDED, and required on both: the denial names it so the agent, and the operator reading the audit row, learn why rather than just that it was refused, and an exclusion whose reason nobody wrote down is one nobody can revisit. 100006 was mcp_exclusion_reason, folded into mcp_denial_reason above. Do not reuse the number: an extend block cannot carry a `reserved` statement, so this comment is the only marker, and a binary built before the merge reads 100006 as the old enum — giving that number a new meaning would let it read a confident wrong answer instead of nothing. |
| mcp_method_class | MCPMethodClass | .google.protobuf.MethodOptions | 100004 | How the method is classified for MCP (AI agent) sessions. |
| permission | string | .google.protobuf.MethodOptions | 100001 | The permission required to call this method. |
| Field | Type | Label | Description |
| name | string | The name of the access grant, generated by the server. Format: projects/{project}/accessGrants/{access_grant} The {access_grant} segment is a server-generated unique ID. |
|
| creator | string | The creator of the access grant, the caller who requested it. Format: users/{email} |
|
| status | AccessGrant.Status | The status of the access grant. An ACTIVE grant with `expire_time` in the past is effectively expired and no longer authorizes access. Use `expire_time` to determine whether an ACTIVE grant has expired. |
|
| expire_time | google.protobuf.Timestamp | The expiration time of the access grant. |
|
| ttl | google.protobuf.Duration | Input only. The time-to-live duration for the access grant. The server computes `expire_time` from this value at activation time. |
|
| issue | string | The issue associated with the access grant. Can be empty. Format: projects/{project}/issues/{issue} |
|
| targets | string | repeated | The target databases for this access grant. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
| query | string | The query permission granted. |
|
| unmask | bool | Whether the grant allows unmasking sensitive data. |
|
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
|
| reason | string |
|
|
| export | bool | Whether the grant allows exporting the query result. An active grant with export=true grants bb.sql.export for this query until the grant expires. |
|
| schema | string | The default schema to execute the query. |
|
| container | string | The container name to execute the query against, used for CosmosDB only. |
| Field | Type | Label | Description |
| name | string | The name of the access grant to activate. Format: projects/{project}/accessGrants/{access_grant} |
| Field | Type | Label | Description |
| parent | string | The parent project for the access grant. Format: projects/{project} |
|
| access_grant | AccessGrant | The access grant to create. |
| Field | Type | Label | Description |
| name | string | The name of the access grant to retrieve. Format: projects/{project}/accessGrants/{access_grant} |
| Field | Type | Label | Description |
| parent | string | The parent project of the access grants. Format: projects/{project} |
|
| page_size | int32 | The maximum number of access grants to return. |
|
| page_token | string | A page token from a previous ListAccessGrants call. |
|
| filter | string | Filter expression using AIP-160 syntax. Supported fields: - name: the fullname in "projects/{project}/accessGrants/{access_grant}" format, support "==" operator. - creator: the creator name in "users/{email}" format, support "==" operator. - status: the access status, support "==" and "in" operator. - issue: the access issue fullname, support "==" operator. - expire_time: the access expire time in "2006-01-02T15:04:05Z07:00" format, support ">=", ">", "<=" and "<" operator. - create_time: the access creation time in "2006-01-02T15:04:05Z07:00" format, support ">=", ">", "<=" and "<" operator. - query: the access query, support "==" and ".contains(xx)" operator. Equality trims only boundary ASCII space, tab, LF, CR, vertical tab, and form feed. - query_hash: supports "==" with a lowercase hexadecimal SHA-256 digest of the UTF-8 query after the same boundary trim. Internal whitespace and Unicode remain unchanged. - schema: execution schema, supports "=="; empty matches only empty or absent values. - container: execution container, supports "=="; empty matches only empty or absent values. - target: the target database fullname, support "==" operator. - unmask: whether the grant allows unmasking sensitive data, support "==" operator with a boolean literal. - export: whether the grant allows exporting the query result, support "==" operator with a boolean literal. Examples: - creator == "users/dev@example.com" - status == "ACTIVE" - status in ["ACTIVE", "PENDING"] - creator == "users/dev@example.com" && status == "ACTIVE" - issue == "projects/x/issues/123" - status == "ACTIVE" && expire_time > "2024-02-01T00:00:00Z" - target == "instances/sample/databases/employee" - unmask == true - export == true && status == "ACTIVE" |
|
| order_by | string | The order by of access grants. Support creator, expire_time, create_time. The default sorting order is ascending. For example: - order_by = "creator" - order_by = "expire_time desc" - order_by = "expire_time asc, create_time desc" |
| Field | Type | Label | Description |
| access_grants | AccessGrant | repeated | The access grants from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | The name of the access grant to revoke. Format: projects/{project}/accessGrants/{access_grant} |
| Field | Type | Label | Description |
| parent | string | The parent project to search in. Format: projects/{project} |
|
| page_size | int32 | The maximum number of access grants to return. |
|
| page_token | string | A page token from a previous SearchMyAccessGrants call. |
|
| filter | string | Check the filter field in the ListAccessGrantsRequest message. |
|
| order_by | string | Check the order_by field in the ListAccessGrantsRequest message. |
| Field | Type | Label | Description |
| access_grants | AccessGrant | repeated | The access grants from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
The status of the access grant.
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | |
| PENDING | 1 | The access grant is pending approval. |
| ACTIVE | 2 | The access grant is active. Check `expire_time` to determine whether the grant is still valid or has expired. |
| REVOKED | 3 | The access grant has been revoked. |
AccessGrantService manages temporary access grants within projects.
| Method Name | Request Type | Response Type | Description |
| GetAccessGrant | GetAccessGrantRequest | AccessGrant | Gets an access grant by name. |
| ListAccessGrants | ListAccessGrantsRequest | ListAccessGrantsResponse | Lists access grants in a project. |
| CreateAccessGrant | CreateAccessGrantRequest | AccessGrant | Creates an access grant. |
| ActivateAccessGrant | ActivateAccessGrantRequest | AccessGrant | Activates a pending access grant. |
| RevokeAccessGrant | RevokeAccessGrantRequest | AccessGrant | Revokes an active access grant. |
| SearchMyAccessGrants | SearchMyAccessGrantsRequest | SearchMyAccessGrantsResponse | Searches access grants created by the caller. |
| Method Name | Method | Pattern | Body |
| GetAccessGrant | GET | /v1/{name=projects/*/accessGrants/*} | |
| ListAccessGrants | GET | /v1/{parent=projects/*}/accessGrants | |
| CreateAccessGrant | POST | /v1/{parent=projects/*}/accessGrants | access_grant |
| ActivateAccessGrant | POST | /v1/{name=projects/*/accessGrants/*}:activate | * |
| RevokeAccessGrant | POST | /v1/{name=projects/*/accessGrants/*}:revoke | * |
| SearchMyAccessGrants | POST | /v1/{parent=projects/*}/accessGrants:searchMy | * |
PermissionDeniedDetail provides structured information about permission failures.
Used as error detail when returning CodePermissionDenied errors.
| Field | Type | Label | Description |
| method | string | The API method that was called. |
|
| required_permissions | string | repeated | The permissions required but not granted to the user. |
| resources | string | repeated | The resources the user was trying to access. |
Position in a text expressed as one-based line and one-based column.
We use 1-based numbering to match the majority of industry standards:
- Monaco Editor uses 1-based (https://microsoft.github.io/monaco-editor/typedoc/interfaces/IPosition.html)
- GitHub Actions uses 1-based (https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message)
- Most text editors display 1-based positions to users
Note: LSP uses 0-based (https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#position),
but we follow the canonical user-facing standards.
Handling unknown positions:
- If the entire position is unknown, leave this field as nil/undefined
- If only line is known, set line and leave column as 0 (e.g., line=5, column=0)
- If only column is known (rare), set column and leave line as 0
Frontends should check for nil/undefined/zero values and handle them appropriately.
| Field | Type | Label | Description |
| line | int32 | Line position in a text (one-based). First line of the text is line 1. A value of 0 indicates the line information is unknown. |
|
| column | int32 | Column position in a text (one-based). Column is measured in Unicode code points (characters/runes), not bytes or grapheme clusters. First character of the line is column 1. A value of 0 indicates the column information is unknown. Examples: - "SELECT * FROM t" - column 8 is '*' - "SELECT 你好 FROM t" - column 8 is '你' (even though it's at byte offset 7) - "SELECT 😀 FROM t" - column 8 is '😀' (even though it's 4 bytes in UTF-8) |
Range represents a span within a text or sequence.
Whether the indices are byte offsets or character indices depends on the context.
Check the documentation of the field using Range for specific semantics.
| Field | Type | Label | Description |
| start | int32 | Start index (inclusive). |
|
| end | int32 | End index (exclusive). |
Approval workflow status for an issue or a plan.
Lives at the top level so both plan_service.proto and issue_service.proto
can reference it without a circular import.
| Name | Number | Description |
| APPROVAL_STATUS_UNSPECIFIED | 0 | No approval workflow has started, including for a linked draft issue. |
| CHECKING | 1 | Approval checks are being evaluated. |
| PENDING | 2 | Approval is pending. |
| APPROVED | 3 | Issue has been approved. |
| REJECTED | 4 | Issue has been rejected. |
| SKIPPED | 5 | Approval was skipped. |
Database engine type.
| Name | Number | Description |
| ENGINE_UNSPECIFIED | 0 | Unspecified database engine. |
| CLICKHOUSE | 1 | ClickHouse columnar database. |
| MYSQL | 2 | MySQL relational database. |
| POSTGRES | 3 | PostgreSQL relational database. |
| SNOWFLAKE | 4 | Snowflake cloud data warehouse. |
| TIDB | 6 | TiDB distributed SQL database. |
| MONGODB | 7 | MongoDB document database. |
| REDIS | 8 | Redis key-value store. |
| ORACLE | 9 | Oracle relational database. |
| SPANNER | 10 | Google Cloud Spanner distributed database. |
| MSSQL | 11 | Microsoft SQL Server relational database. |
| REDSHIFT | 12 | Amazon Redshift data warehouse. |
| MARIADB | 13 | MariaDB relational database. |
| OCEANBASE | 14 | OceanBase distributed database. |
| STARROCKS | 15 | StarRocks analytics database. |
| DORIS | 16 | Apache Doris analytics database. |
| HIVE | 17 | Apache Hive data warehouse. |
| ELASTICSEARCH | 18 | Elasticsearch search engine. |
| BIGQUERY | 19 | Google BigQuery data warehouse. |
| DYNAMODB | 20 | Amazon DynamoDB NoSQL database. |
| DATABRICKS | 21 | Databricks lakehouse platform. |
| COCKROACHDB | 22 | CockroachDB distributed SQL database. |
| COSMOSDB | 23 | Azure Cosmos DB multi-model database. |
| TRINO | 24 | Trino distributed SQL query engine. |
| CASSANDRA | 25 | Apache Cassandra NoSQL database. |
Where an export goes. Values are added as destinations are supported.
| Name | Number | Description |
| EXPORT_DESTINATION_UNSPECIFIED | 0 | Treated as DOWNLOAD. |
| DOWNLOAD | 1 | Return the export in the response. |
| SHAREPOINT | 2 | Upload the export to the project's SharePoint export destination. |
Data export format.
| Name | Number | Description |
| FORMAT_UNSPECIFIED | 0 | Unspecified export format. |
| CSV | 1 | Comma-separated values format. |
| JSON | 2 | JavaScript Object Notation format. |
| SQL | 3 | SQL statements format. |
| XLSX | 4 | Microsoft Excel spreadsheet format. |
The status of an issue.
Lives at the top level so both plan_service.proto and issue_service.proto
can reference it without a circular import.
| Name | Number | Description |
| ISSUE_STATUS_UNSPECIFIED | 0 | Unspecified status. |
| OPEN | 1 | Issue is open and active. |
| DONE | 2 | Issue is completed. |
| CANCELED | 3 | Issue is canceled. |
RiskLevel is the risk level.
| Name | Number | Description |
| RISK_LEVEL_UNSPECIFIED | 0 | Unspecified risk level. |
| LOW | 1 | Low risk operation. |
| MODERATE | 2 | Moderate risk operation. |
| HIGH | 3 | High risk operation. |
Resource lifecycle state.
| Name | Number | Description |
| STATE_UNSPECIFIED | 0 | |
| ACTIVE | 1 | Resource is active and operational. |
| DELETED | 2 | Resource is soft-deleted but may be recoverable. |
StatementType represents the type of SQL statement.
| Name | Number | Description |
| STATEMENT_TYPE_UNSPECIFIED | 0 | |
| CREATE_DATABASE | 1 | DDL - CREATE statements |
| CREATE_TABLE | 2 | |
| CREATE_VIEW | 3 | |
| CREATE_INDEX | 4 | |
| CREATE_SEQUENCE | 5 | |
| CREATE_SCHEMA | 6 | |
| CREATE_FUNCTION | 7 | |
| CREATE_TRIGGER | 8 | |
| CREATE_PROCEDURE | 9 | |
| CREATE_EVENT | 10 | |
| CREATE_EXTENSION | 11 | |
| CREATE_TYPE | 12 | |
| DROP_DATABASE | 20 | DDL - DROP statements |
| DROP_TABLE | 21 | |
| DROP_VIEW | 22 | |
| DROP_INDEX | 23 | |
| DROP_SEQUENCE | 24 | |
| DROP_SCHEMA | 25 | |
| DROP_FUNCTION | 26 | |
| DROP_TRIGGER | 27 | |
| DROP_PROCEDURE | 28 | |
| DROP_EVENT | 29 | |
| DROP_EXTENSION | 30 | |
| DROP_TYPE | 31 | |
| ALTER_DATABASE | 40 | DDL - ALTER statements |
| ALTER_TABLE | 41 | |
| ALTER_VIEW | 42 | |
| ALTER_SEQUENCE | 43 | |
| ALTER_EVENT | 44 | |
| ALTER_TYPE | 45 | |
| ALTER_INDEX | 46 | |
| TRUNCATE | 50 | DDL - Other |
| RENAME | 51 | |
| RENAME_INDEX | 52 | |
| RENAME_SCHEMA | 53 | |
| RENAME_SEQUENCE | 54 | |
| COMMENT | 55 | |
| INSERT | 60 | DML statements |
| UPDATE | 61 | |
| DELETE | 62 | |
| MERGE | 63 |
Version control system type.
| Name | Number | Description |
| VCS_TYPE_UNSPECIFIED | 0 | Unspecified VCS type. |
| GITHUB | 1 | GitHub version control platform. |
| GITLAB | 2 | GitLab version control platform. |
| BITBUCKET | 3 | Bitbucket version control platform. |
| AZURE_DEVOPS | 4 | Azure DevOps version control platform. |
Webhook integration type.
| Name | Number | Description |
| WEBHOOK_TYPE_UNSPECIFIED | 0 | Unspecified type. |
| SLACK | 1 | Slack integration. |
| DISCORD | 2 | Discord integration. |
| TEAMS | 3 | Microsoft Teams integration. |
| DINGTALK | 4 | DingTalk integration. |
| FEISHU | 5 | Feishu integration. |
| WECOM | 6 | WeCom (WeChat Work) integration. |
| LARK | 7 | Lark integration. |
| GOOGLE_CHAT | 8 | Google Chat integration. |
| Field | Type | Label | Description |
| parent | string | The task name for the taskRuns. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task} Use `projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/-` to cancel task runs under the same stage. |
|
| task_runs | string | repeated | The taskRuns to cancel. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
| Field | Type | Label | Description |
| parent | string | The stage name for the tasks. Format: projects/{project}/plans/{plan}/rollout/stages/{stage} |
|
| tasks | string | repeated | The tasks to run. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task} |
| run_time | google.protobuf.Timestamp | optional | The task run should run after run_time. |
| skip_prior_backup | bool | If true, skip prior backup for this run even if the task has prior backup enabled. |
| Field | Type | Label | Description |
| parent | string | The stage name for the tasks. Format: projects/{project}/plans/{plan}/rollout/stages/{stage} |
|
| tasks | string | repeated | The tasks to skip. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task} |
| reason | string | The reason for skipping the tasks. |
| Field | Type | Label | Description |
| parent | string | The parent plan for which this rollout will be created. Format: projects/{project}/plans/{plan} |
|
| target | string | optional | Create the rollout only for the specified target. Format: environments/{environment} If unspecified, all stages are created. If set to "", no stages are created. |
| Field | Type | Label | Description |
| name | string | The name of the rollout to retrieve. This is the rollout resource name, which is the plan name plus /rollout suffix. Format: projects/{project}/plans/{plan}/rollout |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of rollouts. Format: projects/{project} Use "projects/-" to list all rollouts from all projects. |
|
| page_size | int32 | The maximum number of rollouts to return. The service may return fewer than this value. If unspecified, at most 10 rollouts will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListRollouts` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListRollouts` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter rollouts returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filters: - update_time: rollout update time in "2006-01-02T15:04:05Z07:00" format, support ">=" or "<=" operator. - task_type: the task type, support "in" operator, check the Task.Type enum for the values. For example: update_time >= "2025-01-02T15:04:05Z07:00" task_type in ["DATABASE_MIGRATE", "DATABASE_CREATE"] |
| Field | Type | Label | Description |
| rollouts | Rollout | repeated | The rollouts from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of taskRuns. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task} Use "projects/{project}/plans/{plan}/rollout/stages/-/tasks/-" to list all taskRuns from a rollout. |
|
| page_size | int32 | The maximum number of task runs to return. The service may return fewer than this value. If unspecified, at most 1000 task runs will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListTaskRuns` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListTaskRuns` must match the call that provided the page token. |
| Field | Type | Label | Description |
| task_runs | TaskRun | repeated | The taskRuns from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
| Field | Type | Label | Description |
| statement | string | The rollback SQL statement that would undo the task run. |
| Field | Type | Label | Description |
| name | string | The resource name of the rollout. Format: projects/{project}/plans/{plan}/rollout |
|
| title | string | The title of the rollout, inherited from the associated plan. This field is output only and cannot be directly set. |
|
| stages | Stage | repeated | Stages and thus tasks of the rollout. |
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage} Use "-" for {stage} when the stage has no environment or deleted environment. |
|
| id | string | id is the environment id of the stage. e.g., "prod". Use "-" when the stage has no environment or deleted environment. |
|
| environment | string | environment is the environment of the stage. Format: environments/{environment} for valid environments, or "environments/-" for stages without environment or with deleted environments. |
|
| tasks | Task | repeated | The tasks within this stage. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task} |
|
| spec_id | string | A UUID4 string that uniquely identifies the Spec. |
|
| status | Task.Status | Status is the status of the task. |
|
| skipped_reason | string | The reason why the task was skipped. |
|
| type | Task.Type |
|
|
| target | string | Format: instances/{instance} or projects/{project}/instances/{instance} if the task is DatabaseCreate. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| database_create | Task.DatabaseCreate |
|
|
| database_update | Task.DatabaseUpdate |
|
|
| update_time | google.protobuf.Timestamp | optional | The update_time is the update time of latest task run. If there are no task runs, it will be empty. |
| run_time | google.protobuf.Timestamp | optional | The run_time is the scheduled run time of latest task run. If there are no task runs or the task run is not scheduled, it will be empty. |
Payload for creating a new database.
| Field | Type | Label | Description |
| sheet | string | Format: projects/{project}/sheets/{sheet} |
Payload for updating a database schema.
| Field | Type | Label | Description |
| sheet | string | Format: projects/{project}/sheets/{sheet} |
|
| release | string | Format: projects/{project}/releases/{release} |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
|
| creator | string | Format: users/hello@world.com |
|
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
|
| status | TaskRun.Status | The current execution status of the task run. |
|
| detail | string | Below are the results of a task run. Detailed information about the task run result. |
|
| start_time | google.protobuf.Timestamp | The time when the task run started execution. |
|
| has_prior_backup | bool | Indicates whether a prior backup was created for this task run. When true, rollback SQL can be generated via PreviewTaskRunRollback. Backup details are available in the task run logs. |
|
| scheduler_info | TaskRun.SchedulerInfo | Scheduling information about the task run. |
|
| run_time | google.protobuf.Timestamp | optional | The task run should run after run_time. This can only be set when creating the task run calling BatchRunTasks. |
Information about task run scheduling.
| Field | Type | Label | Description |
| report_time | google.protobuf.Timestamp | The time when the scheduling info was reported. |
|
| waiting_cause | TaskRun.SchedulerInfo.WaitingCause | The cause for the task run waiting. |
Information about why a task run is waiting.
| Field | Type | Label | Description |
| parallel_tasks_limit | bool | Waiting due to parallel tasks limit. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun}/log |
|
| entries | TaskRunLogEntry | repeated | The log entries for this task run. |
| Field | Type | Label | Description |
| type | TaskRunLogEntry.Type | The type of this log entry. |
|
| log_time | google.protobuf.Timestamp | The time when the log was recorded. |
|
| replica_id | string | The replica ID for this log entry. |
|
| schema_dump | TaskRunLogEntry.SchemaDump | Schema dump details (if type is SCHEMA_DUMP). |
|
| command_execute | TaskRunLogEntry.CommandExecute | Command execution details (if type is COMMAND_EXECUTE). |
|
| database_sync | TaskRunLogEntry.DatabaseSync | Database sync details (if type is DATABASE_SYNC). |
|
| transaction_control | TaskRunLogEntry.TransactionControl | Transaction control details (if type is TRANSACTION_CONTROL). |
|
| prior_backup | TaskRunLogEntry.PriorBackup | Prior backup details (if type is PRIOR_BACKUP). |
|
| retry_info | TaskRunLogEntry.RetryInfo | Retry information details (if type is RETRY_INFO). |
|
| compute_diff | TaskRunLogEntry.ComputeDiff | Compute diff details (if type is COMPUTE_DIFF). |
|
| release_file_execute | TaskRunLogEntry.ReleaseFileExecute | Release file execution details (if type is RELEASE_FILE_EXECUTE). |
|
| ghost_migration | TaskRunLogEntry.GhostMigration | gh-ost migration details (if type is GHOST_MIGRATION). |
Command execution details.
| Field | Type | Label | Description |
| log_time | google.protobuf.Timestamp | When the command was logged. |
|
| range | Range | The byte offset range of the executed command in the sheet. Uses byte offsets (not character indices) for efficient slicing of sheet content bytes. Example: For "SELECT 你好;" in a UTF-8 sheet, range [0, 13) represents all 13 bytes. |
|
| statement | string | The executed statement. |
|
| response | TaskRunLogEntry.CommandExecute.CommandResponse | The response from executing the command. |
Command execution response.
| Field | Type | Label | Description |
| log_time | google.protobuf.Timestamp | When the response was logged. |
|
| error | string | Error message if command execution failed. |
|
| affected_rows | int64 | Total affected rows. |
|
| all_affected_rows | int64 | repeated | `all_affected_rows` is the affected rows of each command. `all_affected_rows` may be unavailable if the database driver doesn't support it. Caller should fallback to `affected_rows` in that case. |
Schema diff computation details.
| Field | Type | Label | Description |
| start_time | google.protobuf.Timestamp | When diff computation started. |
|
| end_time | google.protobuf.Timestamp | When diff computation ended. |
|
| error | string | Error message if computation failed. |
Database synchronization details.
| Field | Type | Label | Description |
| start_time | google.protobuf.Timestamp | When the database sync started. |
|
| end_time | google.protobuf.Timestamp | When the database sync ended. |
|
| error | string | Error message if sync failed. |
gh-ost migration details.
| Field | Type | Label | Description |
| start_time | google.protobuf.Timestamp | When the gh-ost migration started. |
|
| end_time | google.protobuf.Timestamp | When the gh-ost migration ended. |
|
| error | string | Error message if the gh-ost migration failed. |
Prior backup operation details.
| Field | Type | Label | Description |
| start_time | google.protobuf.Timestamp | When the backup started. |
|
| end_time | google.protobuf.Timestamp | When the backup ended. |
|
| prior_backup_detail | TaskRunLogEntry.PriorBackup.PriorBackupDetail | The backup details. |
|
| error | string | Error message if the backup failed. |
Prior backup detail for rollback purposes.
| Field | Type | Label | Description |
| items | TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item | repeated | The list of backed up tables. |
A single backup table mapping.
| Field | Type | Label | Description |
| source_table | TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item.Table | The original table information. |
|
| target_table | TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item.Table | The target backup table information. |
|
| start_position | Position | The start position in the SQL statement. |
|
| end_position | Position | The end position in the SQL statement. |
Table information.
| Field | Type | Label | Description |
| database | string | The database information. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| schema | string | The schema name. |
|
| table | string | The table name. |
Release file execution details.
| Field | Type | Label | Description |
| version | string | The version of the file being executed (e.g., "0001"). |
|
| file_path | string | The file path within the release (e.g., "2.2/V0001_create_table.sql"). |
Retry information for failed operations.
| Field | Type | Label | Description |
| error | string | The error that triggered the retry. |
|
| retry_count | int32 | Current retry attempt number. |
|
| maximum_retries | int32 | Maximum number of retries allowed. |
Schema dump operation details.
| Field | Type | Label | Description |
| start_time | google.protobuf.Timestamp | When the schema dump started. |
|
| end_time | google.protobuf.Timestamp | When the schema dump ended. |
|
| error | string | Error message if the schema dump failed. |
Transaction control operation details.
| Field | Type | Label | Description |
| type | TaskRunLogEntry.TransactionControl.Type | The type of transaction control. |
|
| error | string | Error message if the operation failed. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun}/session |
|
| postgres | TaskRunSession.Postgres | PostgreSQL session information. |
PostgreSQL session information.
| Field | Type | Label | Description |
| session | TaskRunSession.Postgres.Session | `session` is the session of the task run executing commands. |
|
| blocking_sessions | TaskRunSession.Postgres.Session | repeated | `blocking_sessions` block `session`. |
| blocked_sessions | TaskRunSession.Postgres.Session | repeated | `blocked_sessions` are blocked by `session`. |
PostgreSQL session information read from `pg_stat_activity`.
| Field | Type | Label | Description |
| pid | string | Process ID of the session. |
|
| blocked_by_pids | string | repeated | PIDs of sessions blocking this session. |
| query | string | Current query being executed. |
|
| state | string | optional | Session state (active, idle, etc.). |
| wait_event_type | string | optional | Wait event type if session is waiting. |
| wait_event | string | optional | Specific wait event if session is waiting. |
| datname | string | optional | Database name. |
| usename | string | optional | User name. |
| application_name | string | Application name. |
|
| client_addr | string | optional | Client IP address. |
| client_port | string | optional | Client port number. |
| backend_start | google.protobuf.Timestamp | When the backend process started. |
|
| xact_start | google.protobuf.Timestamp | optional | When the current transaction started. |
| query_start | google.protobuf.Timestamp | optional | When the current query started. |
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | Unspecified status. |
| NOT_STARTED | 1 | Task has not started and is awaiting its turn in the deployment sequence. |
| PENDING | 2 | Task is ready to run and waiting for approval or scheduled time. |
| RUNNING | 3 | Task is currently executing. |
| DONE | 4 | Task completed successfully. |
| FAILED | 5 | Task execution failed with errors. |
| CANCELED | 6 | Task execution was canceled by a user. |
| SKIPPED | 7 | Task was skipped and will not be executed. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified task type. |
| GENERAL | 1 | General task for miscellaneous operations. |
| DATABASE_CREATE | 2 | Database creation task that creates a new database. Use payload DatabaseCreate. |
| DATABASE_MIGRATE | 3 | Database migration task that applies versioned schema changes. Use payload DatabaseUpdate. |
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | Unspecified status. |
| PENDING | 1 | Task run is queued and waiting to start execution. |
| RUNNING | 2 | Task run is currently executing. |
| DONE | 3 | Task run completed successfully. |
| FAILED | 4 | Task run execution failed with errors. |
| CANCELED | 5 | Task run execution was canceled by a user. |
| AVAILABLE | 6 | Task run is ready for immediate execution. |
Transaction control type.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified type. |
| BEGIN | 1 | Begin transaction. |
| COMMIT | 2 | Commit transaction. |
| ROLLBACK | 3 | Rollback transaction. |
The type of log entry.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified type. |
| SCHEMA_DUMP | 1 | Schema dump operation. |
| COMMAND_EXECUTE | 2 | Command execution. |
| DATABASE_SYNC | 3 | Database synchronization. |
| TRANSACTION_CONTROL | 5 | Transaction control (BEGIN, COMMIT, ROLLBACK). |
| PRIOR_BACKUP | 6 | Prior backup operation. |
| RETRY_INFO | 7 | Retry information. |
| COMPUTE_DIFF | 8 | Schema diff computation. |
| RELEASE_FILE_EXECUTE | 9 | Release file execution. |
| GHOST_MIGRATION | 10 | gh-ost online migration. |
RolloutService manages the execution of deployment plans.
| Method Name | Request Type | Response Type | Description |
| GetRollout | GetRolloutRequest | Rollout | Retrieves a rollout by its plan name. Permissions required: bb.rollouts.get |
| ListRollouts | ListRolloutsRequest | ListRolloutsResponse | Lists rollouts in a project. Permissions required: bb.rollouts.list |
| CreateRollout | CreateRolloutRequest | Rollout | Creates a new rollout for a plan. Permissions required: bb.rollouts.create |
| ListTaskRuns | ListTaskRunsRequest | ListTaskRunsResponse | Lists task run executions for a task. Permissions required: bb.taskRuns.list |
| GetTaskRun | GetTaskRunRequest | TaskRun | Retrieves a task run by name. Permissions required: bb.taskRuns.list |
| GetTaskRunLog | GetTaskRunLogRequest | TaskRunLog | Retrieves execution logs for a task run. Permissions required: bb.taskRuns.list |
| GetTaskRunSession | GetTaskRunSessionRequest | TaskRunSession | Retrieves database session information for a running task. Permissions required: bb.taskRuns.list |
| BatchRunTasks | BatchRunTasksRequest | BatchRunTasksResponse | Executes multiple tasks in a rollout stage. Permissions required: bb.taskRuns.create (or user with rollout policy role for the environment) |
| BatchSkipTasks | BatchSkipTasksRequest | BatchSkipTasksResponse | Skips multiple tasks in a rollout stage. Permissions required: bb.taskRuns.create (or user with rollout policy role for the environment) |
| BatchCancelTaskRuns | BatchCancelTaskRunsRequest | BatchCancelTaskRunsResponse | Cancels multiple task runs. PENDING and AVAILABLE task runs are moved to CANCELED synchronously. RUNNING task runs receive a best-effort cancellation request and may continue running if the request is missed or the executor does not stop. The response does not report which task runs were actually canceled. Permissions required: bb.taskRuns.create (or user with rollout policy role for the environment) |
| PreviewTaskRunRollback | PreviewTaskRunRollbackRequest | PreviewTaskRunRollbackResponse | Generates rollback SQL for a completed task run. Permissions required: bb.taskRuns.list |
| Method Name | Method | Pattern | Body |
| GetRollout | GET | /v1/{name=projects/*/plans/*/rollout} | |
| ListRollouts | GET | /v1/{parent=projects/*}/rollouts | |
| CreateRollout | POST | /v1/{parent=projects/*/plans/*}/rollout | * |
| ListTaskRuns | GET | /v1/{parent=projects/*/plans/*/rollout/stages/*/tasks/*}/taskRuns | |
| GetTaskRun | GET | /v1/{name=projects/*/plans/*/rollout/stages/*/tasks/*/taskRuns/*} | |
| GetTaskRunLog | GET | /v1/{parent=projects/*/plans/*/rollout/stages/*/tasks/*/taskRuns/*}/log | |
| GetTaskRunSession | GET | /v1/{parent=projects/*/plans/*/rollout/stages/*/tasks/*/taskRuns/*}/session | |
| BatchRunTasks | POST | /v1/{parent=projects/*/plans/*/rollout/stages/*}/tasks:batchRun | * |
| BatchSkipTasks | POST | /v1/{parent=projects/*/plans/*/rollout/stages/*}/tasks:batchSkip | * |
| BatchCancelTaskRuns | POST | /v1/{parent=projects/*/plans/*/rollout/stages/*/tasks/*}/taskRuns:batchCancel | * |
| PreviewTaskRunRollback | POST | /v1/{name=projects/*/plans/*/rollout/stages/*/tasks/*/taskRuns/*}:previewRollback | * |
| Field | Type | Label | Description |
| name | string | The name of the query history to retrieve. Format: projects/{project}/queryHistories/{id} |
| Field | Type | Label | Description |
| parent | string | The parent project whose query histories are listed. Format: projects/{project} Use "projects/-" to list query histories across all projects (https://google.aip.dev/159); this requires the bb.queryHistories.list permission on the workspace. |
|
| page_size | int32 | The maximum number of histories to return. The service may return fewer than this value. If unspecified, at most 10 history entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListQueryHistories` call. Provide this to retrieve the subsequent page. |
|
| filter | string | Filter is the filter to apply on the list query histories. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - creator: the user full name in "users/{email}" format, support "==" operator. For example: creator == "users/{email}" |
| Field | Type | Label | Description |
| query_histories | QueryHistory | repeated | The list of query histories. |
| next_page_token | string | A token to retrieve next page of history. Pass this value in the page_token field in the subsequent call to `ListQueryHistories` method to retrieve the next page of history. |
| Field | Type | Label | Description |
| name | string | The name for the query history. Format: projects/{project}/queryHistories/{id} |
|
| database | string | The database name to execute the query. Format: instances/{instance}/databases/{databaseName} or projects/{project}/instances/{instance}/databases/{databaseName} |
|
| creator | string |
|
|
| create_time | google.protobuf.Timestamp |
|
|
| statement | string |
|
|
| error | string | optional |
|
| duration | google.protobuf.Duration |
|
|
| type | QueryHistory.Type |
|
| Field | Type | Label | Description |
| parent | string | The parent project to search query histories in. Format: projects/{project} The AIP-159 wildcard "projects/-" is not supported; use ListQueryHistories for cross-project reads. |
|
| page_size | int32 | The maximum number of histories to return. The service may return fewer than this value. If unspecified, at most 10 history entries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListQueryHistory` call. Provide this to retrieve the subsequent page. |
|
| filter | string | Filter is the filter to apply on the search query history The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - project: the project full name in "projects/{id}" format, support "==" operator. - database: the database full name in "instances/{id}/databases/{name}" or "projects/{project}/instances/{id}/databases/{name}" format, support "==" operator. - instance: the instance full name in "instances/{id}" or "projects/{project}/instances/{id}" format, support "==" operator. - type: the type, should be "QUERY" or "EXPORT", support "==" operator. - statement: the SQL statement, support "==" and ".contains()" operators. For example: project == "projects/{project}" database == "instances/{instance}/databases/{database}" instance == "instances/{instance}" type == "QUERY" type == "EXPORT" statement == "SELECT 1;" statement.contains("select") type == "QUERY" && statement.contains("select") |
| Field | Type | Label | Description |
| query_histories | QueryHistory | repeated | The list of history. |
| next_page_token | string | A token to retrieve next page of history. Pass this value in the page_token field in the subsequent call to `ListQueryHistory` method to retrieve the next page of history. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified query history type. |
| QUERY | 1 | Query execution for data retrieval. |
| EXPORT | 2 | Data export operation to file. |
QueryHistoryService manages query history records of SQL Editor queries and exports.
| Method Name | Request Type | Response Type | Description |
| SearchQueryHistories | SearchQueryHistoriesRequest | SearchQueryHistoriesResponse | SearchQueryHistories searches query histories for the caller. Permissions required: None (only returns caller's own query histories) |
| ListQueryHistories | ListQueryHistoriesRequest | ListQueryHistoriesResponse | ListQueryHistories lists query histories of all users in a project. Results are ordered by create time descending (newest first). Permissions required: bb.queryHistories.list |
| GetQueryHistory | GetQueryHistoryRequest | QueryHistory | GetQueryHistory gets a single query history for the caller. Permissions required: None (only returns the caller's own query history) |
| Method Name | Method | Pattern | Body |
| SearchQueryHistories | POST | /v1/{parent=projects/*}/queryHistories:search | * |
| ListQueryHistories | GET | /v1/{parent=projects/*}/queryHistories | |
| GetQueryHistory | GET | /v1/{name=projects/*/queryHistories/*} |
| Field | Type | Label | Description |
| name | string | The name is the instance name to execute the query against. Format: instances/{instance}/databases/{databaseName} or projects/{project}/instances/{instance}/databases/{databaseName} |
|
| statement | string | The SQL statement to execute. |
|
| limit | int32 | The maximum number of rows to return. |
|
| schema | string | optional | The default schema to execute the statement. Equals to the current schema in Oracle and search path in Postgres. |
| container | string | optional | Container is the container name to execute the query against, used for CosmosDB only. |
| Field | Type | Label | Description |
| results | QueryResult | repeated | The query results. |
| Field | Type | Label | Description |
| status | Advice.Level | The advice level. |
|
| code | int32 | The advice code. |
|
| title | string | The advice title. |
|
| content | string | The advice content. |
|
| start_position | Position | The start_position is inclusive and the end_position is exclusive. TODO: use range instead |
|
| end_position | Position |
|
|
| rule_type | Advice.RuleType | The type of linting rule that generated this advice. |
| Field | Type | Label | Description |
| name | string | The name is the resource name to execute the export against. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| statement | string | The SQL statement to execute. |
|
| limit | int32 | The maximum number of rows to return. |
|
| format | ExportFormat | The export format. |
|
| admin | bool | The admin is used for workspace owner and DBA for exporting data from SQL Editor Admin mode. The exported data is not masked. |
|
| password | string | The zip password provide by users. |
|
| data_source_id | string | The id of data source. If omitted, Export resolves the data source server-side by using the single read-only data source when exactly one exists, or the admin data source otherwise. It can also be set explicitly to export from the admin data source or a specific read-only data source. |
|
| schema | string | optional | The default schema to search objects. Equals to the current schema in Oracle and search path in Postgres. |
| container | string | optional | Container is the container name to execute the query against, used for CosmosDB only. |
| destination | ExportDestination | Where the export goes. A destination the workspace query data policy does not allow is rejected with FAILED_PRECONDITION. |
| Field | Type | Label | Description |
| content | bytes | The export file content. |
|
| applied_access_grant | string | The just-in-time access grant applied to this export, if any. Format: projects/{project}/accessGrants/{accessGrant}. Empty when the user was authorized through normal ACL rather than a grant. |
|
| uri | string | Set when the export was sent to an export destination: the absolute location of the folder or key prefix created for this export, for example https://… for SharePoint or s3://bucket/prefix for S3. content is then empty. |
| Field | Type | Label | Description |
| semantic_type_id | string | The semantic type that triggered masking (e.g., "SSN", "email", "phone"). |
|
| semantic_type_title | string | Human-readable semantic type title. |
|
| masking_rule_id | string | The masking rule ID that matched (if applicable). |
|
| algorithm | string | The masking algorithm used. |
|
| context | string | Additional context (e.g., "Matched global rule: PII Protection"). |
|
| classification_level | int32 | The classification level that triggered masking. |
|
| semantic_type_icon | string | Icon associated with the semantic type (if any). |
| Field | Type | Label | Description |
| redis_run_commands_on | QueryOption.RedisRunCommandsOn |
|
|
| explain_format | QueryOption.ExplainFormat | Which explain output the caller wants, for an explain request. Leave it unspecified for the engine's own default, which is the only output most engines have. Naming a format an engine cannot produce is INVALID_ARGUMENT rather than a silent fallback, as is any explain request against an engine that has no explain at all. |
| Field | Type | Label | Description |
| name | string | The name is the database resource name to execute the query against. Format: instances/{instance}/databases/{databaseName} or projects/{project}/instances/{instance}/databases/{databaseName} |
|
| statement | string | The SQL statement to execute. |
|
| limit | int32 | The maximum number of rows to return. |
|
| data_source_id | string | The id of data source. If omitted, Query resolves the data source server-side by using the single read-only data source when exactly one exists, or the admin data source otherwise. It can also be set explicitly to query the admin data source or a specific read-only data source. |
|
| explain | bool | Explain the statement. |
|
| schema | string | optional | The default schema to search objects. Equals to the current schema in Oracle and search path in Postgres. |
| query_option | QueryOption |
|
|
| container | string | optional | Container is the container name to execute the query against, used for CosmosDB only. |
| Field | Type | Label | Description |
| results | QueryResult | repeated | The query results. |
| applied_access_grant | string | The just-in-time access grant applied to this query, if any. Format: projects/{project}/accessGrants/{accessGrant}. Empty when the user was authorized through normal ACL rather than a grant. |
| Field | Type | Label | Description |
| column_names | string | repeated | Column names of the query result. |
| column_type_names | string | repeated | Column types of the query result. The types come from the Golang SQL driver. |
| rows | QueryRow | repeated | Rows of the query result. |
| rows_count | int64 |
|
|
| error | string | The error message if the query failed. |
|
| latency | google.protobuf.Duration | The time it takes to execute the query. |
|
| statement | string | The query statement for the result. |
|
| postgres_error | QueryResult.PostgresError |
|
|
| syntax_error | QueryResult.SyntaxError |
|
|
| permission_denied | PermissionDeniedDetail |
|
|
| command_error | QueryResult.CommandError |
|
|
| messages | QueryResult.Message | repeated | Informational or debug messages returned by the database engine during query execution. Examples include PostgreSQL's RAISE NOTICE, MSSQL's PRINT, or Oracle's DBMS_OUTPUT.PUT_LINE. |
| masked | MaskingReason | repeated | Masking reasons for each column (empty for non-masked columns). |
| query_plan | QueryResult.QueryPlan | Set when the result is a query plan. Unset for any other result. |
Permission denied with resource information or disallowed command_type.
Either resources or command_type is available.
| Field | Type | Label | Description |
| command_type | QueryResult.CommandError.Type | Disallowed command_type. |
| Field | Type | Label | Description |
| level | QueryResult.Message.Level |
|
|
| content | string |
|
refer https://www.postgresql.org/docs/11/protocol-error-fields.html
for field description.
| Field | Type | Label | Description |
| severity | string |
|
|
| code | string |
|
|
| message | string |
|
|
| detail | string |
|
|
| hint | string |
|
|
| position | int32 |
|
|
| internal_position | int32 |
|
|
| internal_query | string |
|
|
| where | string |
|
|
| schema_name | string |
|
|
| table_name | string |
|
|
| column_name | string |
|
|
| data_type_name | string |
|
|
| constraint_name | string |
|
|
| file | string |
|
|
| line | int32 |
|
|
| routine | string |
|
A query plan the result carries: in its rows, or beside them.
| Field | Type | Label | Description |
| format | QueryOption.ExplainFormat |
|
|
| executed | bool | Whether producing the plan executed the statement, as EXPLAIN ANALYZE does. |
|
| content | string | The plan itself, where the engine states it beside the result rather than in the result's rows. BigQuery reports the stages its job ran in the job's own statistics, so one result carries the query's data and the plan of the run that produced it. Empty when the plan is the rows, which is every other engine. Omitted from the audit log, as the rows are: the statement is what an audit reads. |
Syntax error with position information for editor highlighting
| Field | Type | Label | Description |
| start_position | Position | Position information for highlighting in editor |
| Field | Type | Label | Description |
| values | RowValue | repeated | Row values of the query result. |
| Field | Type | Label | Description |
| null_value | google.protobuf.NullValue |
|
|
| bool_value | bool |
|
|
| bytes_value | bytes |
|
|
| double_value | double |
|
|
| float_value | float |
|
|
| int32_value | int32 |
|
|
| int64_value | int64 |
|
|
| string_value | string |
|
|
| uint32_value | uint32 |
|
|
| uint64_value | uint64 |
|
|
| value_value | google.protobuf.Value | value_value is used for Spanner and TUPLE ARRAY MAP in Clickhouse only. |
|
| timestamp_value | RowValue.Timestamp | timestamp_value is used for the timestamp without time zone data type, meaning it only includes the timestamp without any time zone or location info. Although it may be expressed as a UTC value, it should be seen as a timestamp missing location context. |
|
| timestamp_tz_value | RowValue.TimestampTZ | timestamp_tz_value is used for the timestamptz data type, which accurately represents the timestamp with location information. |
| Field | Type | Label | Description |
| google_timestamp | google.protobuf.Timestamp |
|
|
| accuracy | int32 | The accuracy is the number of digits after the decimal point. |
| Field | Type | Label | Description |
| google_timestamp | google.protobuf.Timestamp |
|
|
| zone | string | Zone is the time zone abbreviations in timezone database such as "PDT", "PST". https://en.wikipedia.org/wiki/List_of_tz_database_time_zones We retrieve the time zone information from the timestamptz field in the database. A timestamp is in UTC or epoch time, and with zone info, we can convert it to a local time string. Zone and offset are returned by time.Time.Zone() |
|
| offset | int32 | The offset is in seconds east of UTC |
|
| accuracy | int32 |
|
Level represents the severity level of the advice.
| Name | Number | Description |
| ADVICE_LEVEL_UNSPECIFIED | 0 | Unspecified advice level. |
| SUCCESS | 1 | Success status indicating the check passed without issues. |
| WARNING | 2 | Warning status indicating potential issues that should be reviewed. |
| ERROR | 3 | Error status indicating critical issues that must be addressed. |
RuleType indicates the source of the linting rule.
| Name | Number | Description |
| RULE_TYPE_UNSPECIFIED | 0 | Unspecified rule type. |
| PARSER_BASED | 1 | Parser-based rule enforced by the built-in SQL parser. These are non-configurable, mandatory checks for schema health. |
| AI_POWERED | 2 | AI-powered rule defined by user in natural language. These are custom, flexible checks powered by AI models. |
The output format of a query plan.
| Name | Number | Description |
| EXPLAIN_FORMAT_UNSPECIFIED | 0 | The engine's default: PostgreSQL EXPLAIN, SQL Server SHOWPLAN_ALL. On a result, a default the server could not resolve, as when MySQL follows the session's explain_format; read such a plan as text. |
| TEXT | 1 | The human-readable plan. PostgreSQL: EXPLAIN (FORMAT TEXT). SQL Server: SHOWPLAN_ALL. |
| JSON | 2 | The plan tree as JSON. PostgreSQL: EXPLAIN (FORMAT JSON). |
| XML | 3 | The plan tree as XML. PostgreSQL: EXPLAIN (FORMAT XML). SQL Server: SHOWPLAN_XML. |
| YAML | 4 | The plan tree as YAML. PostgreSQL: EXPLAIN (FORMAT YAML). |
| Name | Number | Description |
| REDIS_RUN_COMMANDS_ON_UNSPECIFIED | 0 | UNSPECIFIED defaults to SINGLE_NODE. |
| SINGLE_NODE | 1 | Execute Redis commands on a single node in the cluster. |
| ALL_NODES | 2 | Execute Redis commands on all nodes in the cluster for cluster-wide operations. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| DDL | 1 | |
| DML | 2 | |
| NON_READ_ONLY | 3 |
| Name | Number | Description |
| LEVEL_UNSPECIFIED | 0 | Unspecified message level. |
| INFO | 1 | Informational message. |
| WARNING | 2 | Warning message indicating potential issues. |
| DEBUG | 3 | Debug message for development and troubleshooting. |
| LOG | 4 | General log message. |
| NOTICE | 5 | Notice message for important information. |
| EXCEPTION | 6 | Exception message indicating error conditions. |
SQLService executes SQL queries and manages query operations.
| Method Name | Request Type | Response Type | Description |
| Query | QueryRequest | QueryResponse | Executes a read-only SQL query against a database. Permissions required: bb.databases.get |
| AdminExecute | AdminExecuteRequest stream | AdminExecuteResponse stream | Executes SQL with admin privileges via streaming connection. Permissions required: bb.sql.admin |
| SearchQueryHistories | SearchQueryHistoriesRequest | SearchQueryHistoriesResponse | Deprecated: use QueryHistoryService.SearchQueryHistories instead. Delegating alias kept for upgrade transition; will be removed in a future release. No HTTP binding: the REST route is served by QueryHistoryService. Permissions required: None (only returns caller's own query histories) |
| ListQueryHistories | ListQueryHistoriesRequest | ListQueryHistoriesResponse | Deprecated: use QueryHistoryService.ListQueryHistories instead. Delegating alias kept for upgrade transition; will be removed in a future release. No HTTP binding: the REST route is served by QueryHistoryService. Permissions required: bb.queryHistories.list |
| GetQueryHistory | GetQueryHistoryRequest | QueryHistory | Deprecated: use QueryHistoryService.GetQueryHistory instead. Delegating alias kept for upgrade transition; will be removed in a future release. No HTTP binding: the REST route is served by QueryHistoryService. Permissions required: None (only returns the caller's own query history) |
| Export | ExportRequest | ExportResponse | Exports query results to a file format. Permissions required: bb.databases.get, and bb.sql.export on the data the statement reads. An active access grant with export=true for the statement satisfies bb.sql.export on its target databases. |
| Method Name | Option |
| SearchQueryHistories | true |
| ListQueryHistories | true |
| GetQueryHistory | true |
| Method Name | Method | Pattern | Body |
| Query | POST | /v1/{name=instances/*/databases/*}:query | * |
| Query | POST | /v1/{name=projects/*/instances/*/databases/*}:query | * |
| AdminExecute | GET | /v1:adminExecute | |
| Export | POST | /v1/{name=instances/*/databases/*}:export | * |
| Export | POST | /v1/{name=projects/*/instances/*/databases/*}:export | * |
| Field | Type | Label | Description |
| name | string | The name of the plan check run to cancel. Format: projects/{project}/plans/{plan}/planCheckRun |
| Field | Type | Label | Description |
| parent | string | The parent project where this plan will be created. Format: projects/{project} |
|
| plan | Plan | The plan to create. |
| Field | Type | Label | Description |
| name | string | The name of the plan check run to retrieve. Format: projects/{project}/plans/{plan}/planCheckRun |
| Field | Type | Label | Description |
| name | string | The name of the plan to retrieve. Format: projects/{project}/plans/{plan} |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of plans. Format: projects/{project} Use "projects/-" to list all plans from all projects. |
|
| page_size | int32 | The maximum number of plans to return. The service may return fewer than this value. If unspecified, at most 10 plans will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListPlans` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListPlans` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter plans returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filters: - creator: the plan creator full name in "users/{email or id}" format, support "==" operator. - create_time: the plan create time in "2006-01-02T15:04:05Z07:00" format, support ">=" or "<=" operator. - has_rollout: whether the plan has rollout, support "==" operator, the value should be "true" or "false". - title: the plan title, support "==" operator for exact match and ".contains()" operator for case-insensitive substring match. - spec_type: the plan spec config type, support "==" operator, the value should be "create_database_config" or "change_database_config". - state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED". - has_release: whether a spec references a release, support "==" operator, the value should be "true" or "false". - release: the release a spec references, in "projects/{project}/releases/{release}" format, support "==" operator. - task_status: the current status of any task in the plan, support "in" operator, the values should be Task.Status values except STATUS_UNSPECIFIED. For example: creator == "users/ed@bytebase.com" && create_time >= "2025-01-02T15:04:05Z07:00" title == "My Plan" title.contains("database migration") spec_type == "change_database_config" state == "ACTIVE" has_release == true && task_status in ["FAILED", "RUNNING"] release == "projects/my-project/releases/release_20260115-RC00" |
| Field | Type | Label | Description |
| plans | Plan | repeated | The plans from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | The name of the plan. `plan` is a system generated ID. Format: projects/{project}/plans/{plan} |
|
| state | State | The state of the plan. |
|
| issue | string | The issue associated with the plan. Can be empty. Format: projects/{project}/issues/{issue} |
|
| title | string | The title of the plan. |
|
| description | string | The description of the plan. |
|
| specs | Plan.Spec | repeated | The deployment specs for the plan. |
| creator | string | Format: users/hello@world.com |
|
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
|
| plan_check_run_status_count | Plan.PlanCheckRunStatusCountEntry | repeated | The status count of the latest plan check runs. Keys are: - SUCCESS - WARNING - ERROR - RUNNING |
| has_rollout | bool | Whether the plan has started the rollout. |
|
| approval_status | ApprovalStatus | The approval status of the linked issue. Unspecified when no linked issue exists or the linked issue is a draft. |
|
| rollout_stage_summaries | Plan.RolloutStageSummary | repeated | Per-stage rollout status summary. Ordered by environment deployment order. Empty when no rollout exists. |
| issue_status | IssueStatus | The lifecycle status of the linked issue. Unspecified when no linked issue exists. |
|
| last_plan_editor | string | The user who last created or updated the Plan specs. Format: users/hello@world.com. For legacy Plans without stored attribution, this falls back to the Plan creator. |
| Field | Type | Label | Description |
| targets | string | repeated | The list of targets. Multi-database format: [instances/{instance-id}/databases/{database-name}]. Single database group format: [projects/{project}/databaseGroups/{databaseGroup}]. |
| sheet | string | The resource name of the sheet. Format: projects/{project}/sheets/{sheet} |
|
| release | string | The resource name of the release. Format: projects/{project}/releases/{release} |
|
| enable_prior_backup | bool | If set, a backup of the modified data will be created automatically before any changes are applied. |
| Field | Type | Label | Description |
| target | string | The resource name of the instance on which the database is created. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| database | string | The name of the database to create. |
|
| table | string | table is the name of the table, if it is not empty, Bytebase should create a table after creating the database. For example, in MongoDB, it only creates the database when we first store data in that database. |
|
| character_set | string | character_set is the character set of the database. |
|
| collation | string | collation is the collation of the database. |
|
| cluster | string | cluster is the cluster of the database. This is only applicable to ClickHouse for "ON CLUSTER <<cluster>>". |
|
| owner | string | owner is the owner of the database. This is only applicable to Postgres for "WITH OWNER <<owner>>". |
|
| environment | string | The environment resource. Format: environments/prod where prod is the environment resource ID. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | int32 |
|
| Field | Type | Label | Description |
| stage | string | The stage resource name. Format: projects/{project}/plans/{plan}/rollout/stages/{stage} |
|
| task_status_counts | Plan.TaskStatusCount | repeated | Task status counts for this stage. |
| Field | Type | Label | Description |
| id | string | A UUID4 string that uniquely identifies the Spec. |
|
| create_database_config | Plan.CreateDatabaseConfig |
|
|
| change_database_config | Plan.ChangeDatabaseConfig |
|
| Field | Type | Label | Description |
| status | Task.Status | The task status. |
|
| count | int32 | The number of tasks in the status. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/plans/{plan}/planCheckRun |
|
| status | PlanCheckRun.Status |
|
|
| results | PlanCheckRun.Result | repeated |
|
| error | string | error is set if the Status is FAILED. |
|
| create_time | google.protobuf.Timestamp |
|
| Field | Type | Label | Description |
| status | Advice.Level |
|
|
| title | string |
|
|
| content | string |
|
|
| code | int32 |
|
|
| target | string | Target identification for consolidated results. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| type | PlanCheckRun.Result.Type |
|
|
| sql_summary_report | PlanCheckRun.Result.SqlSummaryReport |
|
|
| sql_review_report | PlanCheckRun.Result.SqlReviewReport |
|
| Field | Type | Label | Description |
| start_position | Position | Position of the SQL statement. |
|
| end_position | Position |
|
| Field | Type | Label | Description |
| statement_types | StatementType | repeated | statement_types are the types of statements that are found in the sql. |
| affected_rows | int64 |
|
| Field | Type | Label | Description |
| name | string | The plan to run plan checks. Format: projects/{project}/plans/{plan} |
|
| spec_id | string | optional | The UUID of the specific spec to run plan checks for. This should match the spec.id field in Plan.Spec. If not set, all specs in the plan will be used. |
| Field | Type | Label | Description |
| plan | Plan | The plan to update. The plan's `name` field is used to identify the plan to update. Format: projects/{project}/plans/{plan} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the plan is not found, a new plan will be created. In this situation, `update_mask` is ignored. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| STATEMENT_ADVISE | 1 | |
| STATEMENT_SUMMARY_REPORT | 2 | |
| GHOST_SYNC | 3 |
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | |
| RUNNING | 1 | |
| DONE | 2 | |
| FAILED | 3 | |
| CANCELED | 4 |
PlanService manages deployment plans for database changes.
| Method Name | Request Type | Response Type | Description |
| GetPlan | GetPlanRequest | Plan | Retrieves a deployment plan by name. Permissions required: bb.plans.get |
| ListPlans | ListPlansRequest | ListPlansResponse | Lists deployment plans in a project. Permissions required: bb.plans.list |
| CreatePlan | CreatePlanRequest | Plan | Creates a new deployment plan. Permissions required: bb.plans.create |
| UpdatePlan | UpdatePlanRequest | Plan | UpdatePlan updates the plan. The plan creator and the user with bb.plans.update permission on the project can update the plan. Permissions required: bb.plans.update (or creator) |
| GetPlanCheckRun | GetPlanCheckRunRequest | PlanCheckRun | Gets the plan check run for a deployment plan. Permissions required: bb.planCheckRuns.get |
| RunPlanChecks | RunPlanChecksRequest | RunPlanChecksResponse | Executes validation checks on a deployment plan. Permissions required: bb.planCheckRuns.run |
| CancelPlanCheckRun | CancelPlanCheckRunRequest | CancelPlanCheckRunResponse | Cancels the plan check run for a deployment plan. Permissions required: bb.planCheckRuns.run |
| Method Name | Method | Pattern | Body |
| GetPlan | GET | /v1/{name=projects/*/plans/*} | |
| ListPlans | GET | /v1/{parent=projects/*}/plans | |
| CreatePlan | POST | /v1/{parent=projects/*}/plans | plan |
| UpdatePlan | PATCH | /v1/{plan.name=projects/*/plans/*} | plan |
| GetPlanCheckRun | GET | /v1/{name=projects/*/plans/*/planCheckRun} | |
| RunPlanChecks | POST | /v1/{name=projects/*/plans/*}:runPlanChecks | * |
| CancelPlanCheckRun | POST | /v1/{name=projects/*/plans/*/planCheckRun}:cancel | * |
ReviewRuleType is the standard review rule set. The rules are fixed:
every project gets them without configuration, and the only setting is a
switch (see ReviewRulePolicy).
A rule id names what the rule examines. An execution check is named for
what it checks; a rule about the SQL itself carries REQUIRE or DISALLOW so
the id says which way it cuts. DISALLOW on a P1 rule means the operation
needs a person's acceptance, not that it is forbidden.
| Name | Number | Description |
| REVIEW_RULE_TYPE_UNSPECIFIED | 0 | |
| SYNTAX | 1 | P0: the statements do not parse for the target engine. It gates the other rules (see ReviewRulePolicy). |
| WALK_THROUGH | 2 | P0: applying the statements to the synced schema fails: a missing table or column, a duplicate object, or an invalid reference. |
| ONLINE_MIGRATION | 3 | P0: the change requests online migration but is not eligible. |
| PRIOR_BACKUP | 4 | P0: the change enables prior backup but the backup cannot be taken. |
| REQUIRE_IS_NULL | 5 | P0: = NULL or <> NULL in a predicate, which is always false. Test for NULL with IS NULL or IS NOT NULL. |
| REQUIRE_WHERE | 6 | P1: UPDATE or DELETE without WHERE. |
| DISALLOW_DROP_OBJECT | 7 | P1: dropping any object, such as a table, column, view, index, sequence, schema, database, or function. Dropping a constraint is DISALLOW_DROP_CONSTRAINT. |
| DISALLOW_TRUNCATE | 8 | P1: TRUNCATE. |
| DISALLOW_DROP_CONSTRAINT | 9 | P1: dropping a PRIMARY KEY, FOREIGN KEY, UNIQUE, or CHECK constraint. |
| DISALLOW_RENAME | 10 | P1: renaming a table, foreign table, view, materialized view, or column. |
| REQUIRE_PRIMARY_KEY | 11 | P1: the change creates a table without a primary key, or drops a primary key without adding one back. A table that already lacked a primary key before the change is not reported. |
| Field | Type | Label | Description |
| roles | string | repeated | The roles required for approval in order. |
| Field | Type | Label | Description |
| flow | ApprovalFlow | The approval flow definition. |
|
| title | string | The title of the approval template. |
|
| description | string | The description of the approval template. |
| Field | Type | Label | Description |
| name | string | The name of the issue to add an approver. Format: projects/{project}/issues/{issue} |
|
| comment | string | The comment explaining the approval decision. |
| Field | Type | Label | Description |
| parent | string | The parent resource shared by all issues being updated. Format: projects/{project} If the operation spans parents, a dash (-) may be accepted as a wildcard. We only support updating the status of databases for now. |
|
| issues | string | repeated | The list of issues to update. Format: projects/{project}/issues/{issue} |
| status | IssueStatus | The new status. |
|
| reason | string | The reason for the status change. |
| Field | Type | Label | Description |
| parent | string | The issue name Format: projects/{project}/issues/{issue} |
|
| issue_comment | IssueComment | The comment to create. |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of issues. Format: projects/{project} |
|
| issue | Issue | The issue to create. |
| Field | Type | Label | Description |
| name | string | The name of the issue to retrieve. Format: projects/{project}/issues/{issue} |
|
| force | bool | If set to true, bypass cache and fetch the latest data. |
| Field | Type | Label | Description |
| name | string | The name of the review run to retrieve. Format: projects/{project}/issues/{issue}/reviewRuns/{reviewRun} |
| Field | Type | Label | Description |
| name | string | The name of the issue. Format: projects/{project}/issues/{issue} |
|
| title | string | The title of the issue. |
|
| description | string | The description of the issue. |
|
| type | Issue.Type |
|
|
| status | IssueStatus | The status of the issue. |
|
| approvers | Issue.Approver | repeated |
|
| approval_template | ApprovalTemplate | The approval template for the issue. |
|
| creator | string | Format: users/hello@world.com |
|
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
|
| plan | string | The plan associated with the issue. Can be empty. Format: projects/{project}/plans/{plan} |
|
| role_grant | RoleGrant | Used if the issue type is ROLE_GRANT. |
|
| risk_level | RiskLevel | The risk level of the issue. |
|
| labels | string | repeated | Labels attached to the issue for categorization and filtering. |
| approval_status | ApprovalStatus | The overall approval status for the issue. |
|
| access_grant | string | The access grant associated with this issue. Format: projects/{project}/accessGrants/{access_grant} |
|
| draft | bool | Whether this issue is a Draft Review Issue. |
Approvers and their approval status for the issue.
| Field | Type | Label | Description |
| status | Issue.Approver.Status | The new status. |
|
| principal | string | Format: users/hello@world.com |
A comment on an issue.
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/issues/{issue}/issueComments/{issueComment-uid} |
|
| comment | string | The text content of the comment. |
|
| payload | string | TODO: use struct message instead. |
|
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
|
| creator | string | Format: users/{email} |
|
| root | string | optional | The thread root's name, set only on replies. Immutable after creation. Format: projects/{project}/issues/{issue}/issueComments/{issueComment} Must name a thread root in the same issue, never a general comment or reply. |
| thread_state | IssueComment.ThreadState | optional | Present only on thread roots. Set OPEN on create to start a thread; an anchored root starts one without it. Omit root, thread_state, and statement_anchor to create a general comment. Update through the thread_state field mask to resolve or reopen. Adding a reply does not reopen a resolved thread. |
| statement_anchor | StatementAnchor | Optional source context on a root or reply. A reply's anchor must share the root's spec and sheet_sha256; it may narrow the range. Cannot be set on events. Immutable after creation. |
|
| review_metadata | IssueComment.ReviewMetadata | Present on review results, the comments the review executor posts. Never accepted on create or update. |
|
| approval | IssueComment.Approval | Approval event. |
|
| issue_update | IssueComment.IssueUpdate | Issue update event. |
|
| plan_update | IssueComment.PlanUpdate | Plan update event. |
|
| review_submission | IssueComment.ReviewSubmission | Review submission event. |
Approval event information.
| Field | Type | Label | Description |
| status | IssueComment.Approval.Status | The approval status. |
Issue update event information.
| Field | Type | Label | Description |
| from_title | string | optional |
|
| to_title | string | optional |
|
| from_description | string | optional |
|
| to_description | string | optional |
|
| from_status | IssueStatus | optional |
|
| to_status | IssueStatus | optional |
|
| from_labels | string | repeated |
|
| to_labels | string | repeated |
|
Plan update event information (snapshot of plan.config.specs before
and after a PlanService.UpdatePlan call that mutated specs).
| Field | Type | Label | Description |
| from_specs | Plan.Spec | repeated |
|
| to_specs | Plan.Spec | repeated |
|
What a review result carries beyond its text.
| Field | Type | Label | Description |
| run_type | ReviewRun.Type | The reviewer that posted the result. |
|
| rule_type | ReviewRuleType | The rule judged against. Set if and only if run_type is RULE. |
|
| priority | IssueComment.ReviewMetadata.Priority |
|
|
| targets | string | repeated | Every database the result applies to, sorted. Format: instances/{instance}/databases/{database} |
| superseded | bool | A later run of the same reviewer has completed, so the result is not from the latest review, whatever its thread state. |
Review submission event information.
| Field | Type | Label | Description |
| parent | string | Format: projects/{projects}/issues/{issue} |
|
| page_size | int32 | The maximum number of issue comments to return. The service may return fewer than this value. If unspecified, at most 10 issue comments will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListIssueComments` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListIssueComments` must match the call that provided the page token. |
|
| filter | string | CEL filter over events, root comments, and replies. Supported: root == null, root == "<comment name>", or root in ["<comment name>", ...]. Root names must belong to parent. Empty and root == null return the timeline (events and root comments); other filters return replies only. |
| Field | Type | Label | Description |
| issue_comments | IssueComment | repeated | The issue comments from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of issues. Format: projects/{project} |
|
| page_size | int32 | The maximum number of issues to return. The service may return fewer than this value. If unspecified, at most 10 issues will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListIssues` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListIssues` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter issues returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filters: - creator: issue creator full name in "users/{email or id}" format, support "==" operator. - status: the issue status, support "==" and "in" operator, check the IssueStatus enum for the values. - create_time: issue create time in "2006-01-02T15:04:05Z07:00" format, support ">=" or "<=" operator. - type: the issue type, support "==" and "in" operator, check the Type enum in the Issue message for the values. - labels: the issue labels, support "==" and "in" operator. - risk_level: the issue risk level, support "in" operator, check the RiskLevel enum for the values. - approval_status: issue approval status, support "==" operator. - current_approver: the issue approver, should in "users/{email} format", support "==" operator. For example: creator == "users/ed@bytebase.com" && status in ["OPEN", "DONE"] status == "CANCELED" && type == "DATABASE_CHANGE" labels in ["label1", "label2"] risk_level in ["HIGH", "MODERATE"] create_time >= "2025-01-02T15:04:05Z07:00" |
|
| query | string | Query is the query statement. |
|
| order_by | string | The order by of issues. Support: - create_time - update_time The default sorting order is ascending. For example: - order_by = "create_time desc" - order_by = "update_time asc" |
| Field | Type | Label | Description |
| issues | Issue | repeated | The issues from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | The name of the issue to add a rejection. Format: projects/{project}/issues/{issue} |
|
| comment | string | The comment explaining the rejection decision. |
| Field | Type | Label | Description |
| name | string | The name of the issue to request a issue. Format: projects/{project}/issues/{issue} |
|
| comment | string | The comment explaining the request. |
| Field | Type | Label | Description |
| name | string | The name of the issue whose approval-finding should be retried. Format: projects/{project}/issues/{issue} |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/issues/{issue}/reviewRuns/{reviewRun} The {reviewRun} id is the reviewer: "rule" or "ai". The name addresses a slot, not an execution. |
|
| type | ReviewRun.Type | Derived from the name. |
|
| status | ReviewRun.Status |
|
|
| create_time | google.protobuf.Timestamp | When the current run was triggered. Reset on every re-run. |
|
| end_time | google.protobuf.Timestamp | When the run reached a terminal status. Unset while AVAILABLE or RUNNING. |
|
| error | string | Fatal execution error, set if and only if status is FAILED: the review failed to execute (a platform problem, never the SQL — SQL problems are review results on a DONE run). |
|
| outdated | bool | Whether the plan's SQL changed after this run started, so the run reviews an earlier version of it. The server starts a new run before it creates the rollout automatically. |
| Field | Type | Label | Description |
| role | string | The requested role. Format: roles/{role}. |
|
| user | string | The user to be granted. Format: users/{email}. |
|
| condition | google.type.Expr | The condition for the role. Same as the condition in IAM Binding message. |
|
| expiration | google.protobuf.Duration | The duration for which the grant is valid. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/issues/{issue}/reviewRuns/{reviewRun} |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of issues. Format: projects/{project} Use the wildcard "projects/-" to search across collections (AIP-159); the result is restricted to the projects where the caller holds bb.issues.get. For a concrete project, the caller must hold bb.issues.get on that project or the request is denied. |
|
| page_size | int32 | The maximum number of issues to return. The service may return fewer than this value. If unspecified, at most 10 issues will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `SearchIssues` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchIssues` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter issues returned in the list. Check the filter field in the ListIssuesRequest message. |
|
| query | string | Query is the query statement. |
|
| order_by | string | The order by of issues. Support: - create_time - update_time The default sorting order is ascending. For example: - order_by = "create_time desc" - order_by = "update_time asc" |
| Field | Type | Label | Description |
| issues | Issue | repeated | The issues from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
The saved statement revision and range referenced by a comment.
Source currency is derived by comparing the spec and hash with the current plan.
Historical SQL is available through SheetService.GetSheet with this hash.
| Field | Type | Label | Description |
| spec | string | The Plan.Spec.id in the issue's plan; may no longer resolve after deletion. |
|
| sheet_sha256 | string | SHA256 of the saved sheet, as 64 lowercase hexadecimal characters. |
|
| start_position | Position | One-based lines and Unicode code-point columns. When both columns are zero, the range covers whole lines, including the end line. Otherwise both columns must be positive, start_position is inclusive, and end_position is exclusive. |
|
| end_position | Position |
|
| Field | Type | Label | Description |
| parent | string | The issue name Format: projects/{project}/issues/{issue} |
|
| issue_comment | IssueComment | The comment to update. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the issue comment is not found, a new issue comment will be created. In this situation, `update_mask` is ignored. |
| Field | Type | Label | Description |
| issue | Issue | The issue to update. The issue's `name` field is used to identify the issue to update. Format: projects/{project}/issues/{issue} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the issue is not found, a new issue will be created. In this situation, `update_mask` is ignored. |
The approval status of an approver.
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | Unspecified status. |
| PENDING | 1 | Awaiting approval. |
| APPROVED | 2 | Approved. |
| REJECTED | 3 | Rejected. |
The type of issue.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified issue type. |
| DATABASE_CHANGE | 1 | Database schema or data change. |
| ROLE_GRANT | 2 | Role grant request. |
| ACCESS_GRANT | 4 | Temporary access grant request. |
Approval status values.
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | Unspecified status. |
| PENDING | 1 | Approval pending. |
| APPROVED | 2 | Approved. |
| REJECTED | 3 | Rejected. |
Priority says what resolving the thread means. It has no bearing on
blocking, which thread_state alone decides.
| Name | Number | Description |
| PRIORITY_UNSPECIFIED | 0 | |
| P0 | 1 | The SQL is wrong and must change. |
| P1 | 2 | Dangerous but legitimate; a person must accept it. |
| P2 | 3 | Advisory. |
| Name | Number | Description |
| THREAD_STATE_UNSPECIFIED | 0 | |
| OPEN | 1 | |
| RESOLVED | 2 |
States follow task_run, minus PENDING (review needs no admission
control) and minus CANCELED (runs are side-effect-free until the fenced
completion transaction, so re-running supersedes instead of canceling).
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | |
| AVAILABLE | 1 | Created and claimable by any replica. |
| RUNNING | 2 | |
| DONE | 3 | Every (spec, target) unit in the reviewer's scope was evaluated. RULE's scope is every target. AI's scope is the project's CI sample, the first ci_sampling_size targets of each spec, or every target when ci_sampling_size is 0. DONE does not mean the review passed: whether problems remain is judged from open comments. |
| FAILED | 4 | At least one unit was not evaluated; the cause is in `error`. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| RULE | 1 | Review against the standard rules. |
| AI | 2 | Review against the natural-language AI review policy, performed by a model. |
IssueService manages issues for tracking database changes and tasks.
| Method Name | Request Type | Response Type | Description |
| GetIssue | GetIssueRequest | Issue | Retrieves an issue by name. Permissions required: bb.issues.get |
| CreateIssue | CreateIssueRequest | Issue | Creates a new issue for database changes or tasks. Permissions required: bb.issues.create |
| ListIssues | ListIssuesRequest | ListIssuesResponse | Lists issues in a project. Permissions required: bb.issues.list |
| SearchIssues | SearchIssuesRequest | SearchIssuesResponse | Search for issues that the caller has the bb.issues.get permission on and also satisfy the specified filter & query. Permissions required: bb.issues.get |
| UpdateIssue | UpdateIssueRequest | Issue | Updates an issue's properties such as title, description, or labels. Permissions required: bb.issues.update |
| ListIssueComments | ListIssueCommentsRequest | ListIssueCommentsResponse | Lists comments on an issue. Permissions required: bb.issueComments.list |
| CreateIssueComment | CreateIssueCommentRequest | IssueComment | Adds a comment to an issue. Permissions required: bb.issueComments.create |
| UpdateIssueComment | UpdateIssueCommentRequest | IssueComment | Updates an existing issue comment. Permissions required: bb.issueComments.update |
| BatchUpdateIssuesStatus | BatchUpdateIssuesStatusRequest | BatchUpdateIssuesStatusResponse | Updates the status of multiple issues in a single operation. Permissions required: bb.issues.update |
| ApproveIssue | ApproveIssueRequest | Issue | Approves an issue. Access determined by approval flow configuration - caller must be a designated approver for the current approval step. Permissions required: None (determined by approval flow) |
| RejectIssue | RejectIssueRequest | Issue | Rejects an issue. Access determined by approval flow configuration - caller must be a designated approver for the current approval step. Permissions required: None (determined by approval flow) |
| RequestIssue | RequestIssueRequest | Issue | Requests changes on an issue. Access determined by approval flow configuration - caller must be a designated approver for the current approval step. Permissions required: None (determined by approval flow) |
| RetryIssueApproval | RetryIssueApprovalRequest | Issue | Re-runs approval-template finding for an issue stuck in CHECKING. Useful when the synchronous post-create finding errored (e.g. against a malformed workspace approval rule) and the operator has since corrected it — without this, the issue would remain in CHECKING indefinitely because there is no other retry path for non-DATABASE_CHANGE issue types. Idempotent: returns the existing issue unchanged when approval-finding has already completed. Permissions required: None (caller must be the issue creator; mirrors RequestIssue's authorization model). |
| GetReviewRun | GetReviewRunRequest | ReviewRun | Gets the current run of one reviewer on an issue. The run carries execution status only; review results are issue comments. A reviewer that has never run on the issue is NOT_FOUND. Permissions required: bb.reviewRuns.get |
| RunReview | RunReviewRequest | ReviewRun | Triggers a review run. The slot is reset unconditionally: a RUNNING execution is superseded (its completion is fenced off), the attempt number is bumped, and the returned run is AVAILABLE. Review results are not returned by this RPC: they are posted as issue comments. The returned run carries execution status only, and GetReviewRun reads it back. The audit log is the only record of who triggered a run. Permissions required: bb.reviewRuns.run |
| Method Name | Method | Pattern | Body |
| GetIssue | GET | /v1/{name=projects/*/issues/*} | |
| CreateIssue | POST | /v1/{parent=projects/*}/issues | issue |
| ListIssues | GET | /v1/{parent=projects/*}/issues | |
| SearchIssues | POST | /v1/{parent=projects/*}/issues:search | * |
| UpdateIssue | PATCH | /v1/{issue.name=projects/*/issues/*} | issue |
| ListIssueComments | GET | /v1/{parent=projects/*/issues/*}/issueComments | |
| CreateIssueComment | POST | /v1/{parent=projects/*/issues/*}:comment | issue_comment |
| UpdateIssueComment | PATCH | /v1/{parent=projects/*/issues/*}:comment | issue_comment |
| BatchUpdateIssuesStatus | POST | /v1/{parent=projects/*}/issues:batchUpdateStatus | * |
| ApproveIssue | POST | /v1/{name=projects/*/issues/*}:approve | * |
| RejectIssue | POST | /v1/{name=projects/*/issues/*}:reject | * |
| RequestIssue | POST | /v1/{name=projects/*/issues/*}:request | * |
| RetryIssueApproval | POST | /v1/{name=projects/*/issues/*}:retryApproval | * |
| GetReviewRun | GET | /v1/{name=projects/*/issues/*/reviewRuns/*} | |
| RunReview | POST | /v1/{name=projects/*/issues/*/reviewRuns/*}:run | * |
| Field | Type | Label | Description |
| enabled | bool |
|
|
| provider | AISetting.Provider |
|
|
| endpoint | string |
|
|
| api_key | string |
|
|
| model | string |
|
|
| version | string |
|
|
| sql_review_enabled | bool | Whether the AI SQL review may run. It is off by default and is a consent of its own beside `enabled`: a review sends the statements of a change to the provider, and can send the schema of its target databases and their table statistics. |
| Field | Type | Label | Description |
| full_mask | Algorithm.FullMask |
|
|
| range_mask | Algorithm.RangeMask |
|
|
| md5_mask | Algorithm.MD5Mask |
|
|
| inner_outer_mask | Algorithm.InnerOuterMask |
|
| Field | Type | Label | Description |
| substitution | string | substitution is the string used to replace the original value, the max length of the string is 16 bytes. |
| Field | Type | Label | Description |
| prefix_len | int32 |
|
|
| suffix_len | int32 |
|
|
| type | Algorithm.InnerOuterMask.MaskType |
|
|
| substitution | string |
|
| Field | Type | Label | Description |
| salt | string | salt is the salt value to generate a different hash that with the word alone. |
| Field | Type | Label | Description |
| slices | Algorithm.RangeMask.Slice | repeated | We store it as a repeated field to face the fact that the original value may have multiple parts should be masked. But frontend can be started with a single rule easily. |
| Field | Type | Label | Description |
| start | int32 | start is the start character index (0-based) of the original value, should be less than end. Uses character indices (not byte offsets) for display-oriented masking. Example: For "你好world", character index 2 refers to 'w' (the 3rd character). |
|
| end | int32 | end is the end character index (exclusive) of the original value. Uses character indices (not byte offsets) for display-oriented masking. |
|
| substitution | string | substitution is the string used to replace the OriginalValue[start:end). |
| Field | Type | Label | Description |
| text | string | The text of announcement |
|
| link | string | The optional link, user can follow the link to check extra details |
|
| theme | Announcement.AnnouncementTheme | Banner colors. Built-in presets (info/warning/critical) are a frontend-only concept that seeds these colors; the store only holds them. |
| Field | Type | Label | Description |
| background | google.type.Color |
|
|
| text | google.type.Color |
|
| Field | Type | Label | Description |
| settings | AppIMSetting.IMSetting | repeated |
|
| Field | Type | Label | Description |
| client_id | string |
|
|
| client_secret | string |
|
|
| robot_code | string |
|
| Field | Type | Label | Description |
| app_id | string |
|
|
| app_secret | string |
|
| Field | Type | Label | Description |
| type | WebhookType |
|
|
| slack | AppIMSetting.Slack |
|
|
| feishu | AppIMSetting.Feishu |
|
|
| wecom | AppIMSetting.Wecom |
|
|
| lark | AppIMSetting.Lark |
|
|
| dingtalk | AppIMSetting.DingTalk |
|
|
| teams | AppIMSetting.Teams |
|
| Field | Type | Label | Description |
| app_id | string |
|
|
| app_secret | string |
|
| Field | Type | Label | Description |
| token | string |
|
| Field | Type | Label | Description |
| tenant_id | string | Azure AD tenant ID (Directory ID). |
|
| client_id | string | Azure AD application (client) ID. |
|
| client_secret | string | Azure AD client secret. |
| Field | Type | Label | Description |
| corp_id | string |
|
|
| agent_id | string |
|
|
| secret | string |
|
| Field | Type | Label | Description |
| configs | DataClassificationSetting.DataClassificationConfig | repeated |
|
| Field | Type | Label | Description |
| id | string | id is the uuid for classification. Each project can chose one classification config. |
|
| title | string |
|
|
| levels | DataClassificationSetting.DataClassificationConfig.Level | repeated | levels is user defined level list for classification. |
| classification | DataClassificationSetting.DataClassificationConfig.ClassificationEntry | repeated | classification is the id - DataClassification map. The id should in [0-9]+-[0-9]+-[0-9]+ format. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | DataClassificationSetting.DataClassificationConfig.DataClassification |
|
| Field | Type | Label | Description |
| id | string | id is the classification id in [0-9]+-[0-9]+-[0-9]+ format. |
|
| title | string |
|
|
| level | int32 | optional | The sensitivity level. Maps to Level.level. |
| Field | Type | Label | Description |
| title | string |
|
|
| level | int32 | The numeric level for ordering. Higher = more sensitive. |
| Field | Type | Label | Description |
| from | string |
|
|
| from_name | string |
|
|
| type | EmailSetting.Type |
|
|
| smtp | EmailSetting.SMTPConfig |
|
| Field | Type | Label | Description |
| host | string |
|
|
| port | int32 |
|
|
| username | string |
|
|
| password | string |
|
|
| encryption | EmailSetting.SMTPConfig.Encryption |
|
|
| authentication | EmailSetting.SMTPConfig.Authentication |
|
| Field | Type | Label | Description |
| environments | EnvironmentSetting.Environment | repeated |
|
| Field | Type | Label | Description |
| name | string | The resource name of the environment. Format: environments/{environment}. Output only. |
|
| id | string | The resource id of the environment. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/. |
|
| title | string | The display name of the environment. |
|
| tags | EnvironmentSetting.Environment.TagsEntry | repeated |
|
| color | google.type.Color |
|
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
ExportSetting holds each export destination provider's credentials.
| Field | Type | Label | Description |
| sharepoint | SharePointSetting | Unset when SharePoint is not configured. |
The request message for getting a setting.
| Field | Type | Label | Description |
| name | string | The resource name of the setting. |
The response message for getting a setting.
| Field | Type | Label | Description |
| setting | Setting |
|
| Field | Type | Label | Description |
| settings | Setting | repeated | The settings from the specified request. |
MCPSetting is what an MCP (Model Context Protocol) session may do in this
workspace.
| Field | Type | Label | Description |
| capability | MCPSetting.Capability | The maximum capability available to MCP sessions in this workspace, acting as an admin-set ceiling. Enforced server-side at three points: the /mcp endpoint decides whether a connection is admitted at all, the ceiling gate on the internal MCP chain decides, per request, which method classes are served, and under READ_ONLY the SQL clamp decides, per statement, whether it only reads. |
| Field | Type | Label | Description |
| id | string |
|
|
| name | string |
|
|
| monaco_base | string |
|
|
| tokens | SQLEditorThemeSetting.TokensEntry | repeated | CSS token colors. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | google.type.Color |
|
| Field | Type | Label | Description |
| types | SemanticTypeSetting.SemanticType | repeated |
|
| Field | Type | Label | Description |
| id | string | id is the uuid for semantic type. |
|
| title | string | the title of the semantic type, it should not be empty. |
|
| description | string | the description of the semantic type, it can be empty. |
|
| algorithm | Algorithm |
|
|
| icon | string | icon is the icon for semantic type, it can be emoji or base64 encoded image. |
The schema of setting.
| Field | Type | Label | Description |
| name | string | The resource name of the setting. Format: settings/{setting} Example: "settings/SEMANTIC_TYPES" |
|
| value | SettingValue | The configuration value of the setting. |
The data in setting value.
| Field | Type | Label | Description |
| app_im | AppIMSetting |
|
|
| workspace_profile | WorkspaceProfileSetting |
|
|
| workspace_approval | WorkspaceApprovalSetting |
|
|
| data_classification | DataClassificationSetting |
|
|
| semantic_type | SemanticTypeSetting |
|
|
| ai | AISetting |
|
|
| environment | EnvironmentSetting |
|
|
| EmailSetting |
|
||
| mcp | MCPSetting |
|
|
| export | ExportSetting |
|
SharePointSetting is the Microsoft Entra application that uploads exports to
SharePoint. It is granted access per library by the customer's SharePoint
administrators.
| Field | Type | Label | Description |
| tenant_id | string | The Microsoft Entra tenant (directory) ID. |
|
| client_id | string | The application (client) ID. |
|
| client_secret | string | The client secret. It is never returned. |
|
| client_secret_set | bool | Whether a client secret is stored. |
| Field | Type | Label | Description |
| parent | string |
|
|
| email_setting | EmailSetting |
|
|
| to | string |
|
| Field | Type | Label | Description |
| success | bool |
|
|
| error | string |
|
The request message for updating or creating a setting.
| Field | Type | Label | Description |
| setting | Setting | The setting to update. |
|
| validate_only | bool | validate_only is a flag to indicate whether to validate the setting value, server would not persist the setting value if it is true. |
|
| allow_missing | bool |
|
|
| update_mask | google.protobuf.FieldMask |
|
| Field | Type | Label | Description |
| rules | WorkspaceApprovalSetting.Rule | repeated |
|
| Field | Type | Label | Description |
| template | ApprovalTemplate |
|
|
| condition | google.type.Expr | The condition that is associated with the rule. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec The `source` field filters which rules apply. The `condition` field then evaluates with full context. All supported variables: statement.affected_rows: affected row count in the DDL/DML, support "==", "!=", "<", "<=", ">", ">=" operations. statement.table_rows: table row count number, support "==", "!=", "<", "<=", ">", ">=" operations. resource.environment_id: the environment resource id, support "==", "!=", "in [xx]", "!(in [xx])" operations. resource.project_id: the project resource id, support "==", "!=", "in [xx]", "!(in [xx])", "contains()", "matches()", "startsWith()", "endsWith()" operations. resource.db_engine: the database engine type, support "==", "!=", "in [xx]", "!(in [xx])" operations. Check the Engine enum for values. statement.sql_type: the SQL type, support "==", "!=", "in [xx]", "!(in [xx])" operations. resource.database_name: the database name, support "==", "!=", "in [xx]", "!(in [xx])", "contains()", "matches()", "startsWith()", "endsWith()" operations. resource.schema_name: the schema name, support "==", "!=", "in [xx]", "!(in [xx])", "contains()", "matches()", "startsWith()", "endsWith()" operations. resource.table_name: the table name, support "==", "!=", "in [xx]", "!(in [xx])", "contains()", "matches()", "startsWith()", "endsWith()" operations. statement.text: the SQL statement, support "contains()", "matches()", "startsWith()", "endsWith()" operations. request.expiration_days: the role expiration days for the request, support "==", "!=", "<", "<=", ">", ">=" operations. request.role: the request role full name, support "==", "!=", "in [xx]", "!(in [xx])", "contains()", "matches()", "startsWith()", "endsWith()" operations. When source is CHANGE_DATABASE, support: statement.*, resource.* (excluding request.*) When source is CREATE_DATABASE, support: resource.environment_id, resource.project_id, resource.db_engine, resource.database_name When source is REQUEST_ROLE, support: resource.project_id, request.expiration_days, request.role When source is REQUEST_ACCESS, support: resource.environment_id, resource.project_id, resource.db_engine, resource.database_name, resource.schema_name, resource.table_name, request.unmask, request.data_export For examples: resource.environment_id == "prod" && statement.affected_rows >= 100 resource.table_name.matches("sensitive_.*") && resource.db_engine == "MYSQL" |
|
| source | WorkspaceApprovalSetting.Rule.Source |
|
| Field | Type | Label | Description |
| external_url | string | The external URL is used for sso authentication callback. |
|
| disallow_signup | bool | Disallow self-service signup, users can only be invited by the owner. |
|
| require_mfa | bool | Require MFA for all users. |
|
| refresh_token_duration | google.protobuf.Duration | The duration for refresh token. Default is 7 days. |
|
| announcement | Announcement | The setting of custom announcement |
|
| maximum_request_expiration | google.protobuf.Duration | The max expiration duration for data access requests. |
|
| domains | string | repeated | The workspace domain, e.g., bytebase.com. |
| enforce_identity_domain | bool | Only user and group from the domains can be created and login. |
|
| database_change_mode | DatabaseChangeMode | The workspace database change mode. |
|
| disallow_password_signin | bool | Whether password sign-in is disabled for all end users. |
|
| enable_metric_collection | bool | Whether to enable metric collection for the workspace. |
|
| inactive_session_timeout | google.protobuf.Duration | The session expiration time if not activity detected for the user. Value <= 0 means no limit. |
|
| enable_audit_log_stdout | bool | Whether to enable audit logging to stdout in structured JSON format. Requires TEAM or ENTERPRISE license. |
|
| watermark | bool | Whether to display watermark on pages. Requires ENTERPRISE license. |
|
| password_restriction | WorkspaceProfileSetting.PasswordRestriction | Password restriction settings. |
|
| access_token_duration | google.protobuf.Duration | The duration for access token. Default is 1 hour. |
|
| enable_debug | bool | Whether debug mode is enabled. |
|
| sql_result_size | int64 | The maximum result size limit in bytes for query and export, works for the SQL Editor and Export Center. The default value is 100MB, we will use the default value if the setting not exists, or the limit <= 0. |
|
| query_timeout | google.protobuf.Duration | The query timeout duration for query and export, works for the SQL Editor and Export Center. |
|
| allow_email_code_signin | bool | Allow signin/signup using email + a 6-digit one-time verification code. Requires the EMAIL setting to be configured on the workspace. |
|
| sql_editor_theme_id | string | Enforced SQL Editor theme id: OPAQUE — a frontend-resolved built-in preset id OR a custom theme's uuid. Empty ⇒ default light. |
|
| sql_editor_custom_theme | SQLEditorThemeSetting | The enforced CUSTOM theme's full definition — present ONLY when sql_editor_theme_id is a custom uuid. tokens is always complete. |
|
| maximum_role_expiration | google.protobuf.Duration | The max expiration duration for request role. Deprecated: use just-in-time access request flows instead. |
|
| directory_sync_token_configured | bool | Whether a directory sync token has been generated for this workspace. The token itself is never returned; this only lets the UI decide between offering "generate" and "regenerate". |
| Field | Type | Label | Description |
| min_length | int32 | min_length is the minimum password length. It must be at least 8. |
|
| require_number | bool | require_number requires the password to contain at least one number. |
|
| require_letter | bool | require_letter requires the password to contain at least one letter, either uppercase or lowercase. |
|
| require_uppercase_letter | bool | require_uppercase_letter requires the password to contain at least one uppercase letter. |
|
| require_special_character | bool | require_special_character requires the password to contain at least one special character. |
|
| require_reset_password_for_first_login | bool | require_reset_password_for_first_login requires users to change their password after their first login. |
|
| password_rotation | google.protobuf.Duration | password_rotation requires users to change their password after the duration. |
| Name | Number | Description |
| PROVIDER_UNSPECIFIED | 0 | |
| OPEN_AI | 1 | |
| CLAUDE | 2 | |
| GEMINI | 3 | |
| AZURE_OPENAI | 4 |
| Name | Number | Description |
| MASK_TYPE_UNSPECIFIED | 0 | |
| INNER | 1 | |
| OUTER | 2 |
| Name | Number | Description |
| DATABASE_CHANGE_MODE_UNSPECIFIED | 0 | |
| PIPELINE | 1 | A more advanced database change process, including custom approval workflows and other advanced features. Default to this mode. |
| EDITOR | 2 | A simple database change process in SQL editor. Users can execute SQL directly. |
| Name | Number | Description |
| AUTHENTICATION_UNSPECIFIED | 0 | |
| AUTHENTICATION_NONE | 1 | |
| PLAIN | 2 | |
| LOGIN | 3 | |
| CRAM_MD5 | 4 |
| Name | Number | Description |
| ENCRYPTION_UNSPECIFIED | 0 | |
| ENCRYPTION_NONE | 1 | |
| STARTTLS | 2 | |
| SSL_TLS | 3 |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| SMTP | 1 |
Capability is the ceiling: a session runs at this level or lower.
Writing CAPABILITY_UNSPECIFIED, explicitly or by leaving
value.mcp.capability out of the update mask, is rejected.
| Name | Number | Description |
| CAPABILITY_UNSPECIFIED | 0 | |
| DISABLED | 1 | MCP connections are rejected. |
| READ_ONLY | 3 | MCP may inspect metadata and run read-only queries. A session opens, and what it may do is decided per method by the capability gate and per statement by the SQL clamp: a request holding a statement that is not a read is refused whole, and where the engine's driver has one the database session is opened read-only as well. |
| READ_WRITE | 4 | MCP may perform mutations, still bounded by the user's RBAC. |
| Name | Number | Description |
| SETTING_NAME_UNSPECIFIED | 0 | |
| WORKSPACE_PROFILE | 1 | |
| WORKSPACE_APPROVAL | 2 | |
| APP_IM | 3 | |
| AI | 4 | |
| DATA_CLASSIFICATION | 5 | |
| SEMANTIC_TYPES | 6 | |
| ENVIRONMENT | 7 | |
| 8 | ||
| MCP | 9 | |
| EXPORT | 10 |
| Name | Number | Description |
| SOURCE_UNSPECIFIED | 0 | |
| CHANGE_DATABASE | 1 | |
| CREATE_DATABASE | 2 | |
| REQUEST_ROLE | 4 | |
| REQUEST_ACCESS | 5 |
SettingService manages workspace-level settings and configurations.
| Method Name | Request Type | Response Type | Description |
| ListSettings | ListSettingsRequest | ListSettingsResponse | Lists all workspace settings. Permissions required: bb.settings.list |
| GetSetting | GetSettingRequest | Setting | Retrieves a workspace setting by name. Permissions required: bb.settings.get |
| UpdateSetting | UpdateSettingRequest | Setting | Updates a workspace setting. Permissions required: bb.settings.set |
| TestEmailSetting | TestEmailSettingRequest | TestEmailSettingResponse | Sends a test email using the provided config (without persisting). Permissions required: bb.settings.set |
| Method Name | Method | Pattern | Body |
| ListSettings | GET | /v1/settings | |
| GetSetting | GET | /v1/{name=settings/*} | |
| UpdateSetting | PATCH | /v1/{setting.name=settings/*} | setting |
| TestEmailSetting | POST | /v1/{parent=workspaces/*}/settings/EMAIL:test | * |
System information and configuration for the Bytebase instance.
Actuator concept is similar to the Spring Boot Actuator.
| Field | Type | Label | Description |
| version | string | The Bytebase server version. |
|
| git_commit | string | The git commit hash of the build. |
|
| saas | bool | Whether the Bytebase instance is running in SaaS mode where some features cannot be edited by users. |
|
| external_url | string | The external URL where users or webhook callbacks access Bytebase. |
|
| last_active_time | google.protobuf.Timestamp | The last time any API call was made, refreshed on each request. |
|
| workspace | string | The unique identifier for the workspace. Format: workspaces/{id} |
|
| unlicensed_features | string | repeated | List of features that are not licensed. |
| activated_instance_count | int32 | The number of activated database instances. |
|
| total_instance_count | int32 | The total number of database instances. |
|
| external_url_from_flag | bool | Whether the external URL is set via command-line flag (and thus cannot be changed via UI). |
|
| replica_count | int32 | The number of active replicas (servers sharing the same database). |
|
| default_project | string | The default project for unassigned databases. Format: projects/{id} |
|
| user_count_in_iam | int32 | The number of users in the workspace IAM (for seat limit display). |
|
| active_vcs_user_count | int32 | The number of active VCS users seen in the active window. |
|
| sample | SampleInfo | Sample setup availability and provisioned resources. |
|
| mcp_setting | MCPSetting | The MCP (Model Context Protocol) setting in the current workspace. |
|
| ai_enabled | bool | Whether the workspace AI setting enables the AI agent. |
|
| ai_sql_review_enabled | bool | Whether the workspace AI setting switches the AI SQL review on. A review also needs `ai_enabled`. |
Request message for getting actuator information.
SampleInfo describes sample setup availability and provisioned resources.
| Field | Type | Label | Description |
| available | bool | Whether sample setup is currently available. |
|
| instances | SampleInfo.Instance | repeated | The provisioned sample instances. |
Instance describes one provisioned sample instance.
| Field | Type | Label | Description |
| instance | string | The provisioned sample instance. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| expire_time | google.protobuf.Timestamp | The time when the provisioned sample instance expires. |
ActuatorService manages system health and operational information.
| Method Name | Request Type | Response Type | Description |
| GetActuatorInfo | GetActuatorInfoRequest | ActuatorInfo | Gets system information and health status of the Bytebase instance. The workspace is resolved from the authenticated session. Permissions required: None (authentication required) |
| Method Name | Method | Pattern | Body |
| GetActuatorInfo | GET | /v1/actuator/info |
A single message in the conversation.
| Field | Type | Label | Description |
| role | AIChatMessageRole | The role of the message sender. |
|
| content | string | optional | The text content of the message. Optional for assistant messages that only contain tool calls. |
| tool_calls | AIChatToolCall | repeated | Tool calls made by the assistant. Only present in assistant messages. |
| tool_call_id | string | optional | The ID of the tool call this message is responding to. Only present in tool messages. |
Request message for AIService.Chat.
| Field | Type | Label | Description |
| messages | AIChatMessage | repeated | The conversation messages. |
| tool_definitions | AIChatToolDefinition | repeated | The tool definitions available to the AI. |
Response message for AIService.Chat.
| Field | Type | Label | Description |
| content | string | optional | The text content of the AI response. Optional when the response only contains tool calls. |
| tool_calls | AIChatToolCall | repeated | Tool calls the AI wants to make. |
| usage | AIChatUsage | optional | Token usage for this provider call, when available. |
| stop_reason | AIChatResponse.StopReason | Why the model stopped. A truncated or blocked response can still carry content. |
A tool call made by the AI.
| Field | Type | Label | Description |
| id | string | The unique ID of this tool call. |
|
| name | string | The name of the tool to call. |
|
| arguments | string | The JSON-encoded arguments to pass to the tool. |
|
| metadata | string | optional | Opaque provider-specific metadata (e.g., Gemini thought_signature). Frontend must echo this back unchanged when sending tool results. |
A tool definition that the AI can invoke.
| Field | Type | Label | Description |
| name | string | The name of the tool. |
|
| description | string | A description of what the tool does. |
|
| parameters_schema | string | The JSON Schema describing the tool's parameters. |
Token usage for a single AI provider call.
| Field | Type | Label | Description |
| total_tokens | int32 | Total tokens used by the provider call. |
Role of a chat message.
| Name | Number | Description |
| AI_CHAT_MESSAGE_ROLE_UNSPECIFIED | 0 | Unspecified role. |
| AI_CHAT_MESSAGE_ROLE_SYSTEM | 1 | System message providing instructions. |
| AI_CHAT_MESSAGE_ROLE_USER | 2 | User message. |
| AI_CHAT_MESSAGE_ROLE_ASSISTANT | 3 | Assistant (AI) message. |
| AI_CHAT_MESSAGE_ROLE_TOOL | 4 | Tool result message. |
Why the model stopped generating a response.
| Name | Number | Description |
| STOP_REASON_UNSPECIFIED | 0 | The provider did not report why the model stopped. |
| TURN_COMPLETED | 1 | The model completed its turn with an answer or with tool calls. |
| TOKEN_LIMIT | 2 | The response was truncated at a token limit and is incomplete. |
| BLOCKED | 3 | The provider blocked the request or the response, or the model refused to answer. |
| MALFORMED_TOOL_CALL | 4 | The model generated a tool call that the provider could not parse. |
| OTHER | 5 | The model stopped for a reason that no other value names. |
AIService provides AI chat capabilities for the page agent.
| Method Name | Request Type | Response Type | Description |
| Chat | AIChatRequest | AIChatResponse | Chat sends a conversation with tool definitions to the configured AI provider and returns the AI response. |
| Method Name | Method | Pattern | Body |
| Chat | POST | /v1/ai/chat | * |
Binding associates members with a role and optional conditions.
| Field | Type | Label | Description |
| role | string | The role that is assigned to the members. Format: roles/{role} |
|
| members | string | repeated | Specifies the principals requesting access for a Bytebase resource. For users, the member should be: user:{email} For groups, the member should be: group:{email} For service accounts, the member should be: serviceAccount:{email} For workload identities, the member should be: workloadIdentity:{email} |
| condition | google.type.Expr | The condition that is associated with this binding, only used in the project IAM policy. If the condition evaluates to true, then this binding applies to the current request. If the condition evaluates to false, then this binding does not apply to the current request. However, a different role binding might grant the same role to one or more of the principals in this binding. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Support variables: resource.database: the canonical database full name in "instances/{instance}/databases/{database}" or "projects/{project}/instances/{instance}/databases/{database}" format, used by any role with SQL Editor read (e.g. "roles/sqlEditorUser", "roles/sqlEditorReadUser"), export (bb.sql.export, e.g. "roles/sqlEditorExporter") or write (bb.sql.ddl / bb.sql.dml) access, support "==" operator. resource.schema_name: the schema name, used by any role with SQL Editor read, export (bb.sql.export) or write (bb.sql.ddl / bb.sql.dml) access; for writes it is evaluated per write-target table, support "==" operator. resource.table_name: the table name, used by any role with SQL Editor read, export (bb.sql.export) or write (bb.sql.ddl / bb.sql.dml) access; for writes it is evaluated per write-target table, support "==" operator. resource.environment_id: the environment to allow the DDL/DML operation in the SQL Editor, only works for the role with bb.sql.ddl or bb.sql.dml permissions. Support "in" operator. request.time: the expiration. Only support "<" operation in `request.time < timestamp("{ISO datetime string format}")`. Known limitations of table/schema-scoped DDL/DML grants: - The scope only gates the write target, not the read sources of a write: e.g. `INSERT INTO granted_table SELECT * FROM other_table` may read `other_table` without a grant on it, so a table-scoped write grant is not an exfiltration boundary. - It must be paired with a database/project-level read grant: a table-scoped grant alone does not satisfy the SQL Editor query method permission (bb.databases.get). - A resource.schema_name-scoped grant only authorizes a write whose schema is unambiguous — qualify the table (schema.table) or select the schema for the SQL Editor session. An unqualified write whose effective schema cannot be determined ahead of execution is denied (qualify it, or use a table-only grant). - Multi-statement batches are authorized at the database level: an earlier statement can rebind the session's default schema or database mid-batch, so per-table/schema scoping is dropped and a table/schema-scoped grant requires a database-level grant. The database-level check is still per target database — a qualified cross-database write is gated by a grant on its own database, not the request database — but an unqualified write whose session default is rebound mid-batch is evaluated against the database it literally names, so qualify cross-database writes or run them as single statements. - A write target in a different project than the SQL-Editor session's database is denied: the per-target check evaluates the session project's IAM policy, so a cross-project write is failed closed (to write it, open the SQL Editor on a database in the target project). - Enforcement is on the statement's literal write target; writes routed elsewhere by a view/synonym, or into a temporary schema (e.g. pg_temp), are evaluated against what the statement names, not the ultimate base object. - Write-target gating uses an ALLOWLIST of statement types the resolver models. It does NOT cover every syntactically-identifiable cross-database write; statement types off the allowlist are authorized against the request database. The allowlist is: - Modeled table/data writes (per-table/schema-scopable): INSERT/UPDATE/DELETE/TRUNCATE/MERGE, LOAD DATA, IMPORT INTO, CREATE TABLE AS / SELECT INTO, and table-level CREATE/DROP/ALTER/RENAME/index. - Modeled non-table object DDL (gated at the DATABASE level by the object's own explicit database/schema qualifier; an unqualified name keeps the request-database check): CREATE/ALTER/DROP of view, procedure/function/routine, trigger, sequence, synonym, type, and (Oracle) package and cluster; plus Oracle ALTER/DROP MATERIALIZED VIEW (Oracle CREATE MATERIALIZED VIEW is not modeled — see below). NOT modeled (these fall back to the request-database check, so a qualified cross-database one is authorized against the request database): MySQL CREATE TRIGGER and CREATE/ALTER/DROP EVENT (bare-string AST names); MSSQL ALTER of view/procedure/function/trigger (no ALTER node in the grammar); Oracle CREATE MATERIALIZED VIEW and the niche object DDL — dimension, attribute dimension, hierarchy, analytic view, JSON duality view, materialized zonemap, operator, in-memory join group, property graph, vector index, index type, domain; COPY ... FROM; and engine-specific bulk-load / deprecated text writes. A structural "write-target object database" extraction layer to remove this allowlist dependence is tracked as a follow-up. - Out of scope (read sources / indirect effects): the tables a write READS (INSERT … SELECT, MERGE … USING, CREATE TABLE AS … SELECT) and objects reached indirectly via views/synonyms/function bodies/triggers are NOT gated. Invariant: for a statement ON the modeled allowlist that explicitly names a different database as its write target, the ACL uses that target database, not the request database. Statement types OFF the allowlist are authorized against the request database. For example: resource.database == "instances/local-pg/databases/postgres" && resource.schema_name in ["public","another_schema"] resource.database == "instances/local-pg/databases/bytebase" && resource.schema_name == "public" && resource.table_name in ["audit_log"] resource.database == "instances/local-pg/databases/postgres" && resource.environment_id in ["test"] request.time < timestamp("2025-04-26T11:24:48.655Z") |
|
| parsed_expr | google.api.expr.v1alpha1.Expr | The parsed expression of the condition. |
A single change to a binding.
| Field | Type | Label | Description |
| action | BindingDelta.Action | The action that was performed on a Binding. |
|
| role | string | Role that is assigned to `members`. For example, `roles/projectOwner`. |
|
| member | string | Follows the same format of Binding.members. |
|
| condition | google.type.Expr | The condition that is associated with this binding. |
Request message for getting an IAM policy.
| Field | Type | Label | Description |
| resource | string | The name of the resource to get the IAM policy. Format: projects/{project} Format: workspaces/{workspace} |
IAM policy that binds members to roles.
| Field | Type | Label | Description |
| bindings | Binding | repeated | Collection of binding. A binding binds one or more project members to a single project role. |
| etag | string | The current etag of the policy, returned by GetIamPolicy and SetIamPolicy. Sending it back on SetIamPolicy makes the write conditional: if the policy changed since the read, the call returns ABORTED. Omitting it applies the write unconditionally, overwriting any concurrent change (AIP-154). |
Describes changes between two IAM policies.
| Field | Type | Label | Description |
| binding_deltas | BindingDelta | repeated | The delta for Bindings between two policies. |
Request message for setting an IAM policy.
| Field | Type | Label | Description |
| resource | string | The name of the resource to set the IAM policy. Format: projects/{project} Format: workspaces/{workspace} |
|
| policy | IamPolicy |
|
|
| etag | string | The current etag of the policy. Equivalent to setting `policy.etag`; supplying both with different values returns INVALID_ARGUMENT. |
Type of action performed on a binding.
| Name | Number | Description |
| ACTION_UNSPECIFIED | 0 | Unspecified action. |
| ADD | 1 | Add a binding. |
| REMOVE | 2 | Remove a binding. |
Additional audit data specific to certain operations.
| Field | Type | Label | Description |
| policy_delta | PolicyDelta | Changes to IAM policies. |
Audit log entry recording system activity or API call.
| Field | Type | Label | Description |
| name | string | The name of the log. Formats: - projects/{project}/auditLogs/{uid} - workspaces/{workspace}/auditLogs/{uid} |
|
| create_time | google.protobuf.Timestamp | The timestamp when the audit log was created. |
|
| actor | string | The principal who performed the action. Formats: users/{email}, serviceAccounts/{email}, or workloadIdentities/{email} |
|
| method | string | The method or action being audited. For example: /bytebase.v1.SQLService/Query or bb.project.repository.push |
|
| severity | AuditLog.Severity | The severity level of this audit log entry. |
|
| resource | string | The resource associated with this audit log. |
|
| request | string | The request payload in JSON format. |
|
| response | string | The response payload in JSON format. Some fields may be omitted if they are too large or contain sensitive information. |
|
| status | google.rpc.Status | The status of the operation. |
|
| latency | google.protobuf.Duration | The duration of the operation. |
|
| service_data | google.protobuf.Any | Service-specific metadata about the request, response, and activities. |
|
| request_metadata | RequestMetadata | Metadata about the request context. |
|
| mcp_delegation | MCPDelegation | MCP delegation provenance. Present exactly when the audited call arrived through the MCP server's delegated credential; never set for public API calls. Presence of this message is the MCP-origin marker. |
Request message for exporting audit logs.
| Field | Type | Label | Description |
| parent | string |
|
|
| filter | string | The filter of the log. It should be a valid CEL expression. Check the filter field in the SearchAuditLogsRequest message. |
|
| order_by | string | The order by of the log. Only support order by create_time. The default sorting order is ascending. For example: - order_by = "create_time asc" - order_by = "create_time desc" |
|
| format | ExportFormat | The export format. |
|
| page_size | int32 | The maximum number of logs to return. The service may return fewer than this value. If unspecified, at most 10 log entries will be returned. The maximum value is 5000; values above 5000 will be coerced to 5000. |
|
| page_token | string | A page token, received from a previous `ExportAuditLogs` call. Provide this to retrieve the subsequent page. |
Response message for exporting audit logs.
| Field | Type | Label | Description |
| content | bytes | The exported audit log content in the requested format. |
|
| next_page_token | string | A token to retrieve next page of log entities. Pass this value in the page_token field in the subsequent call to retrieve the next page of log entities. |
Provenance of a call that reached the API through the MCP (Model Context
Protocol) server's delegated credential. The values are copied verbatim from
the verified credential's grant state; empty fields record that the grant
stored nothing (legacy sessions), never a resolved or synthesized value.
| Field | Type | Label | Description |
| scope | string | The OAuth2 grant's consented scope, e.g. "mcp:read-only". Empty when the grant recorded no scope. |
|
| resource | string | The grant's stored MCP resource URI. Empty for pre-grant legacy sessions. |
|
| client_id | string | The OAuth2 client the grant was consented to. Empty for legacy web-session tokens at /mcp. |
|
| correlation_id | string | Correlates the audit rows an MCP session produces. Minted at the /mcp boundary and session-scoped: the MCP SDK hands tool handlers the initialize-time context, so one MCP session carries one correlation ID across all of its tool calls. |
Metadata about the incoming request.
| Field | Type | Label | Description |
| caller_ip | string | The IP address of the request originator. |
|
| caller_supplied_user_agent | string | The user agent string provided by the caller. This is supplied by the client and is not authenticated. |
Request message for searching audit logs.
| Field | Type | Label | Description |
| parent | string |
|
|
| filter | string | The filter of the log. It should be a valid CEL expression. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - method: the API name, can be found in the docs. Usually "/bytebase.v1.…", for example "/bytebase.v1.UserService/CreateUser"; entries written outside the v1 API carry their own prefix, such as "/bytebase.mcp.Session/Authorize" or "/bytebase.cli.Recovery/ResetUserPassword". Support "==" operator. - resource: the resource the entry is about, support "==" operator. - severity: support "==" operator, check Severity enum in AuditLog message for values. - actor: the actor, in users/{email}, serviceAccounts/{email}, or workloadIdentities/{email} format. Support "==" operator. - create_time: support ">=" and "<=" operator. - mcp: true selects the entries MCP produced, false the rest. A boolean, not a string. Support "==" operator. - mcp_correlation_id: the MCP session an entry belongs to, taken from an entry's mcp_delegation.correlation_id. Support "==" operator. Entries MCP produced outside a session — a refused connection or consent — carry none and match no value here. For example: - filter = "method == '/bytebase.v1.SQLService/Query'" - filter = "method == '/bytebase.v1.SQLService/Query' && severity == 'ERROR'" - filter = "method == '/bytebase.v1.SQLService/Query' && severity == 'ERROR' && actor == 'users/bb@bytebase.com'" - filter = "method == '/bytebase.v1.SQLService/Query' && severity == 'ERROR' && create_time <= '2021-01-01T00:00:00Z' && create_time >= '2020-01-01T00:00:00Z'" - filter = "mcp == true" - filter = "mcp_correlation_id == '0b7f1a3c-1d2e-4f56-8a90-1b2c3d4e5f60'" |
|
| order_by | string | The order by of the log. Only support order by create_time. The default sorting order is ascending. For example: - order_by = "create_time asc" - order_by = "create_time desc" |
|
| page_size | int32 | The maximum number of logs to return. The service may return fewer than this value. If unspecified, at most 10 log entries will be returned. The maximum value is 5000; values above 5000 will be coerced to 5000. |
|
| page_token | string | A page token, received from a previous `SearchLogs` call. Provide this to retrieve the subsequent page. |
Response message for searching audit logs.
| Field | Type | Label | Description |
| audit_logs | AuditLog | repeated |
|
| next_page_token | string | A token to retrieve next page of log entities. Pass this value in the page_token field in the subsequent call to retrieve the next page of log entities. |
Severity level for audit log entries.
| Name | Number | Description |
| SEVERITY_UNSPECIFIED | 0 | Unspecified severity level. |
| DEBUG | 1 | Debug-level information. |
| INFO | 2 | Informational messages. |
| NOTICE | 3 | Notable events. |
| WARNING | 4 | Warning conditions. |
| ERROR | 5 | Error conditions. |
| CRITICAL | 6 | Critical conditions. |
| ALERT | 7 | Action must be taken immediately. |
| EMERGENCY | 8 | System is unusable. |
AuditLogService manages audit logs for system activities and API calls.
| Method Name | Request Type | Response Type | Description |
| SearchAuditLogs | SearchAuditLogsRequest | SearchAuditLogsResponse | Searches audit logs with optional filtering and pagination. Permissions required: bb.auditLogs.search |
| ExportAuditLogs | ExportAuditLogsRequest | ExportAuditLogsResponse | Exports audit logs in a specified format for external analysis. Permissions required: bb.auditLogs.export |
| Method Name | Method | Pattern | Body |
| SearchAuditLogs | POST | /v1/{parent=projects/*}/auditLogs:search | * |
| SearchAuditLogs | POST | /v1/auditLogs:search | * |
| ExportAuditLogs | POST | /v1/{parent=projects/*}/auditLogs:export | * |
| ExportAuditLogs | POST | /v1/auditLogs:export | * |
| Field | Type | Label | Description |
| identity_provider | IdentityProvider | The identity provider to create. |
|
| identity_provider_id | string | The ID to use for the identity provider, which will become the final component of the identity provider's resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/. |
|
| validate_only | bool | If set to true, the request will be validated without actually creating the identity provider. |
| Field | Type | Label | Description |
| name | string | The name of the identity provider to delete. Format: idps/{identity_provider} |
FieldMapping saves the field names from user info API of identity provider.
As we save all raw json string of user info response data into `principal.idp_user_info`,
we can extract the relevant data based with `FieldMapping`.
| Field | Type | Label | Description |
| identifier | string | Identifier is the field name of the unique identifier in 3rd-party idp user info. Required. |
|
| display_name | string | DisplayName is the field name of display name in 3rd-party idp user info. Optional. |
|
| phone | string | Phone is the field name of primary phone in 3rd-party idp user info. Optional. |
|
| groups | string | Groups is the field name of groups in 3rd-party idp user info. Optional. Mainly used for OIDC: https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/ |
| Field | Type | Label | Description |
| name | string | The name of the identity provider to retrieve. Format: idps/{idp} |
| Field | Type | Label | Description |
| name | string | The name of the identity provider. Format: idps/{idp} |
|
| title | string | The display title of the identity provider. |
|
| domain | string | The domain for email matching when using this identity provider. |
|
| type | IdentityProviderType | The type of identity provider protocol. |
|
| config | IdentityProviderConfig | The configuration details for the identity provider. |
| Field | Type | Label | Description |
| oauth2_config | OAuth2IdentityProviderConfig | OAuth2 protocol configuration. |
|
| oidc_config | OIDCIdentityProviderConfig | OIDC protocol configuration. |
|
| ldap_config | LDAPIdentityProviderConfig | LDAP protocol configuration. |
LDAPIdentityProviderConfig is the structure for LDAP identity provider config.
| Field | Type | Label | Description |
| host | string | Host is the hostname or IP address of the LDAP server, e.g., "ldap.example.com". |
|
| port | int32 | Port is the port number of the LDAP server, e.g., 389. When not set, the default port of the corresponding security protocol will be used, i.e. 389 for StartTLS and 636 for LDAPS. |
|
| skip_tls_verify | bool | SkipTLSVerify controls whether to skip TLS certificate verification. |
|
| bind_dn | string | BindDN is the DN of the user to bind as a service account to perform search requests. |
|
| bind_password | string | BindPassword is the password of the user to bind as a service account. |
|
| base_dn | string | BaseDN is the base DN to search for users, e.g., "ou=users,dc=example,dc=com". |
|
| user_filter | string | UserFilter is the filter to search for users, e.g., "(uid=%s)". |
|
| security_protocol | LDAPIdentityProviderConfig.SecurityProtocol | SecurityProtocol is the security protocol to be used for establishing connections with the LDAP server. |
|
| field_mapping | FieldMapping | FieldMapping is the mapping of the user attributes returned by the LDAP server. |
| Field | Type | Label | Description |
| username | string | The username of a directory user, substituted into the user filter. |
|
| password | string | The password of the directory user. |
| Field | Type | Label | Description |
| parent | string | The parent workspace whose identity providers should be listed. It must be the workspace the caller's credential belongs to. Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| identity_providers | IdentityProvider | repeated | The identity providers from the specified request. |
OAuth2IdentityProviderConfig is the structure for OAuth2 identity provider config.
| Field | Type | Label | Description |
| auth_url | string | The authorization endpoint URL for OAuth2 flow. |
|
| token_url | string | The token endpoint URL for exchanging authorization code. |
|
| user_info_url | string | The user information endpoint URL. |
|
| client_id | string | The OAuth2 client identifier. |
|
| client_secret | string | The OAuth2 client secret for authentication. |
|
| scopes | string | repeated | The list of OAuth2 scopes to request. |
| field_mapping | FieldMapping | Mapping configuration for user attributes from OAuth2 response. |
|
| skip_tls_verify | bool | Whether to skip TLS certificate verification. |
|
| auth_style | OAuth2AuthStyle | The authentication style for client credentials. |
| Field | Type | Label | Description |
| code | string | Authorize code from website. |
OIDCIdentityProviderConfig is the structure for OIDC identity provider config.
| Field | Type | Label | Description |
| issuer | string | The OIDC issuer URL for the identity provider. |
|
| client_id | string | The OIDC client identifier. |
|
| client_secret | string | The OIDC client secret for authentication. |
|
| scopes | string | repeated | The scopes that the OIDC provider supports. Should be fetched from the well-known configuration file of the OIDC provider. |
| field_mapping | FieldMapping | Mapping configuration for user attributes from OIDC claims. |
|
| skip_tls_verify | bool | Whether to skip TLS certificate verification. |
|
| auth_style | OAuth2AuthStyle | The authentication style for client credentials. |
|
| auth_endpoint | string | The authorization endpoint of the OIDC provider. Should be fetched from the well-known configuration file of the OIDC provider. |
| Field | Type | Label | Description |
| code | string | Authorize code from OIDC provider. |
| Field | Type | Label | Description |
| identity_provider | IdentityProvider | The identity provider to test connection including uncreated. |
|
| oauth2_context | OAuth2IdentityProviderTestRequestContext |
|
|
| oidc_context | OIDCIdentityProviderTestRequestContext | OIDC authentication context for test connection. |
|
| ldap_context | LDAPIdentityProviderTestRequestContext | LDAP credentials context for test connection. |
| Field | Type | Label | Description |
| claims | TestIdentityProviderResponse.ClaimsEntry | repeated | The map of claims returned by the identity provider. |
| user_info | TestIdentityProviderResponse.UserInfoEntry | repeated | The matched user info from the claims. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| identity_provider | IdentityProvider | The identity provider to update. The identity provider's `name` field is used to identify the identity provider to update. Format: idps/{identity_provider} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the identity provider is not found, a new identity provider will be created. In this situation, `update_mask` is ignored. |
| Name | Number | Description |
| IDENTITY_PROVIDER_TYPE_UNSPECIFIED | 0 | Unspecified identity provider type. |
| OAUTH2 | 1 | OAuth 2.0 authentication protocol. |
| OIDC | 2 | OpenID Connect authentication protocol. |
| LDAP | 3 | LDAP directory service authentication. |
| Name | Number | Description |
| SECURITY_PROTOCOL_UNSPECIFIED | 0 | |
| START_TLS | 1 | StartTLS is the security protocol that starts with an unencrypted connection and then upgrades to TLS. |
| LDAPS | 2 | LDAPS is the security protocol that uses TLS from the beginning. |
| Name | Number | Description |
| OAUTH2_AUTH_STYLE_UNSPECIFIED | 0 | |
| IN_PARAMS | 1 | IN_PARAMS sends the "client_id" and "client_secret" in the POST body as application/x-www-form-urlencoded parameters. |
| IN_HEADER | 2 | IN_HEADER sends the client_id and client_password using HTTP Basic Authorization. This is an optional style described in the OAuth2 RFC 6749 section 2.3.1. |
IdentityProviderService manages external identity providers for SSO authentication.
| Method Name | Request Type | Response Type | Description |
| GetIdentityProvider | GetIdentityProviderRequest | IdentityProvider | Gets an identity provider by name. Permissions required: bb.identityProviders.get |
| ListIdentityProviders | ListIdentityProvidersRequest | ListIdentityProvidersResponse | Lists the identity providers configured for the caller's workspace. The login page reads AuthService.GetAuthenticationInfo instead, which publishes only the fields a browser needs to start an SSO redirect. Returns the same representation as GetIdentityProvider — secrets redacted, the rest of the configuration included — so granting bb.identityProviders.list conveys configuration read over the whole collection, not merely the names in it. Permissions required: bb.identityProviders.list |
| CreateIdentityProvider | CreateIdentityProviderRequest | IdentityProvider | Creates a new identity provider. Permissions required: bb.identityProviders.create |
| UpdateIdentityProvider | UpdateIdentityProviderRequest | IdentityProvider | Updates an identity provider. Permissions required: bb.identityProviders.update When allow_missing=true, also requires: bb.identityProviders.create |
| DeleteIdentityProvider | DeleteIdentityProviderRequest | .google.protobuf.Empty | Deletes an identity provider. Permissions required: bb.identityProviders.delete |
| TestIdentityProvider | TestIdentityProviderRequest | TestIdentityProviderResponse | Tests the connection and configuration of an identity provider. Permissions required: bb.identityProviders.update |
| Method Name | Method | Pattern | Body |
| GetIdentityProvider | GET | /v1/{name=idps/*} | |
| ListIdentityProviders | GET | /v1/idps | |
| ListIdentityProviders | GET | /v1/{parent=workspaces/*}/idps | |
| CreateIdentityProvider | POST | /v1/idps | identity_provider |
| UpdateIdentityProvider | PATCH | /v1/{identity_provider.name=idps/*} | identity_provider |
| DeleteIdentityProvider | DELETE | /v1/{name=idps/*} | |
| TestIdentityProvider | POST | /v1/idps/*:test | * |
| Field | Type | Label | Description |
| names | string | repeated | The user names to retrieve. Format: users/{email} |
| Field | Type | Label | Description |
| users | User | repeated | One user per requested name, in the same order as `names`. |
| Field | Type | Label | Description |
| name | string | Format: users/{email}. Must be the caller's own name. |
|
| new_password | string |
|
|
| credential | CredentialProof |
|
| Field | Type | Label | Description |
| name | string | Format: users/{email}. Must be the caller's own name. |
|
| pending_version | google.protobuf.Timestamp | The pending_version of the codes being confirmed. Confirming promotes exactly the set this version identifies, or nothing. |
|
| credential | CredentialProof |
|
|
| otp_code | string | Required for first-time enrollment, rejected otherwise. A *fresh* code, not the one EnableMFA took. |
| Field | Type | Label | Description |
| user | User | The user to create. |
One proof that the caller currently controls a credential on the account.
Exactly one field must be set; enforced in the handler.
| Field | Type | Label | Description |
| current_password | string | The account's current password. Refused by a factor-touching method while a live MFA factor exists. |
|
| otp_code | string | A live code from the account's enrolled TOTP authenticator. |
|
| recovery_code | string | A single-use MFA recovery code. |
|
| email_code | string | A one-time code from RequestReauthCode. Bytebase Cloud only, and only while the account has no live MFA factor. |
| Field | Type | Label | Description |
| name | string | The name of the user to delete. Format: users/{email} |
| Field | Type | Label | Description |
| name | string | Format: users/{email}. The caller's own, or another user's with bb.users.update. |
|
| credential | CredentialProof | Required for a self-service call against a live factor, and then only otp_code or recovery_code. Unused on an admin-assisted call. |
| Field | Type | Label | Description |
| name | string | Format: users/{email}. Must be the caller's own name. |
|
| otp_code | string | A code from the authenticator the pending secret was just added to. |
|
| pending_version | google.protobuf.Timestamp | The pending_version this enrollment was minted with. |
|
| credential | CredentialProof | Proof of the *existing* factor, not the new device above. Required for a rotation, and for first-time enrollment on an account with a password. |
| Field | Type | Label | Description |
| name | string | The name of the user to retrieve. Format: users/{email} |
| Field | Type | Label | Description |
| page_size | int32 | The maximum number of users to return. The service may return fewer than this value. If unspecified, at most 10 users will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListUsers` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListUsers` must match the call that provided the page token. |
|
| show_deleted | bool | Show deleted users if specified. |
|
| filter | string | Filter is used to filter users returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - name: the user name, support "==" and ".contains()" operator. - email: the user email, support "==" and ".contains()" operator. - state: check State enum for values, support "==" operator. - project: the project full name in "projects/{id}" format, support "==" operator. For example: name == "ed" name.contains("ed") email == "ed@bytebase.com" email.contains("ed") state == "DELETED" project == "projects/sample-project" You can combine filter conditions like: name.contains("ed") && project == "projects/sample-project" (name == "ed" || email == "ed@bytebase.com") && project == "projects/sample-project" |
| Field | Type | Label | Description |
| users | User | repeated | The users from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | Format: users/{email}. Must be the caller's own name. |
| Field | Type | Label | Description |
| recovery_codes | string | repeated | The pending recovery codes, shown once for the caller to save. |
| pending_version | google.protobuf.Timestamp | Identifies this mint; see StartMFAEnrollmentResponse.pending_version. |
| Field | Type | Label | Description |
| name | string | Format: users/{email}. Must be the caller's own name. |
| Field | Type | Label | Description |
| name | string | Format: users/{email}. Must be the caller's own name. |
| Field | Type | Label | Description |
| otp_secret | string | The pending TOTP secret. The only response that carries it — it is never readable from the User resource. |
|
| recovery_codes | string | repeated | The pending recovery codes, shown once for the caller to save. |
| expire_time | google.protobuf.Timestamp | When this enrollment stops being confirmable. |
|
| pending_version | google.protobuf.Timestamp | Identifies this mint. Echo it back to EnableMFA and ConfirmRecoveryCodes; a mint from another tab or device replaces the pending state, and those methods refuse a version that is no longer the pending one rather than promoting something this caller never saw. |
| Field | Type | Label | Description |
| name | string | The name of the deleted user. Format: users/{email} |
| Field | Type | Label | Description |
| name | string | The name of the user whose email to update. Format: users/{email} Note: This is the current (old) email address. The new email is specified in the 'email' field. |
|
| string | The new email address. |
| Field | Type | Label | Description |
| user | User | The user to update. The user's `name` field is used to identify the user to update. Format: users/{email} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the user is not found, a new user will be created. In this situation, `update_mask` is ignored. |
| Field | Type | Label | Description |
| name | string | The name of the user. Format: users/{email} |
|
| state | State | The lifecycle state of the user account. |
|
| string | The email address of the user, used for login and notifications. |
||
| title | string | The display title or full name of the user. |
|
| password | string | The password for authentication. Only used during user creation or password updates. |
|
| mfa_enabled | bool | Whether the user has a live MFA factor. Set by ConfirmRecoveryCodes and DisableMFA, never by an update. |
|
| phone | string | Should be a valid E.164 compliant phone number. Could be empty. |
|
| profile | User.Profile | User profile metadata. |
|
| groups | string | repeated | The groups for the user. Format: groups/{email} |
| workspace | string | The current workspace. Format: workspaces/{id} |
| Field | Type | Label | Description |
| last_login_time | google.protobuf.Timestamp | The last time the user successfully logged in. |
|
| last_change_password_time | google.protobuf.Timestamp | The last time the user changed their password. |
|
| source | string | source means where the user comes from. For now we support Entra ID SCIM sync, so the source could be Entra ID. |
UserService manages user accounts and authentication.
| Method Name | Request Type | Response Type | Description |
| GetUser | GetUserRequest | User | Get the user. Any authenticated user can get the user. Permissions required: bb.users.get |
| BatchGetUsers | BatchGetUsersRequest | BatchGetUsersResponse | Get the users in batch. Any authenticated user can batch get users. One resource per requested name, in request order. The first name that does not resolve fails the whole call (AIP-231: no partial response). Permissions required: bb.users.get |
| GetCurrentUser | .google.protobuf.Empty | User | Get the current authenticated user. Permissions required: None |
| ListUsers | ListUsersRequest | ListUsersResponse | List all users. Any authenticated user can list users. Permissions required: bb.users.list |
| CreateUser | CreateUserRequest | User | Creates a user in the caller's workspace (admin action, self-hosted only). In SaaS mode, admins should add users via workspace IAM policy instead. Permissions required: bb.users.create |
| UpdateUser | UpdateUserRequest | User | Updates a user. Users can update their own profile, or users with bb.users.update permission can update any user. Note: Email updates are not supported through this API. Use UpdateEmail instead. Permissions required: bb.users.update (or self) |
| DeleteUser | DeleteUserRequest | .google.protobuf.Empty | Deletes a user. Requires bb.users.delete permission with additional validation: the last remaining workspace admin cannot be deleted. Permissions required: bb.users.delete |
| UndeleteUser | UndeleteUserRequest | User | Restores a deleted user. Permissions required: bb.users.undelete |
| UpdateEmail | UpdateEmailRequest | User | Updates a user's email address. Permissions required: bb.users.updateEmail |
| RequestReauthCode | RequestReauthCodeRequest | .google.protobuf.Empty | Sends a one-time code to the caller's own email, usable as CredentialProof.email_code. Bytebase Cloud only, and only while the account has no live MFA factor. Not AuthService.SendEmailLoginCode: that one starts a session, this one proves an existing one. Permissions required: None beyond being signed in as `name`. |
| ChangePassword | ChangePasswordRequest | User | Changes the caller's own password. An administrator resetting someone else's password uses UpdateUser with the `password` mask instead — that is a different operation with a different audit story, even though both end in a new password hash. Permissions required: None beyond being signed in as `name`. |
| StartMFAEnrollment | StartMFAEnrollmentRequest | StartMFAEnrollmentResponse | Mints a pending TOTP secret and recovery codes for the caller's own account and returns them. Nothing goes live until ConfirmRecoveryCodes, so an abandoned enrollment leaves the account exactly as it was. Permissions required: None beyond being signed in as `name`. |
| EnableMFA | EnableMFARequest | User | Verifies an otp_code against the pending enrollment. Nothing is written: this is the step that catches a mistyped authenticator before the caller is shown recovery codes, and promotion happens at ConfirmRecoveryCodes so an account is never MFA-required with codes its owner never saved. Permissions required: None beyond being signed in as `name`. It writes nothing itself, but it is a required step of installing a factor on the account, which is why it is denied on the same grounds as the promotion it precedes. |
| DisableMFA | DisableMFARequest | User | Turns MFA off, clearing the entire MFA config — live and pending state alike. Callers may disable their own; an administrator may disable another user's with bb.users.update, which is how a locked-out user is recovered. Permissions required: bb.users.update, unless `name` is the caller's own. |
| RegenerateRecoveryCodes | RegenerateRecoveryCodesRequest | RegenerateRecoveryCodesResponse | Mints a pending recovery-code set beside the live one and returns it. The old codes keep working until ConfirmRecoveryCodes promotes these, so a caller who closes the page mid-way is not left without any. Permissions required: None beyond being signed in as `name`. |
| ConfirmRecoveryCodes | ConfirmRecoveryCodesRequest | User | Promotes the pending recovery codes. During first-time enrollment this is also where the pending TOTP secret goes live, so the factor and the codes that recover it start existing in the same write. Permissions required: None beyond being signed in as `name`. |
| Method Name | Method | Pattern | Body |
| GetUser | GET | /v1/{name=users/*} | |
| BatchGetUsers | GET | /v1/users:batchGet | |
| GetCurrentUser | GET | /v1/users/me | |
| ListUsers | GET | /v1/users | |
| CreateUser | POST | /v1/users | user |
| UpdateUser | PATCH | /v1/{user.name=users/*} | user |
| DeleteUser | DELETE | /v1/{name=users/*} | |
| UndeleteUser | POST | /v1/{name=users/*}:undelete | * |
| UpdateEmail | POST | /v1/{name=users/*}:updateEmail | * |
| RequestReauthCode | POST | /v1/{name=users/*}:requestReauthCode | * |
| ChangePassword | POST | /v1/{name=users/*}:changePassword | * |
| StartMFAEnrollment | POST | /v1/{name=users/*}:startMFAEnrollment | * |
| EnableMFA | POST | /v1/{name=users/*}:enableMFA | * |
| DisableMFA | POST | /v1/{name=users/*}:disableMFA | * |
| RegenerateRecoveryCodes | POST | /v1/{name=users/*}:regenerateRecoveryCodes | * |
| ConfirmRecoveryCodes | POST | /v1/{name=users/*}:confirmRecoveryCodes | * |
| Field | Type | Label | Description |
| workspace | string | The workspace used for authentication, when one can be resolved. Format: workspaces/{workspace} |
|
| restriction | Restriction | The effective authentication restrictions. |
|
| identity_providers | LoginIdentityProvider | repeated | The identity providers the login page renders, in display order. |
AuthorizationRequest is what a browser needs to start an SSO redirect.
| Field | Type | Label | Description |
| endpoint | string | The OAuth2 auth_url, or the authorization endpoint from the OIDC issuer's discovery document. |
|
| client_id | string | The OAuth2 or OIDC client identifier. |
|
| scopes | string | repeated | The scopes to request. |
| Field | Type | Label | Description |
| token | string | External OIDC token (JWT) from CI/CD platform. |
|
| string | Workload Identity email for identifying which identity to authenticate as. Format: {name}@workload.bytebase.com |
| Field | Type | Label | Description |
| access_token | string | Bytebase access token. |
| Field | Type | Label | Description |
| workspace | string | Optional. The workspace whose authentication policy should be returned. Format: workspaces/{workspace} When unset, self-hosted resolves the singleton workspace and SaaS uses the deployment-level defaults. |
Context for identity provider authentication.
| Field | Type | Label | Description |
| oauth2_context | OAuth2IdentityProviderContext | OAuth2 authentication context. |
|
| oidc_context | OIDCIdentityProviderContext | OpenID Connect authentication context. |
LoginIdentityProvider is an identity provider as the login page sees it.
Deliberately not a view of IdentityProvider: this message is served without
a credential, so every field it exposes is published by hand and no
provider configuration reaches it by default.
| Field | Type | Label | Description |
| name | string | The name of the identity provider. Format: idps/{idp} |
|
| type | IdentityProviderType | The type of identity provider protocol. |
|
| title | string | The display title of the identity provider. |
|
| authorization_request | AuthorizationRequest | The parameters the browser needs to start the authorization redirect. Set for OAUTH2 and OIDC, absent for LDAP, whose bind happens server-side. |
| Field | Type | Label | Description |
| string | User's email address. Bounded so an oversized identity is refused at the edge before any handler runs; the login-attempt lockout keys rows by this value. |
||
| password | string | User's password for authentication. Bounded for abuse only: LDAP directories may accept passwords beyond bcrypt's 72-byte limit, and the local-password path rejects longer inputs itself. |
|
| web | bool | If true, sets access token and refresh token as HTTP-only cookies instead of returning the token in the response body. Use for browser-based clients. |
|
| idp_name | string | The name of the identity provider. Format: idps/{idp} |
|
| idp_context | IdentityProviderContext | The idp_context is used to get the user information from identity provider. |
|
| otp_code | string | optional | The otp_code is used to verify the user's identity by MFA. |
| recovery_code | string | optional | The recovery_code is used to recovery the user's identity with MFA. |
| mfa_temp_token | string | optional | The mfa_temp_token is used to verify the user's identity by MFA. |
| email_code | string | optional | 6-digit code from email for passwordless login/signup. Pairs with `email`. Mutually exclusive with `password` and `idp_name`. |
| workspace | string | optional | Preferred workspace to land in after login. If the user is a member of this workspace, the token is issued for it; otherwise falls back to the default resolution (last login workspace → first membership). Typically populated from the ?workspace= query parameter in invite links. Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| token | string | Access token for authenticated requests. Only returned when web=false. For web=true, the token is set as an HTTP-only cookie. |
|
| mfa_temp_token | string | optional | Temporary token for MFA verification. |
| require_reset_password | bool | Whether user must reset password before continuing. |
|
| user | User | The user from the successful login. |
Request to logout current user session.
OAuth2 authentication context.
| Field | Type | Label | Description |
| code | string | Authorization code from OAuth2 provider. |
OpenID Connect authentication context.
| Field | Type | Label | Description |
| code | string | Authorization code from OIDC provider. |
Request to refresh the access token.
Response from refreshing the access token.
| Field | Type | Label | Description |
| string | The email address of the account to reset. Bounded so an oversized identity is refused at the edge before any handler runs; the login-attempt lockout keys rows by this value. |
||
| workspace | string | optional | Optional workspace context captured at send time, used to locate the EMAIL setting, and later (at verify time) for signup gate checks and workspace assignment. Unset for SaaS brand-new signup (no workspace exists yet). Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| string | The email address of the account. Bounded so an oversized identity is refused at the edge before any handler runs; the login-attempt lockout keys rows by this value. |
||
| code | string | The 6-digit code from the reset email. |
|
| new_password | string | The new password to set. |
| Field | Type | Label | Description |
| disallow_signup | bool | Whether self-service user signup is disabled. |
|
| disallow_password_signin | bool | Whether password sign-in is disabled for all end users. |
|
| password_restriction | WorkspaceProfileSetting.PasswordRestriction | Password complexity and restriction requirements. |
|
| allow_email_code_signin | bool | Whether email + 6-digit code signin is enabled for this workspace. |
|
| password_reset_enabled | bool | Whether password reset via email is available for this workspace. True when the workspace (or deployment) has an email setting configured. |
| Field | Type | Label | Description |
| string | The email address to send the code to. Bounded so an oversized identity is refused at the edge before any handler runs; the login-attempt lockout keys rows by this value. |
||
| workspace | string | optional | Optional workspace context captured at send time, used to locate the EMAIL setting, and later (at verify time) for signup gate checks and workspace assignment. Unset for SaaS brand-new signup (no workspace exists yet). Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| string | The email for the new account. Bounded so an oversized identity is refused at the edge before any handler runs; the login-attempt lockout keys rows by this value. |
||
| password | string | The password for the new account. |
|
| title | string | The display name of the user. |
| Field | Type | Label | Description |
| workspace | string | The target workspace to switch to. Format: workspaces/{workspace} |
|
| web | bool | If true, sets tokens as HTTP-only cookies (browser clients). |
|
| otp_code | string | optional | OTP code for MFA verification. Required if the target workspace enforces MFA. |
| recovery_code | string | optional | Recovery code for MFA verification (alternative to otp_code). |
| mfa_temp_token | string | optional | Temporary MFA token from a previous SwitchWorkspace call that returned mfa_temp_token. |
AuthService handles user authentication operations.
| Method Name | Request Type | Response Type | Description |
| GetAuthenticationInfo | GetAuthenticationInfoRequest | AuthenticationInfo | Gets everything the login page renders: the sign-in restrictions and the identity providers it offers. Permissions required: None |
| Login | LoginRequest | LoginResponse | Authenticates a user and returns access tokens. Permissions required: None |
| Logout | LogoutRequest | .google.protobuf.Empty | Logs out the current user session. Permissions required: None |
| ExchangeToken | ExchangeTokenRequest | ExchangeTokenResponse | Exchanges an external OIDC token for a Bytebase access token. Used by CI/CD pipelines with Workload Identity Federation. Permissions required: None (validates via OIDC token) |
| Signup | SignupRequest | LoginResponse | Registers a new user account. Creates a principal and assigns a workspace: - If the user's email was pre-invited to a workspace, joins that workspace. - Otherwise, creates a new workspace with the user as admin. Returns access tokens so the user is logged in immediately after signup. |
| Refresh | RefreshRequest | RefreshResponse | Refreshes the access token using the refresh token cookie. Permissions required: None (validates via refresh token cookie) |
| SwitchWorkspace | SwitchWorkspaceRequest | LoginResponse | Switches the current user's active workspace and issues new tokens. The user must be a member of the target workspace. |
| RequestPasswordReset | RequestPasswordResetRequest | .google.protobuf.Empty | Requests a password reset email for the given email address. Always returns success to avoid leaking whether the email exists. Requires the workspace's SMTP mail delivery setting; without it the recovery route is an admin password reset. Permissions required: None |
| ResetPassword | ResetPasswordRequest | .google.protobuf.Empty | Resets the user's password using a password reset token from email. Permissions required: None (validates via token) |
| SendEmailLoginCode | SendEmailLoginCodeRequest | .google.protobuf.Empty | Sends a 6-digit verification code to the email for login/signup. Always returns success (no email enumeration). Enforces 60-sec resend cooldown. The signed-in counterpart is UserService.RequestReauthCode; LOGIN and REAUTH codes are not interchangeable. Permissions required: None |
| Method Name | Method | Pattern | Body |
| GetAuthenticationInfo | GET | /v1/auth/info | |
| GetAuthenticationInfo | GET | /v1/{workspace=workspaces/*}/auth/info | |
| Login | POST | /v1/auth/login | * |
| Logout | POST | /v1/auth/logout | * |
| ExchangeToken | POST | /v1/auth:exchangeToken | * |
| Signup | POST | /v1/auth/signup | * |
| Refresh | POST | /v1/auth/refresh | * |
| SwitchWorkspace | POST | /v1/auth:switchWorkspace | * |
| RequestPasswordReset | POST | /v1/auth:requestPasswordReset | * |
| ResetPassword | POST | /v1/auth:resetPassword | * |
| SendEmailLoginCode | POST | /v1/auth:sendEmailLoginCode | * |
Request message for batch deparsing CEL expressions.
| Field | Type | Label | Description |
| expressions | google.api.expr.v1alpha1.Expr | repeated | The CEL expression ASTs to deparse. |
Response message for batch deparsing CEL expressions.
| Field | Type | Label | Description |
| expressions | string | repeated | The deparsed CEL expressions as strings. |
Request message for batch parsing CEL expressions.
| Field | Type | Label | Description |
| expressions | string | repeated | The CEL expression strings to parse. |
Response message for batch parsing CEL expressions.
| Field | Type | Label | Description |
| expressions | google.api.expr.v1alpha1.Expr | repeated | The parsed CEL expressions as AST. |
CelService manages CEL (Common Expression Language) parsing and formatting operations.
| Method Name | Request Type | Response Type | Description |
| BatchParse | BatchParseRequest | BatchParseResponse | Parses multiple CEL expression strings into AST representations. Permissions required: None |
| BatchDeparse | BatchDeparseRequest | BatchDeparseResponse | Converts multiple CEL AST representations back into expression strings. Permissions required: None |
| Method Name | Method | Pattern | Body |
| BatchParse | POST | /v1/cel/batchParse | * |
| BatchDeparse | POST | /v1/cel/batchDeparse | * |
| Field | Type | Label | Description |
| name | string | Format: instances/{instance}/databases/{database}/changelogs/{changelog} or projects/{project}/instances/{instance}/databases/{database}/changelogs/{changelog} |
|
| create_time | google.protobuf.Timestamp |
|
|
| status | Changelog.Status |
|
|
| schema | string |
|
|
| schema_size | int64 |
|
|
| task_run | string | Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
|
| plan_title | string | The title of the plan associated with this changelog's task run. This field is populated by deriving the plan from task_run for display purposes. |
| Field | Type | Label | Description |
| name | string | The name of the changelog to retrieve. Format: instances/{instance}/databases/{database}/changelogs/{changelog} or projects/{project}/instances/{instance}/databases/{database}/changelogs/{changelog} |
|
| view | ChangelogView |
|
| Field | Type | Label | Description |
| parent | string | The parent of the changelogs. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| page_size | int32 | The maximum number of changelogs to return. The service may return fewer than this value. If unspecified, at most 10 changelogs will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from the previous call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided must match the call that provided the page token. |
|
| view | ChangelogView |
|
|
| filter | string | Filter is used to filter changelogs returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - status: the changelog status, support "==" operation. check Changelog.Status for available values. - has_schema_snapshot: filters to changelogs with a schema snapshot; only "has_schema_snapshot == true" is supported. - create_time: the changelog create time in RFC 3339 format, supports ">=", "<=", or "<" operator. Example: status == "DONE" status == "FAILED" has_schema_snapshot == true && create_time < "2024-01-02T00:00:00Z" |
| Field | Type | Label | Description |
| changelogs | Changelog | repeated | The list of changelogs. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Name | Number | Description |
| STATUS_UNSPECIFIED | 0 | |
| PENDING | 1 | |
| DONE | 2 | |
| FAILED | 3 |
| Name | Number | Description |
| CHANGELOG_VIEW_UNSPECIFIED | 0 | The default / unset value. The API will default to the BASIC view. |
| CHANGELOG_VIEW_BASIC | 1 | |
| CHANGELOG_VIEW_FULL | 2 |
ChangelogService manages database migration history.
| Method Name | Request Type | Response Type | Description |
| ListChangelogs | ListChangelogsRequest | ListChangelogsResponse | Lists migration history for a database. Permissions required: bb.changelogs.list |
| GetChangelog | GetChangelogRequest | Changelog | Retrieves a specific changelog entry. Permissions required: bb.changelogs.get |
| Method Name | Method | Pattern | Body |
| ListChangelogs | GET | /v1/{parent=instances/*/databases/*}/changelogs | |
| ListChangelogs | GET | /v1/{parent=projects/*/instances/*/databases/*}/changelogs | |
| GetChangelog | GET | /v1/{name=instances/*/databases/*/changelogs/*} | |
| GetChangelog | GET | /v1/{name=projects/*/instances/*/databases/*/changelogs/*} |
Column metadata within a table.
| Field | Type | Label | Description |
| name | string | The column name. |
|
| semantic_type | string | The semantic type describing the data purpose. |
|
| labels | ColumnCatalog.LabelsEntry | repeated | User-defined labels for this column. |
| classification | string | The data classification level for this column. |
|
| object_schema | ObjectSchema | optional | Object schema for complex column types like JSON. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
Catalog metadata for a database including schemas, tables, and columns.
| Field | Type | Label | Description |
| name | string | The name of the database catalog. Format: instances/{instance}/databases/{database}/catalog or projects/{project}/instances/{instance}/databases/{database}/catalog |
|
| schemas | SchemaCatalog | repeated | The schemas in the database. |
Request message for getting a database catalog.
| Field | Type | Label | Description |
| name | string | The name of the database catalog to retrieve. Format: instances/{instance}/databases/{database}/catalog or projects/{project}/instances/{instance}/databases/{database}/catalog |
Schema definition for object-type columns.
| Field | Type | Label | Description |
| type | ObjectSchema.Type | The data type of this object. |
|
| struct_kind | ObjectSchema.StructKind | Struct schema. |
|
| array_kind | ObjectSchema.ArrayKind | Array schema. |
|
| semantic_type | string | The semantic type of this object. |
Array type with element schema.
| Field | Type | Label | Description |
| kind | ObjectSchema | The schema of array elements. |
Structure type with named properties.
| Field | Type | Label | Description |
| properties | ObjectSchema.StructKind.PropertiesEntry | repeated | Properties of the struct. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | ObjectSchema |
|
Schema metadata within a database.
| Field | Type | Label | Description |
| name | string | The schema name. |
|
| tables | TableCatalog | repeated | The tables in the schema. |
Table metadata within a schema.
| Field | Type | Label | Description |
| name | string | The table name. |
|
| columns | TableCatalog.Columns | Regular table columns. |
|
| object_schema | ObjectSchema | Object schema for JSON/XML columns. |
|
| classification | string | The data classification level for this table. |
Column list for regular tables.
| Field | Type | Label | Description |
| columns | ColumnCatalog | repeated | The columns in the table. |
Request message for updating a database catalog.
| Field | Type | Label | Description |
| catalog | DatabaseCatalog | The database catalog to update, identified by its `name` field. Format: instances/{instance}/databases/{database}/catalog or projects/{project}/instances/{instance}/databases/{database}/catalog Replaces the whole catalog: send the complete value, since anything omitted is erased. There is no `update_mask` because `schemas` is a repeated field, and AIP-161 forbids addressing one element of one. |
Object schema data types.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified type. |
| STRING | 1 | String type. |
| NUMBER | 2 | Number type. |
| BOOLEAN | 3 | Boolean type. |
| OBJECT | 4 | Object/struct type. |
| ARRAY | 5 | Array type. |
DatabaseCatalogService manages database schema metadata and classification.
| Method Name | Request Type | Response Type | Description |
| GetDatabaseCatalog | GetDatabaseCatalogRequest | DatabaseCatalog | Gets the catalog metadata for a database. Permissions required: bb.databaseCatalogs.get |
| UpdateDatabaseCatalog | UpdateDatabaseCatalogRequest | DatabaseCatalog | Updates catalog metadata such as classifications and labels. Permissions required: bb.databaseCatalogs.update |
| Method Name | Method | Pattern | Body |
| GetDatabaseCatalog | GET | /v1/{name=instances/*/databases/*/catalog} | |
| GetDatabaseCatalog | GET | /v1/{name=projects/*/instances/*/databases/*/catalog} | |
| UpdateDatabaseCatalog | PATCH | /v1/{catalog.name=instances/*/databases/*/catalog} | catalog |
| UpdateDatabaseCatalog | PATCH | /v1/{catalog.name=projects/*/instances/*/databases/*/catalog} | catalog |
Request message for creating a database group.
| Field | Type | Label | Description |
| parent | string | The parent resource where this database group will be created. Format: projects/{project} |
|
| database_group | DatabaseGroup | The database group to create. |
|
| database_group_id | string | The ID to use for the database group, which will become the final component of the database group's resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/. |
|
| validate_only | bool | If set, validate the create request and preview the full database group response, but do not actually create it. |
A group of databases matched by expressions.
| Field | Type | Label | Description |
| name | string | The name of the database group. Format: projects/{project}/databaseGroups/{databaseGroup} |
|
| title | string | The short name used in actual databases specified by users. |
|
| database_expr | google.type.Expr | The condition that is associated with this database group. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Support variables: resource.environment_id: the environment resource id. Support "==", "!=", "in [XX]", "!(in [xx])" operations. resource.instance_id: the instance resource id. Support "==", "!=", "in [XX]", "!(in [xx])", "contains", "matches", "startsWith", "endsWith" operations. resource.database_name: the database name. Support "==", "!=", "in [XX]", "!(in [xx])", "contains", "matches", "startsWith", "endsWith" operations. resource.database_labels: the database labels. Support map access operations. All variables should join with "&&" condition. For example: resource.environment_id == "test" && resource.database_name.startsWith("sample_") resource.database_labels["tenant"] == "tenant1" |
|
| matched_databases | DatabaseGroup.Database | repeated | The list of databases that match the database group condition. |
A database within a database group.
| Field | Type | Label | Description |
| name | string | The resource name of the database. Format: instances/{instance}/databases/{database} |
Request message for deleting a database group.
| Field | Type | Label | Description |
| name | string | The name of the database group to delete. Format: projects/{project}/databaseGroups/{databaseGroup} |
Request message for getting a database group.
| Field | Type | Label | Description |
| name | string | The name of the database group to retrieve. Format: projects/{project}/databaseGroups/{databaseGroup} |
|
| view | DatabaseGroupView | The view to return. Defaults to DATABASE_GROUP_VIEW_BASIC. |
Request message for listing database groups.
| Field | Type | Label | Description |
| parent | string | The parent resource whose database groups are to be listed. Format: projects/{project} |
|
| view | DatabaseGroupView | The view to return. Defaults to DATABASE_GROUP_VIEW_BASIC. |
Response message for listing database groups.
| Field | Type | Label | Description |
| database_groups | DatabaseGroup | repeated | The database groups from the specified request. |
Request message for updating a database group.
| Field | Type | Label | Description |
| database_group | DatabaseGroup | The database group to update. The database group's `name` field is used to identify the database group to update. Format: projects/{project}/databaseGroups/{databaseGroup} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the database group is not found, a new database group will be created. In this situation, `update_mask` is ignored. |
View options for database group responses.
| Name | Number | Description |
| DATABASE_GROUP_VIEW_UNSPECIFIED | 0 | The default / unset value. The API will default to the BASIC view. |
| DATABASE_GROUP_VIEW_BASIC | 1 | Include basic information about the database group, but exclude the list of matched databases and unmatched databases. |
| DATABASE_GROUP_VIEW_FULL | 2 | Include everything. |
DatabaseGroupService manages database groups for organizing databases by criteria.
| Method Name | Request Type | Response Type | Description |
| ListDatabaseGroups | ListDatabaseGroupsRequest | ListDatabaseGroupsResponse | Lists database groups in a project. Permissions required: bb.databaseGroups.list |
| GetDatabaseGroup | GetDatabaseGroupRequest | DatabaseGroup | Gets a database group by name. Permissions required: bb.databaseGroups.get |
| CreateDatabaseGroup | CreateDatabaseGroupRequest | DatabaseGroup | Creates a new database group. Permissions required: bb.databaseGroups.create |
| UpdateDatabaseGroup | UpdateDatabaseGroupRequest | DatabaseGroup | Updates a database group. Permissions required: bb.databaseGroups.update When allow_missing=true, also requires: bb.databaseGroups.create |
| DeleteDatabaseGroup | DeleteDatabaseGroupRequest | .google.protobuf.Empty | Deletes a database group. Permissions required: bb.databaseGroups.delete |
| Method Name | Method | Pattern | Body |
| ListDatabaseGroups | GET | /v1/{parent=projects/*}/databaseGroups | |
| GetDatabaseGroup | GET | /v1/{name=projects/*/databaseGroups/*} | |
| CreateDatabaseGroup | POST | /v1/{parent=projects/*}/databaseGroups | database_group |
| UpdateDatabaseGroup | PATCH | /v1/{database_group.name=projects/*/databaseGroups/*} | database_group |
| DeleteDatabaseGroup | DELETE | /v1/{name=projects/*/databaseGroups/*} |
InstanceRole is the API message for instance role.
| Field | Type | Label | Description |
| name | string | The name of the role. Format: instances/{instance}/roles/{role} or projects/{project}/instances/{instance}/roles/{role} The role name is the unique name for the role. |
|
| role_name | string | The role name. It's unique within the instance. |
|
| password | string | optional | The role password. |
| connection_limit | int32 | optional | The connection count limit for this role. |
| valid_until | string | optional | The expiration for the role's password. |
| attribute | string | optional | The role attribute. For PostgreSQL, it contains super_user, no_inherit, create_role, create_db, can_login, replication, and bypass_rls. Docs: https://www.postgresql.org/docs/current/role-attributes.html For MySQL, it's the global privileges as GRANT statements, which means it only contains "GRANT ... ON *.* TO ...". Docs: https://dev.mysql.com/doc/refman/8.0/en/grant.html |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of roles. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| page_size | int32 | Not used. The maximum number of roles to return. The service may return fewer than this value. If unspecified, at most 10 roles will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | Not used. A page token, received from a previous `ListInstanceRoles` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListInstanceRoles` must match the call that provided the page token. |
|
| refresh | bool | Refresh will refresh and return the latest data. |
| Field | Type | Label | Description |
| roles | InstanceRole | repeated | The roles from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
InstanceRoleService manages database roles within instances.
| Method Name | Request Type | Response Type | Description |
| ListInstanceRoles | ListInstanceRolesRequest | ListInstanceRolesResponse | Lists all database roles in an instance. Permissions required: bb.instanceRoles.list |
| Method Name | Method | Pattern | Body |
| ListInstanceRoles | GET | /v1/{parent=instances/*}/roles | |
| ListInstanceRoles | GET | /v1/{parent=projects/*/instances/*}/roles |
| Field | Type | Label | Description |
| name | string | The name of the instance to add a data source to. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| data_source | DataSource | Identified by data source ID. Only READ_ONLY data source can be added. |
|
| validate_only | bool | Validate only also tests the data source connection. |
| Field | Type | Label | Description |
| parent | string | optional | The parent, which owns this collection of instances. Format: projects/{project}. If omitted, all targets must be workspace instances; otherwise, every target must belong to this project collection. |
| requests | SyncInstanceRequest | repeated | The request message specifying the instances to sync. A maximum of 1000 instances can be synced in a batch. |
| Field | Type | Label | Description |
| parent | string | optional | The parent, which owns this collection of instances. Format: projects/{project}. If omitted, all targets must be workspace instances; otherwise, every target must belong to this project collection. |
| requests | UpdateInstanceRequest | repeated | The request message specifying the resources to update. |
| Field | Type | Label | Description |
| instances | Instance | repeated |
|
| Field | Type | Label | Description |
| parent | string | optional | The parent, which owns this collection of instances. Format: projects/{project}. If omitted, the instance is created in the workspace collection. |
| instance | Instance | The instance to create. |
|
| instance_id | string | The ID to use for the instance, which will become the final component of the instance's resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/. |
|
| validate_only | bool | Validate only also tests the data source connection. |
| Field | Type | Label | Description |
| id | string | The unique identifier for this data source. |
|
| type | DataSourceType | The type of data source (ADMIN or READ_ONLY). |
|
| username | string | The username for database authentication. |
|
| password | string | The password for database authentication. |
|
| use_ssl | bool | Use SSL to connect to the data source. By default, we use system default SSL configuration. |
|
| ssl_ca | string | The SSL certificate authority certificate. |
|
| ssl_cert | string | The SSL client certificate. |
|
| ssl_key | string | The SSL client private key. |
|
| ssl_ca_path | string | The local filesystem path to the SSL certificate authority certificate. |
|
| ssl_cert_path | string | The local filesystem path to the SSL client certificate. |
|
| ssl_key_path | string | The local filesystem path to the SSL client private key. |
|
| ssl_ca_set | bool | Whether an SSL certificate authority certificate has been configured. |
|
| ssl_cert_set | bool | Whether an SSL client certificate has been configured. |
|
| ssl_key_set | bool | Whether an SSL client private key has been configured. |
|
| ssl_ca_path_set | bool | Whether an SSL certificate authority path has been configured. |
|
| ssl_cert_path_set | bool | Whether an SSL client certificate path has been configured. |
|
| ssl_key_path_set | bool | Whether an SSL client private key path has been configured. |
|
| verify_tls_certificate | bool | verify_tls_certificate enables TLS certificate verification for SSL connections. Default is false (no verification) for backward compatibility. Set to true for secure connections (recommended for production). Only set to false for development or when certificates cannot be properly validated (e.g., self-signed certs, VPN environments). |
|
| host | string | The hostname or IP address of the database server. |
|
| port | string | The port number of the database server. |
|
| database | string | The name of the database to connect to. |
|
| srv | bool | srv, authentication_database and replica_set are used for MongoDB. srv is a boolean flag that indicates whether the host is a DNS SRV record. |
|
| authentication_database | string | authentication_database is the database name to authenticate against, which stores the user credentials. |
|
| replica_set | string | replica_set is used for MongoDB replica set. |
|
| sid | string | sid and service_name are used for Oracle. |
|
| service_name | string |
|
|
| ssh_host | string | Connection over SSH. The hostname of the SSH server agent. Required. |
|
| ssh_port | string | The port of the SSH server agent. It's 22 typically. Required. |
|
| ssh_user | string | The user to login the server. Required. |
|
| ssh_password | string | The password to login the server. If it's empty string, no password is required. |
|
| ssh_private_key | string | The private key to login the server. If it's empty string, we will use the system default private key from os.Getenv("SSH_AUTH_SOCK"). |
|
| authentication_private_key | string | PKCS#8 private key in PEM format. If it's empty string, no private key is required. Used for authentication when connecting to the data source. |
|
| authentication_private_key_passphrase | string | Passphrase for the encrypted PKCS#8 private key. Only used when the private key is encrypted. |
|
| external_secret | DataSourceExternalSecret |
|
|
| authentication_type | DataSource.AuthenticationType |
|
|
| cloud_sql_ip_type | DataSource.CloudSQLIPType | cloud_sql_ip_type selects the Cloud SQL IP type for Google Cloud SQL IAM connections. CLOUD_SQL_IP_TYPE_UNSPECIFIED is treated as PUBLIC for backward compatibility. |
|
| azure_credential | DataSource.AzureCredential |
|
|
| aws_credential | DataSource.AWSCredential |
|
|
| gcp_credential | DataSource.GCPCredential |
|
|
| sasl_config | SASLConfig |
|
|
| additional_addresses | DataSource.Address | repeated | additional_addresses is used for MongoDB replica set. |
| direct_connection | bool | direct_connection is used for MongoDB to dispatch all the operations to the node specified in the connection string. |
|
| region | string | region is the location of where the DB is, works for AWS RDS. For example, us-east-1. |
|
| warehouse_id | string | warehouse_id is used by Databricks. |
|
| master_name | string | master_name is the master name used by connecting redis-master via redis sentinel. |
|
| master_username | string | master_username and master_password are master credentials used by redis sentinel mode. |
|
| master_password | string |
|
|
| redis_type | DataSource.RedisType |
|
|
| extra_connection_parameters | DataSource.ExtraConnectionParametersEntry | repeated | Extra connection parameters for the database connection. For PostgreSQL HA, this can be used to set target_session_attrs=read-write |
| project_id | string | project_id and instance_id are the GCP resource identifiers. project_id is used by Spanner and BigQuery; instance_id is used by Spanner. For these engines, host and port optionally override the default Google API endpoint (e.g. a Private Service Connect endpoint like spanner-nonprod.p.googleapis.com). |
|
| instance_id | string |
|
| Field | Type | Label | Description |
| access_key_id | string |
|
|
| secret_access_key | string |
|
|
| session_token | string |
|
|
| role_arn | string | ARN of IAM role to assume for cross-account access. See: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html |
|
| external_id | string | Optional external ID for additional security when assuming role. See: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html |
| Field | Type | Label | Description |
| host | string |
|
|
| port | string |
|
| Field | Type | Label | Description |
| tenant_id | string |
|
|
| client_id | string |
|
|
| client_secret | string |
|
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| content | string |
|
| Field | Type | Label | Description |
| secret_type | DataSourceExternalSecret.SecretType | The type of external secret store. |
|
| url | string | The URL of the external secret store. |
|
| auth_type | DataSourceExternalSecret.AuthType | The authentication method for accessing the secret store. |
|
| app_role | DataSourceExternalSecret.AppRoleAuthOption | AppRole authentication configuration. |
|
| token | string | Token for direct authentication. Interpreted according to token_type: the literal token (PLAIN), an environment variable name (ENVIRONMENT), or a file path (FILE). |
|
| token_type | DataSourceExternalSecret.TokenType | How to interpret the token field when auth_type is TOKEN. |
|
| engine_name | string | engine name is the name for secret engine. |
|
| secret_name | string | the secret name in the engine to store the password. |
|
| password_key_name | string | the key name for the password. |
|
| skip_vault_tls_verification | bool | TLS configuration for connecting to Vault server. These fields are separate from the database TLS configuration in DataSource. skip_vault_tls_verification disables TLS certificate verification for Vault connections. Default is false (verification enabled) for security. Only set to true for development or when certificates cannot be properly validated. |
|
| vault_ssl_ca | string | CA certificate for Vault server verification. |
|
| vault_ssl_cert | string | Client certificate for mutual TLS authentication with Vault. |
|
| vault_ssl_key | string | Client private key for mutual TLS authentication with Vault. |
| Field | Type | Label | Description |
| role_id | string | The role ID for Vault AppRole authentication. |
|
| secret_id | string | the secret id for the role without ttl. |
|
| type | DataSourceExternalSecret.AppRoleAuthOption.SecretType | The type of secret for AppRole authentication. |
|
| mount_path | string | The path where the approle auth method is mounted. |
| Field | Type | Label | Description |
| name | string | The name of the instance to delete. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| force | bool | If set to true, a workspace instance's databases are moved to the default project before the instance is soft-deleted. Project instances reject this option because their databases must remain in the owning project. |
|
| purge | bool | If set to true, permanently purge the soft-deleted instance and all related resources. This operation is irreversible. Following AIP-165, this should only be used for administrative cleanup of old soft-deleted instances. The instance must already be soft-deleted for this to work. |
| Field | Type | Label | Description |
| name | string | The name of the instance to retrieve. Format: instances/{instance} or projects/{project}/instances/{instance} |
| Field | Type | Label | Description |
| name | string | The name of the instance. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| state | State | The lifecycle state of the instance. |
|
| title | string | The display title of the instance. |
|
| engine | Engine | The database engine type. |
|
| engine_version | string | The version of the database engine. |
|
| external_link | string | External URL to the database instance console. |
|
| data_sources | DataSource | repeated | Data source configurations for connecting to the instance. |
| environment | string | optional | The environment resource. Format: environments/prod where prod is the environment resource ID. |
| activation | bool | Whether the instance is activated for use. |
|
| roles | InstanceRole | repeated | Database roles available in this instance. |
| sync_interval | google.protobuf.Duration | How often the instance is synced. |
|
| sync_databases | SyncDatabases | Enable sync for following databases. Not set means sync all schemas & databases. |
|
| last_sync_time | google.protobuf.Timestamp | The last time the instance was synced. |
|
| labels | Instance.LabelsEntry | repeated | Labels are key-value pairs that can be attached to the instance. For example, { "org_group": "infrastructure", "environment": "production" } |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| title | string | The display title of the instance. |
|
| engine | Engine | The database engine type. |
|
| engine_version | string | The version of the database engine. |
|
| data_sources | DataSource | repeated | Data source configurations for the instance. |
| activation | bool | Whether the instance is activated. |
|
| name | string | The name of the instance. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| environment | string | optional | The environment resource. Format: environments/prod where prod is the environment resource ID. |
| Field | Type | Label | Description |
| primary | string | The primary component of the Kerberos principal. |
|
| instance | string | The instance component of the Kerberos principal. |
|
| realm | string | The Kerberos realm. |
|
| keytab | bytes | The keytab file contents for authentication. |
|
| kdc_host | string | The hostname of the Key Distribution Center (KDC). |
|
| kdc_port | string | The port of the Key Distribution Center (KDC). |
|
| kdc_transport_protocol | string | The transport protocol for KDC communication (tcp or udp). |
| Field | Type | Label | Description |
| name | string | The name of the instance. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| instance | Instance | optional | The target instance. We need to set this field if the target instance is not created yet. |
| Field | Type | Label | Description |
| databases | string | repeated | All database name list in the instance. |
| Field | Type | Label | Description |
| parent | string | optional | The parent, which owns this collection of instances. Format: projects/{project}. If omitted, only workspace instances are returned. Wildcard project parents are not supported. When set, the `project` filter must be omitted or match this parent. |
| page_size | int32 | The maximum number of instances to return. The service may return fewer than this value. If unspecified, at most 10 instances will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListInstances` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListInstances` must match the call that provided the page token. |
|
| show_deleted | bool | Show deleted instances if specified. |
|
| filter | string | Filter the instance. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filters: - name: the instance name, support "==" and ".contains()" operator. - resource_id: the instance id, support "==" and ".contains()" operator. - environment: the environment full name in "environments/{id}" format, support "==" operator. - state: the instance state, check State enum for values, support "==" operator. - engine: the instance engine, check Engine enum for values. Support "==", "in [xx]", "!(in [xx])" operator. - host: the instance host, support "==" and ".contains()" operator. - port: the instance port, support "==" and ".contains()" operator. - project: the project full name in "projects/{id}" format, support "==" operator. - labels.{key}: the instance label, support "==" and "in" operators. For example: name == "sample instance" name.contains("sample") resource_id == "sample-instance" resource_id.contains("sample") state == "DELETED" environment == "environments/test" environment == "" (find instances which environment is not set) engine == "MYSQL" engine in ["MYSQL", "POSTGRES"] !(engine in ["MYSQL", "POSTGRES"]) host == "127.0.0.1" host.contains("127.0") port == "54321" port.contains("543") labels.org_group == "infrastructure" labels.environment in ["prod", "production"] project == "projects/sample-project" You can combine filter conditions like: name.contains("sample") && environment == "environments/test" host == "127.0.0.1" && port == "54321" |
|
| order_by | string | The order by of instances. Support title, environment. The default sorting order is ascending. For example: - order_by = "title" - order_by = "title desc" - order_by = "title desc, environment asc" |
| Field | Type | Label | Description |
| instances | Instance | repeated | The instances from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| parent | string | The project that owns the sample instance. Format: projects/{project} |
| Field | Type | Label | Description |
| name | string | The name of the instance to remove a data source from. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| data_source | DataSource | Identified by data source ID. Only READ_ONLY data source can be removed. |
| Field | Type | Label | Description |
| krb_config | KerberosConfig | Kerberos authentication configuration. |
| Field | Type | Label | Description |
| databases | string | repeated |
|
| Field | Type | Label | Description |
| name | string | The name of instance. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| enable_full_sync | bool | When full sync is enabled, all databases in the instance will be synchronized. Otherwise, only the instance metadata (such as the database list) and any newly discovered databases will be synced. |
| Field | Type | Label | Description |
| databases | string | repeated | All database name list in the instance. |
| Field | Type | Label | Description |
| name | string | The name of the deleted instance. Format: instances/{instance} or projects/{project}/instances/{instance} |
| Field | Type | Label | Description |
| name | string | The name of the instance to update a data source. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| data_source | DataSource | Identified by data source ID. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| validate_only | bool | Validate only also tests the data source connection. |
|
| allow_missing | bool | If set to true, and the data source is not found, a new data source will be created. In this situation, `update_mask` is ignored. |
| Field | Type | Label | Description |
| instance | Instance | The instance to update. The instance's `name` field is used to identify the instance to update. Format: instances/{instance} or projects/{project}/instances/{instance} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the instance is not found, a new instance will be created. In this situation, `update_mask` is ignored. A project-nested name creates the instance only under its encoded active, non-default project; it never falls back to a workspace instance. |
| Name | Number | Description |
| AUTHENTICATION_UNSPECIFIED | 0 | |
| PASSWORD | 1 | |
| GOOGLE_CLOUD_SQL_IAM | 2 | |
| AWS_RDS_IAM | 3 | |
| AZURE_IAM | 4 |
CloudSQLIPType selects which Cloud SQL IP to dial for Google Cloud SQL IAM connections.
| Name | Number | Description |
| CLOUD_SQL_IP_TYPE_UNSPECIFIED | 0 | |
| PUBLIC | 1 | |
| PRIVATE | 2 | |
| PSC | 3 |
| Name | Number | Description |
| REDIS_TYPE_UNSPECIFIED | 0 | |
| STANDALONE | 1 | |
| SENTINEL | 2 | |
| CLUSTER | 3 |
| Name | Number | Description |
| SECRET_TYPE_UNSPECIFIED | 0 | Unspecified secret type. |
| PLAIN | 1 | Plain text secret. |
| ENVIRONMENT | 2 | Secret from environment variable. |
| Name | Number | Description |
| AUTH_TYPE_UNSPECIFIED | 0 | Unspecified authentication type. |
| TOKEN | 1 | ref: https://developer.hashicorp.com/vault/docs/auth/token |
| VAULT_APP_ROLE | 2 | ref: https://developer.hashicorp.com/vault/docs/auth/approle |
| Name | Number | Description |
| SECRET_TYPE_UNSPECIFIED | 0 | Unspecified secret type. |
| VAULT_KV_V2 | 1 | ref: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2 |
| AWS_SECRETS_MANAGER | 2 | ref: https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html |
| GCP_SECRET_MANAGER | 3 | ref: https://cloud.google.com/secret-manager/docs |
| AZURE_KEY_VAULT | 4 | ref: https://learn.microsoft.com/en-us/azure/key-vault/secrets/about-secrets |
| Name | Number | Description |
| TOKEN_TYPE_UNSPECIFIED | 0 | Unspecified token type, treated as PLAIN for backward compatibility. |
| PLAIN | 1 | The token field holds the literal token value. |
| ENVIRONMENT | 2 | The token field holds the name of an environment variable on the Bytebase server that holds the token value. |
| FILE | 3 | The token field holds a path to a file on the Bytebase server that holds the token value. |
| Name | Number | Description |
| DATA_SOURCE_UNSPECIFIED | 0 | Unspecified data source type. |
| ADMIN | 1 | Admin data source with write permissions. |
| READ_ONLY | 2 | Read-only data source for query operations. |
InstanceService manages database instances and their connections.
| Method Name | Request Type | Response Type | Description |
| GetInstance | GetInstanceRequest | Instance | Gets a database instance by name. Permissions required: bb.instances.get |
| ListInstances | ListInstancesRequest | ListInstancesResponse | Lists database instances, optionally within a project. Permissions required: bb.instances.list |
| CreateInstance | CreateInstanceRequest | Instance | Creates a new database instance. Permissions required: bb.instances.create |
| PrepareSampleProjectInstance | PrepareSampleProjectInstanceRequest | Instance | Prepares a Sample Project Instance for a project. Permissions required: bb.instances.create |
| UpdateInstance | UpdateInstanceRequest | Instance | Updates a database instance. Permissions required: bb.instances.update |
| DeleteInstance | DeleteInstanceRequest | .google.protobuf.Empty | Deletes or soft-deletes a database instance. Soft-delete requests fail with FAILED_PRECONDITION while any task run targeting the instance is pending, available, or running. Permissions required: bb.instances.delete |
| UndeleteInstance | UndeleteInstanceRequest | Instance | Restores a soft-deleted database instance. Restore requests fail with FAILED_PRECONDITION while any task run targeting the instance is pending, available, or running. Permissions required: bb.instances.undelete |
| SyncInstance | SyncInstanceRequest | SyncInstanceResponse | Syncs database schemas and metadata from an instance. Permissions required: bb.instances.sync |
| ListInstanceDatabase | ListInstanceDatabaseRequest | ListInstanceDatabaseResponse | Lists all databases within an instance without creating them. Permissions required: bb.instances.get |
| BatchSyncInstances | BatchSyncInstancesRequest | BatchSyncInstancesResponse | Syncs multiple instances in a single request. Permissions required: bb.instances.sync |
| BatchUpdateInstances | BatchUpdateInstancesRequest | BatchUpdateInstancesResponse | Updates multiple instances in a single request. Permissions required: bb.instances.update |
| AddDataSource | AddDataSourceRequest | Instance | Adds a read-only data source to an instance. Permissions required: bb.instances.update |
| RemoveDataSource | RemoveDataSourceRequest | Instance | Removes a read-only data source from an instance. Permissions required: bb.instances.update |
| UpdateDataSource | UpdateDataSourceRequest | Instance | Updates a data source configuration. Permissions required: bb.instances.update |
| Method Name | Method | Pattern | Body |
| GetInstance | GET | /v1/{name=instances/*} | |
| GetInstance | GET | /v1/{name=projects/*/instances/*} | |
| ListInstances | GET | /v1/instances | |
| ListInstances | GET | /v1/{parent=projects/*}/instances | |
| CreateInstance | POST | /v1/instances | instance |
| CreateInstance | POST | /v1/{parent=projects/*}/instances | instance |
| PrepareSampleProjectInstance | POST | /v1/{parent=projects/*}/instances:prepareSampleProjectInstance | * |
| UpdateInstance | PATCH | /v1/{instance.name=instances/*} | instance |
| UpdateInstance | PATCH | /v1/{instance.name=projects/*/instances/*} | instance |
| DeleteInstance | DELETE | /v1/{name=instances/*} | |
| DeleteInstance | DELETE | /v1/{name=projects/*/instances/*} | |
| UndeleteInstance | POST | /v1/{name=instances/*}:undelete | * |
| UndeleteInstance | POST | /v1/{name=projects/*/instances/*}:undelete | * |
| SyncInstance | POST | /v1/{name=instances/*}:sync | * |
| SyncInstance | POST | /v1/{name=projects/*/instances/*}:sync | * |
| ListInstanceDatabase | POST | /v1/{name=instances/*}:databases | * |
| ListInstanceDatabase | POST | /v1/{name=projects/*/instances/*}:databases | * |
| BatchSyncInstances | POST | /v1/instances:batchSync | * |
| BatchSyncInstances | POST | /v1/{parent=projects/*}/instances:batchSync | * |
| BatchUpdateInstances | POST | /v1/instances:batchUpdate | * |
| BatchUpdateInstances | POST | /v1/{parent=projects/*}/instances:batchUpdate | * |
| AddDataSource | POST | /v1/{name=instances/*}:addDataSource | * |
| AddDataSource | POST | /v1/{name=projects/*/instances/*}:addDataSource | * |
| RemoveDataSource | POST | /v1/{name=instances/*}:removeDataSource | * |
| RemoveDataSource | POST | /v1/{name=projects/*/instances/*}:removeDataSource | * |
| UpdateDataSource | PATCH | /v1/{name=instances/*}:updateDataSource | data_source |
| UpdateDataSource | PATCH | /v1/{name=projects/*/instances/*}:updateDataSource | data_source |
| Field | Type | Label | Description |
| parent | string | The parent resource shared by all databases being retrieved. - projects/{project}: batch get databases in a project; - instances/{instance}: batch get databases in an instance; - projects/{project}/instances/{instance}: batch get databases in a project instance; Use "-" as wildcard to batch get databases across parent. |
|
| names | string | repeated | The list of database names to retrieve. |
| Field | Type | Label | Description |
| databases | Database | repeated | One database per requested name, in the same order as `names`. |
| Field | Type | Label | Description |
| parent | string | The parent resource shared by all databases being updated. Format: instances/{instance} or projects/{project}/instances/{instance} If the operation spans parents, a dash (-) may be accepted as a wildcard. |
|
| names | string | repeated | The list of database names to sync. |
| Field | Type | Label | Description |
| parent | string | The parent resource shared by all databases being updated. Format: instances/{instance} or projects/{project}/instances/{instance} If the operation spans parents, a dash (-) may be accepted as a wildcard. We only support updating the project of databases for now. |
|
| requests | UpdateDatabaseRequest | repeated | The request message specifying the resources to update. A maximum of 1000 databases can be modified in a batch. |
| Field | Type | Label | Description |
| databases | Database | repeated | Databases updated. |
BoundingBox defines the spatial bounds for GEOMETRY spatial indexes.
| Field | Type | Label | Description |
| xmin | double | Minimum X coordinate |
|
| ymin | double | Minimum Y coordinate |
|
| xmax | double | Maximum X coordinate |
|
| ymax | double | Maximum Y coordinate |
CheckConstraintMetadata is the metadata for check constraints.
| Field | Type | Label | Description |
| name | string | The name is the name of a check constraint. |
|
| expression | string | The expression is the expression of a check constraint. |
ColumnMetadata is the metadata for columns.
| Field | Type | Label | Description |
| name | string | The name is the name of a column. |
|
| position | int32 | The position is the position in columns. |
|
| has_default | bool |
|
|
| default | string | The default value of column. |
|
| default_on_null | bool | Oracle specific metadata. The default_on_null is the default on null of a column. |
|
| on_update | string | The on_update is the on update action of a column. For MySQL like databases, it's only supported for TIMESTAMP columns with CURRENT_TIMESTAMP as on update value. |
|
| nullable | bool | The nullable is the nullable of a column. |
|
| type | string | The type is the type of a column. |
|
| character_set | string | The character_set is the character_set of a column. |
|
| collation | string | The collation is the collation of a column. |
|
| comment | string | The comment is the comment of a column. |
|
| generation | GenerationMetadata | The generation is the generation of a column. |
|
| is_identity | bool |
|
|
| identity_generation | ColumnMetadata.IdentityGeneration | The identity_generation is for identity columns, PG only. |
|
| identity_seed | int64 | The identity_seed is for identity columns, MSSQL only. |
|
| identity_increment | int64 | The identity_increment is for identity columns, MSSQL only. |
|
| default_constraint_name | string | The default_constraint_name is the name of the default constraint, MSSQL only. In MSSQL, default values are implemented as named constraints. When modifying or dropping a column's default value, you must reference the constraint by name. This field stores the actual constraint name from the database. Example: A column definition like: CREATE TABLE employees ( status NVARCHAR(20) DEFAULT 'active' ) Will create a constraint with an auto-generated name like 'DF__employees__statu__3B75D760' or a user-defined name if specified: ALTER TABLE employees ADD CONSTRAINT DF_employees_status DEFAULT 'active' FOR status To modify the default, you must first drop the existing constraint by name: ALTER TABLE employees DROP CONSTRAINT DF__employees__statu__3B75D760 ALTER TABLE employees ADD CONSTRAINT DF_employees_status DEFAULT 'inactive' FOR status This field is populated when syncing from the database. When empty (e.g., when parsing from SQL files), the system cannot automatically drop the constraint. |
|
| srid | uint32 | optional | The spatial reference system identifier of a spatial column, MySQL 8.0 only. Unset means the column declares no SRID; presence carries the explicit SRID, including the valid SRID 0. SRS_IDs are unsigned 32-bit (custom SRSs may exceed int32). |
| is_invisible | bool | Whether the column is invisible (hidden from SELECT *), MySQL 8.0.23+ only. |
| Field | Type | Label | Description |
| name | string | The name of the attribute. |
|
| type | string | The attribute type. User-defined types are always schema-qualified. |
|
| collation | string | The non-default collation of the attribute as an emit-ready SQL identifier reference (quoted as needed, schema-qualified when outside pg_catalog), empty otherwise. e.g. `"C"` or `locale.en_us`. |
|
| comment | string | The comment describing the attribute. |
| Field | Type | Label | Description |
| name | string | The name of the composite type. |
|
| attributes | CompositeTypeAttribute | repeated | The ordered attributes of the composite type. |
| comment | string | The comment describing the composite type. |
| Field | Type | Label | Description |
| name | string | The name of the database. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} {database} is the database name in the instance. |
|
| state | State | The existence of a database. |
|
| successful_sync_time | google.protobuf.Timestamp | The latest synchronization time. |
|
| project | string | The project for a database. Format: projects/{project} |
|
| release | string | The release that was last applied to this database. Format: projects/{project}/releases/{release_id} Example: projects/my-project/releases/release_20260115-RC00 |
|
| environment | string | optional | The environment resource. Format: environments/prod where prod is the environment resource ID. |
| effective_environment | string | optional | The effective environment based on environment tag above and environment tag on the instance. Inheritance follows https://cloud.google.com/resource-manager/docs/tags/tags-overview. |
| labels | Database.LabelsEntry | repeated | Labels will be used for deployment and policy control. |
| instance_resource | InstanceResource | The instance resource. |
|
| backup_available | bool | The database is available for DML prior backup. |
|
| sync_status | SyncStatus | The sync status of the database. |
|
| sync_error | string | The error message if sync failed. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
DatabaseMetadata is the metadata for databases.
| Field | Type | Label | Description |
| name | string | The database metadata name. Format: instances/{instance}/databases/{database}/metadata or projects/{project}/instances/{instance}/databases/{database}/metadata |
|
| schemas | SchemaMetadata | repeated | The schemas is the list of schemas in a database. |
| character_set | string | The character_set is the character set of a database. |
|
| collation | string | The collation is the collation of a database. |
|
| extensions | ExtensionMetadata | repeated | The extensions is the list of extensions in a database. |
| owner | string | The owner of the database. |
|
| search_path | string | The search_path is the search path of a PostgreSQL database. |
DatabaseSDLSchema contains the schema in SDL format.
| Field | Type | Label | Description |
| schema | bytes | The SDL schema content. - For SINGLE_FILE format: contains the complete SDL schema as a text string. - For MULTI_FILE format: contains the ZIP archive as binary data. |
|
| content_type | string | The MIME type of the schema content. Indicates how the client should interpret the schema field. Examples: - "text/plain; charset=utf-8" for SINGLE_FILE format - "application/zip" for MULTI_FILE format |
DatabaseSchema is the metadata for databases.
| Field | Type | Label | Description |
| schema | string | The schema dump from database. |
DependencyColumn is the metadata for dependency columns.
| Field | Type | Label | Description |
| schema | string | The schema is the schema of a reference column. |
|
| table | string | The table is the table of a reference column. |
|
| column | string | The column is the name of a reference column. |
| Field | Type | Label | Description |
| schema | string | The schema is the schema of a reference table. |
|
| table | string | The table is the name of a reference table. |
| Field | Type | Label | Description |
| name | string | The database whose current schema is the diff source. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| target_metadata | DatabaseMetadata | The metadata of the target schema. The source metadata and the engine are read from the database, so only the target travels in the request. Must describe the COMPLETE target schema: the diff runs against the full stored source, so any object omitted from the target (for example by a truncated metadata fetch) is treated as dropped. |
| Field | Type | Label | Description |
| diff | string | The generated migration statements. |
| Field | Type | Label | Description |
| name | string | The name of the database or changelog. Format: database: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} changelog: instances/{instance}/databases/{database}/changelogs/{changelog} or projects/{project}/instances/{instance}/databases/{database}/changelogs/{changelog} |
|
| schema | string | The target schema. |
|
| changelog | string | The resource name of the changelog Format: instances/{instance}/databases/{database}/changelogs/{changelog} or projects/{project}/instances/{instance}/databases/{database}/changelogs/{changelog} |
| Field | Type | Label | Description |
| diff | string |
|
DimensionConstraint defines constraints for a spatial dimension.
| Field | Type | Label | Description |
| dimension | string | Dimension name/type (X, Y, Z, M, etc.) |
|
| min_value | double | Minimum value for this dimension |
|
| max_value | double | Maximum value for this dimension |
|
| tolerance | double | Tolerance for this dimension |
DimensionalConfig defines dimensional and constraint parameters for spatial indexes.
| Field | Type | Label | Description |
| dimensions | int32 | Number of dimensions (2-4, default 2) |
|
| data_type | string | Spatial data type (GEOMETRY, GEOGRAPHY, POINT, POLYGON, etc.) |
|
| srid | int32 | Spatial reference system identifier (SRID) |
|
| constraints | DimensionConstraint | repeated | Coordinate system constraints |
| Field | Type | Label | Description |
| name | string | The name of a type. |
|
| values | string | repeated | The enum values of a type. |
| comment | string | The comment describing the enum type. |
|
| skip_dump | bool | Whether to skip this enum type during schema dump operations. |
| Field | Type | Label | Description |
| name | string | The name of the event. |
|
| definition | string | The schedule of the event. |
|
| time_zone | string | The time zone of the event. |
|
| sql_mode | string | The SQL mode setting for the event. |
|
| character_set_client | string | The character set used by the client creating the event. |
|
| collation_connection | string | The collation used for the connection when creating the event. |
|
| comment | string | The comment is the comment of an event. |
ExtensionMetadata is the metadata for extensions.
| Field | Type | Label | Description |
| name | string | The name is the name of an extension. |
|
| schema | string | The schema is the extension that is installed to. But the extension usage is not limited to the schema. |
|
| version | string | The version is the version of an extension. |
|
| description | string | The description is the description of an extension. |
| Field | Type | Label | Description |
| name | string | The name is the name of a external table. |
|
| external_server_name | string | The external_server_name is the name of the external server. |
|
| external_database_name | string | The external_database_name is the name of the external database. |
|
| columns | ColumnMetadata | repeated | The columns is the ordered list of columns in a foreign table. |
ForeignKeyMetadata is the metadata for foreign keys.
| Field | Type | Label | Description |
| name | string | The name is the name of a foreign key. |
|
| columns | string | repeated | The columns are the ordered referencing columns of a foreign key. |
| referenced_schema | string | The referenced_schema is the referenced schema name of a foreign key. It is an empty string for databases without such concept such as MySQL. |
|
| referenced_table | string | The referenced_table is the referenced table name of a foreign key. |
|
| referenced_columns | string | repeated | The referenced_columns are the ordered referenced columns of a foreign key. |
| on_delete | string | The on_delete is the on delete action of a foreign key. |
|
| on_update | string | The on_update is the on update action of a foreign key. |
|
| match_type | string | The match_type is the match type of a foreign key. The match_type is the PostgreSQL specific field. It's empty string for other databases. |
FunctionMetadata is the metadata for functions.
| Field | Type | Label | Description |
| name | string | The name is the name of a function. |
|
| definition | string | The definition is the definition of a function. |
|
| signature | string | The signature is the name with the number and type of input arguments the function takes. |
|
| character_set_client | string | MySQL specific metadata. |
|
| collation_connection | string |
|
|
| database_collation | string |
|
|
| sql_mode | string |
|
|
| comment | string |
|
|
| dependency_tables | DependencyTable | repeated | The dependency_tables is the list of dependency tables of a function. For PostgreSQL, it's the list of tables that the function depends on the return type definition. |
| skip_dump | bool |
|
| Field | Type | Label | Description |
| type | GenerationMetadata.Type |
|
|
| expression | string |
|
| Field | Type | Label | Description |
| name | string | The name of the database to retrieve metadata. Format: instances/{instance}/databases/{database}/metadata or projects/{project}/instances/{instance}/databases/{database}/metadata |
|
| filter | string | Filter is used to filter databases returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - schema: the schema name, support "==" operator. - table: the table name, support "==" and ".contains()" operator. For example: schema == "schema-a" table == "table-a" table.contains("table-a") schema == "schema-a" && table.contains("sample") The filter is used to search for tables containing "sample" in the schema "schemas/schema-a". The column masking level will only be returned when a table filter is used. |
|
| limit | int32 | Limit the response size of returned table metadata per schema. For example, if the database has 3 schemas, and each schema has 100 tables, if limit is 20, then only 20 tables will be returned for each schema, total 60 tables. Default 0, means no limit. |
| Field | Type | Label | Description |
| name | string | The name of the database to retrieve. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
| Field | Type | Label | Description |
| name | string | The name of the database to retrieve SDL schema. Format: instances/{instance}/databases/{database}/sdlSchema or projects/{project}/instances/{instance}/databases/{database}/sdlSchema |
|
| format | GetDatabaseSDLSchemaRequest.SDLFormat | The format of the SDL schema output. |
| Field | Type | Label | Description |
| name | string | The name of the database to retrieve schema. Format: instances/{instance}/databases/{database}/schema or projects/{project}/instances/{instance}/databases/{database}/schema |
| Field | Type | Label | Description |
| name | string | The name of the database. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| type | GetSchemaStringRequest.ObjectType |
|
|
| schema | string | It's empty for DATABASE. |
|
| object | string | It's empty for DATABASE and SCHEMA. |
|
| metadata | DatabaseMetadata | If use the metadata to generate the schema string, the type is OBJECT_TYPE_UNSPECIFIED. Also the schema and object are empty. |
| Field | Type | Label | Description |
| schema_string | string |
|
GridLevel defines a tessellation grid level with its density.
| Field | Type | Label | Description |
| level | int32 | Grid level number (1-4 for SQL Server) |
|
| density | string | Grid density (LOW, MEDIUM, HIGH) |
IndexMetadata is the metadata for indexes.
| Field | Type | Label | Description |
| name | string | The name is the name of an index. |
|
| expressions | string | repeated | The expressions are the ordered columns or expressions of an index. This could refer to a column or an expression. |
| key_length | int64 | repeated | The key_lengths are the ordered key lengths of an index. If the key length is not specified, it's -1. |
| descending | bool | repeated | The descending is the ordered descending of an index. |
| type | string | The type is the type of an index. |
|
| unique | bool | The unique is whether the index is unique. |
|
| primary | bool | The primary is whether the index is a primary key index. |
|
| visible | bool | The visible is whether the index is visible. |
|
| comment | string | The comment is the comment of an index. |
|
| definition | string | The definition of an index. |
|
| parent_index_schema | string | The schema name of the parent index. |
|
| parent_index_name | string | The index name of the parent index. |
|
| granularity | int64 | The number of granules in the block. It's a ClickHouse specific field. |
|
| is_constraint | bool | It's a PostgreSQL specific field. The unique constraint and unique index are not the same thing in PostgreSQL. |
|
| spatial_config | SpatialIndexConfig | Spatial index configuration for spatial databases like SQL Server, PostgreSQL with PostGIS, etc. |
|
| opclass_names | string | repeated | https://www.postgresql.org/docs/current/catalog-pg-opclass.html Name of the operator class for each column. (PostgreSQL specific). |
| opclass_defaults | bool | repeated | True if the operator class is the default. (PostgreSQL specific). |
| Field | Type | Label | Description |
| parent | string | - projects/{project}: list databases in a project, require "bb.databases.list" permission. - workspaces/{id}: list databases in the workspace, require "bb.databases.list" permission. - instances/{instance}: list databases in an instance, require "bb.instances.get" permission. - projects/{project}/instances/{instance}: list databases in a project instance, require "bb.instances.get" permission. |
|
| page_size | int32 | The maximum number of databases to return. The service may return fewer than this value. If unspecified, at most 10 databases will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListDatabases` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListDatabases` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter databases returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - environment: the environment full name in "environments/{id}" format, support "==" operator. - name: the database name, support ".contains()" operator. - project: the project full name in "projects/{id}" format, support "==" operator. - instance: the instance full name in "instances/{id}" or "projects/{project}/instances/{id}" format, support "==" operator. - engine: the database engine, check Engine enum for values. Support "==", "in [xx]", "!(in [xx])" operator. - exclude_unassigned: should be "true" or "false", will not show unassigned databases if it's true, support "==" operator. - table: filter by the database table, support "==" and ".contains()" operator. - labels.{key}: the database label, support "==" and "in" operators. For example: environment == "environments/{environment resource id}" environment == "" (find databases which environment is not set) project == "projects/{project resource id}" instance == "instances/{instance resource id}" instance == "projects/{project resource id}/instances/{instance resource id}" name.contains("database name") engine == "MYSQL" engine in ["MYSQL", "POSTGRES"] !(engine in ["MYSQL", "POSTGRES"]) exclude_unassigned == true table == "sample" table.contains("sam") labels.environment == "production" labels.region == "asia" labels.region in ["asia", "europe"] You can combine filter conditions like: environment == "environments/prod" && name.contains("employee") |
|
| show_deleted | bool | Show deleted database if specified. |
|
| order_by | string | The order by of databases. Support name, project, instance. The default sorting order is ascending. For example: - order_by = "name" - order by name ascending - order_by = "name desc" - order_by = "name desc, project asc" |
| Field | Type | Label | Description |
| databases | Database | repeated | The databases from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
MaterializedViewMetadata is the metadata for materialized views.
| Field | Type | Label | Description |
| name | string | The name is the name of a materialized view. |
|
| definition | string | The definition is the definition of a materialized view. |
|
| comment | string | The comment is the comment of a materialized view. |
|
| dependency_columns | DependencyColumn | repeated | The dependency_columns is the list of dependency columns of a materialized view. |
| triggers | TriggerMetadata | repeated | The columns is the ordered list of columns in a table. |
| indexes | IndexMetadata | repeated | The indexes is the list of indexes in a table. |
| skip_dump | bool |
|
PackageMetadata is the metadata for packages.
| Field | Type | Label | Description |
| name | string | The name is the name of a package. |
|
| definition | string | The definition is the definition of a package. |
ProcedureMetadata is the metadata for procedures.
| Field | Type | Label | Description |
| name | string | The name is the name of a procedure. |
|
| definition | string | The definition is the definition of a procedure. |
|
| signature | string | The signature is the name with the number and type of input arguments the procedure takes. |
|
| character_set_client | string | MySQL specific metadata. |
|
| collation_connection | string |
|
|
| database_collation | string |
|
|
| sql_mode | string |
|
|
| comment | string | The comment is the comment of a procedure. |
|
| skip_dump | bool |
|
SchemaMetadata is the metadata for schemas.
This is the concept of schema in Postgres, but it's a no-op for MySQL.
| Field | Type | Label | Description |
| name | string | The name is the schema name. It is an empty string for databases without such concept such as MySQL. |
|
| tables | TableMetadata | repeated | The tables is the list of tables in a schema. |
| external_tables | ExternalTableMetadata | repeated | The external_tables is the list of external tables in a schema. |
| views | ViewMetadata | repeated | The views is the list of views in a schema. |
| functions | FunctionMetadata | repeated | The functions is the list of functions in a schema. |
| procedures | ProcedureMetadata | repeated | The procedures is the list of procedures in a schema. |
| streams | StreamMetadata | repeated | The streams is the list of streams in a schema, currently, only used for Snowflake. |
| tasks | TaskMetadata | repeated | The routines is the list of routines in a schema, currently, only used for Snowflake. |
| materialized_views | MaterializedViewMetadata | repeated | The materialized_views is the list of materialized views in a schema. |
| packages | PackageMetadata | repeated | The packages is the list of packages in a schema. |
| owner | string | The owner of the schema. |
|
| sequences | SequenceMetadata | repeated | The sequences is the list of sequences in a schema, sorted by name. |
| events | EventMetadata | repeated | The events is the list of scheduled events in a schema. |
| enum_types | EnumTypeMetadata | repeated | The enum_types is the list of user-defined enum types in a schema. |
| skip_dump | bool | Whether to skip this schema during schema dump operations. |
|
| comment | string | The comment is the comment of a schema. |
|
| composite_types | CompositeTypeMetadata | repeated | The composite_types is the list of user-defined composite types in a schema (PostgreSQL family, CREATE TYPE ... AS). Excludes table/view row types and derived types. |
| Field | Type | Label | Description |
| page_size | int32 | The maximum number of databases to return. The service may return fewer than this value. If unspecified, at most 10 databases will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `SearchDatabases` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchDatabases` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter databases returned in the list. It supports the same fields and operators as `ListDatabasesRequest.filter`. For example: project == "projects/{project resource id}" name.contains("database name") && engine == "POSTGRES" |
| Field | Type | Label | Description |
| databases | Database | repeated | The databases from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | The name of a sequence. |
|
| data_type | string | The data type of a sequence. |
|
| start | string | The start value of a sequence. |
|
| min_value | string | The minimum value of a sequence. |
|
| max_value | string | The maximum value of a sequence. |
|
| increment | string | Increment value of a sequence. |
|
| cycle | bool | Cycle is whether the sequence cycles. |
|
| cache_size | string | Cache size of a sequence. |
|
| last_value | string | Last value of a sequence. |
|
| owner_table | string | The owner table of the sequence. |
|
| owner_column | string | The owner column of the sequence. |
|
| comment | string | The comment describing the sequence. |
|
| skip_dump | bool | Whether to skip this sequence during schema dump operations. |
SpatialIndexConfig defines the spatial index configuration for spatial databases.
| Field | Type | Label | Description |
| method | string | Spatial indexing method (e.g., "SPATIAL", "R-TREE", "GIST") |
|
| tessellation | TessellationConfig | Tessellation configuration for grid-based spatial indexes |
|
| storage | StorageConfig | Storage and performance configuration |
|
| dimensional | DimensionalConfig | Dimensional configuration |
StorageConfig defines storage and performance parameters for spatial indexes.
| Field | Type | Label | Description |
| fillfactor | int32 | Fill factor percentage (1-100) |
|
| buffering | string | Buffering mode for PostgreSQL (auto, on, off) |
|
| tablespace | string | Tablespace configuration for Oracle |
|
| work_tablespace | string |
|
|
| sdo_level | int32 |
|
|
| commit_interval | int32 |
|
|
| pad_index | bool | SQL Server specific parameters |
|
| sort_in_tempdb | string | ON, OFF |
|
| drop_existing | bool |
|
|
| online | bool |
|
|
| allow_row_locks | bool |
|
|
| allow_page_locks | bool |
|
|
| maxdop | int32 |
|
|
| data_compression | string | NONE, ROW, PAGE |
| Field | Type | Label | Description |
| name | string | The name is the name of a stream. |
|
| table_name | string | The table_name is the name of the table/view that the stream is created on. |
|
| owner | string | The owner of the stream. |
|
| comment | string | The comment of the stream. |
|
| type | StreamMetadata.Type | The type of the stream. |
|
| stale | bool | Indicates whether the stream was last read before the `stale_after` time. |
|
| mode | StreamMetadata.Mode | The mode of the stream. |
|
| definition | string | The definition of the stream. |
| Field | Type | Label | Description |
| name | string | The name of the database to sync. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
TableMetadata is the metadata for tables.
| Field | Type | Label | Description |
| name | string | The name is the name of a table. |
|
| columns | ColumnMetadata | repeated | The columns is the ordered list of columns in a table. |
| indexes | IndexMetadata | repeated | The indexes is the list of indexes in a table. |
| engine | string | The engine is the engine of a table. |
|
| collation | string | The collation is the collation of a table. |
|
| charset | string | The character set of table. |
|
| row_count | int64 | The row_count is the estimated number of rows of a table. |
|
| data_size | int64 | The data_size is the estimated data size of a table. |
|
| index_size | int64 | The index_size is the estimated index size of a table. |
|
| data_free | int64 | The data_free is the estimated free data size of a table. |
|
| create_options | string | The create_options is the create option of a table. |
|
| comment | string | The comment is the comment of a table. |
|
| foreign_keys | ForeignKeyMetadata | repeated | The foreign_keys is the list of foreign keys in a table. |
| partitions | TablePartitionMetadata | repeated | The partitions is the list of partitions in a table. |
| check_constraints | CheckConstraintMetadata | repeated | The check_constraints is the list of check constraints in a table. |
| owner | string | The owner of the table. |
|
| sorting_keys | string | repeated | The sorting_keys is a tuple of column names or arbitrary expressions. ClickHouse specific field. Reference: https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#order_by |
| triggers | TriggerMetadata | repeated | The triggers is the list of triggers associated with the table. |
| skip_dump | bool | Whether to skip this table during schema dump operations. |
|
| sharding_info | string | https://docs.pingcap.com/tidb/stable/information-schema-tables/ |
|
| primary_key_type | string | https://docs.pingcap.com/tidb/stable/clustered-indexes/#clustered-indexes CLUSTERED or NONCLUSTERED. |
TablePartitionMetadata is the metadata for table partitions.
| Field | Type | Label | Description |
| name | string | The name is the name of a table partition. |
|
| type | TablePartitionMetadata.Type | The type of a table partition. |
|
| expression | string | The expression is the expression of a table partition. For PostgreSQL, the expression is the text of {FOR VALUES partition_bound_spec}, see https://www.postgresql.org/docs/current/sql-createtable.html. For MySQL, the expression is the `expr` or `column_list` of the following syntax. PARTITION BY { [LINEAR] HASH(expr) | [LINEAR] KEY [ALGORITHM={1 | 2}] (column_list) | RANGE{(expr) | COLUMNS(column_list)} | LIST{(expr) | COLUMNS(column_list)} }. |
|
| value | string | The value is the value of a table partition. For MySQL, the value is for RANGE and LIST partition types, - For a RANGE partition, it contains the value set in the partition's VALUES LESS THAN clause, which can be either an integer or MAXVALUE. - For a LIST partition, this column contains the values defined in the partition's VALUES IN clause, which is a list of comma-separated integer values. - For others, it's an empty string. |
|
| use_default | string | The use_default is whether the users use the default partition, it stores the different value for different database engines. For MySQL, it's [INT] type, 0 means not use default partition, otherwise, it's equals to number in syntax [SUB]PARTITION {number}. |
|
| subpartitions | TablePartitionMetadata | repeated | The subpartitions is the list of subpartitions in a table partition. |
| indexes | IndexMetadata | repeated |
|
| check_constraints | CheckConstraintMetadata | repeated |
|
| Field | Type | Label | Description |
| name | string | The name is the name of a task. |
|
| id | string | The id is the snowflake-generated id of a task. Example: 01ad32a0-1bb6-5e93-0000-000000000001 |
|
| owner | string | The owner of the task. |
|
| comment | string | The comment of the task. |
|
| warehouse | string | The warehouse of the task. |
|
| schedule | string | The schedule interval of the task. |
|
| predecessors | string | repeated | The predecessor tasks of the task. |
| state | TaskMetadata.State | The state of the task. |
|
| condition | string | The condition of the task. |
|
| definition | string | The definition of the task. |
TessellationConfig defines tessellation parameters for spatial indexes.
| Field | Type | Label | Description |
| scheme | string | Tessellation scheme (e.g., "GEOMETRY_GRID", "GEOGRAPHY_GRID", "GEOMETRY_AUTO_GRID") |
|
| grid_levels | GridLevel | repeated | Grid levels and densities for multi-level tessellation |
| cells_per_object | int32 | Number of cells per object (1-8192 for SQL Server) |
|
| bounding_box | BoundingBox | Bounding box for GEOMETRY tessellation (not used for GEOGRAPHY) |
| Field | Type | Label | Description |
| name | string | The name is the name of the trigger. |
|
| event | string | The event is the event of the trigger, such as INSERT, UPDATE, DELETE, TRUNCATE. |
|
| timing | string | The timing is the timing of the trigger, such as BEFORE, AFTER. |
|
| body | string | The body is the body of the trigger. |
|
| sql_mode | string | The SQL mode setting for the trigger. |
|
| character_set_client | string | The character set used by the client creating the trigger. |
|
| collation_connection | string | The collation used for the connection when creating the trigger. |
|
| comment | string | The comment describing the trigger. |
|
| skip_dump | bool | Whether to skip this trigger during schema dump operations. |
| Field | Type | Label | Description |
| database | Database | The database to update. The database's `name` field is used to identify the database to update. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
ViewMetadata is the metadata for views.
| Field | Type | Label | Description |
| name | string | The name is the name of a view. |
|
| definition | string | The definition is the definition of a view. |
|
| comment | string | The comment is the comment of a view. |
|
| dependency_columns | DependencyColumn | repeated | The dependency_columns is the list of dependency columns of a view. |
| columns | ColumnMetadata | repeated | The columns is the ordered list of columns in a table. |
| triggers | TriggerMetadata | repeated | The triggers is the list of triggers in a view. |
| skip_dump | bool |
|
| Name | Number | Description |
| IDENTITY_GENERATION_UNSPECIFIED | 0 | |
| ALWAYS | 1 | |
| BY_DEFAULT | 2 |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| VIRTUAL | 1 | |
| STORED | 2 |
SDLFormat specifies the output format for SDL schema.
| Name | Number | Description |
| SDL_FORMAT_UNSPECIFIED | 0 | Unspecified format. Defaults to SINGLE_FILE. |
| SINGLE_FILE | 1 | Single file format: returns the complete SDL schema as a single file. |
| MULTI_FILE | 2 | Multi-file format: returns the SDL schema as a ZIP archive containing multiple files organized by schema objects (tables, views, functions, etc.). |
| Name | Number | Description |
| OBJECT_TYPE_UNSPECIFIED | 0 | |
| DATABASE | 1 | |
| SCHEMA | 2 | |
| TABLE | 3 | |
| VIEW | 4 | |
| MATERIALIZED_VIEW | 5 | |
| FUNCTION | 6 | |
| PROCEDURE | 7 | |
| SEQUENCE | 8 |
| Name | Number | Description |
| MODE_UNSPECIFIED | 0 | |
| DEFAULT | 1 | |
| APPEND_ONLY | 2 | |
| INSERT_ONLY | 3 |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| DELTA | 1 |
SyncStatus is the status of the database sync operation.
| Name | Number | Description |
| SYNC_STATUS_UNSPECIFIED | 0 | |
| OK | 1 | The database was synced successfully. |
| FAILED | 2 | The database sync failed. |
Type is the type of a table partition, some database engines may not
support all types. Only avilable for the following database engines now:
MySQL: RANGE, RANGE COLUMNS, LIST, LIST COLUMNS, HASH, LINEAR HASH, KEY,
LINEAR_KEY
(https://dev.mysql.com/doc/refman/8.0/en/partitioning-types.html) TiDB:
RANGE, RANGE COLUMNS, LIST, LIST COLUMNS, HASH, KEY PostgreSQL: RANGE,
LIST, HASH (https://www.postgresql.org/docs/current/ddl-partitioning.html)
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| RANGE | 1 | |
| RANGE_COLUMNS | 2 | |
| LIST | 3 | |
| LIST_COLUMNS | 4 | |
| HASH | 5 | |
| LINEAR_HASH | 6 | |
| KEY | 7 | |
| LINEAR_KEY | 8 |
| Name | Number | Description |
| STATE_UNSPECIFIED | 0 | |
| STARTED | 1 | |
| SUSPENDED | 2 |
DatabaseService manages databases and their schemas.
| Method Name | Request Type | Response Type | Description |
| GetDatabase | GetDatabaseRequest | Database | Retrieves a database by name. Permissions required: bb.databases.get |
| BatchGetDatabases | BatchGetDatabasesRequest | BatchGetDatabasesResponse | Retrieves multiple databases by their names. One resource per requested name, in request order. The first name that does not resolve fails the whole call (AIP-231: no partial response). Permissions required: bb.databases.get (on each named database's project) |
| ListDatabases | ListDatabasesRequest | ListDatabasesResponse | Lists databases in a project, instance, or workspace. Permissions required: bb.databases.list (for project or workspace parent), or bb.instances.get (for instance parent) |
| SearchDatabases | SearchDatabasesRequest | SearchDatabasesResponse | Searches for databases in every active project where the caller has the bb.databases.get permission, filtered by the specified filter. Permissions required: bb.databases.get (checked in each project) |
| UpdateDatabase | UpdateDatabaseRequest | Database | Updates database properties such as labels and project assignment. Permissions required: bb.databases.update |
| BatchUpdateDatabases | BatchUpdateDatabasesRequest | BatchUpdateDatabasesResponse | Updates multiple databases in a single batch operation. Permissions required: bb.databases.update |
| SyncDatabase | SyncDatabaseRequest | SyncDatabaseResponse | Synchronizes database schema from the instance. Permissions required: bb.databases.sync |
| BatchSyncDatabases | BatchSyncDatabasesRequest | BatchSyncDatabasesResponse | Synchronizes multiple databases in a single batch operation. Permissions required: bb.databases.sync |
| GetDatabaseMetadata | GetDatabaseMetadataRequest | DatabaseMetadata | Retrieves database metadata including tables, columns, and indexes. Permissions required: bb.databases.getSchema |
| GetDatabaseSchema | GetDatabaseSchemaRequest | DatabaseSchema | Retrieves database schema as DDL statements. Permissions required: bb.databases.getSchema |
| GetDatabaseSDLSchema | GetDatabaseSDLSchemaRequest | DatabaseSDLSchema | Retrieves database schema in SDL (Schema Definition Language) format. Permissions required: bb.databases.getSchema |
| DiffSchema | DiffSchemaRequest | DiffSchemaResponse | Compares and generates migration statements between two schemas. Permissions required: bb.databases.get |
| DiffMetadata | DiffMetadataRequest | DiffMetadataResponse | Generates migration statements from the database's current schema to the given target metadata. Permissions required: bb.databases.diffMetadata |
| GetSchemaString | GetSchemaStringRequest | GetSchemaStringResponse | Generates schema DDL for a database object. Permissions required: bb.databases.getSchema |
| Method Name | Method | Pattern | Body |
| GetDatabase | GET | /v1/{name=instances/*/databases/*} | |
| GetDatabase | GET | /v1/{name=projects/*/instances/*/databases/*} | |
| BatchGetDatabases | GET | /v1/{parent=projects/*}/databases:batchGet | |
| BatchGetDatabases | GET | /v1/{parent=instances/*}/databases:batchGet | |
| BatchGetDatabases | GET | /v1/{parent=projects/*/instances/*}/databases:batchGet | |
| ListDatabases | GET | /v1/{parent=projects/*}/databases | |
| ListDatabases | GET | /v1/{parent=instances/*}/databases | |
| ListDatabases | GET | /v1/{parent=workspaces/*}/databases | |
| ListDatabases | GET | /v1/{parent=projects/*/instances/*}/databases | |
| SearchDatabases | POST | /v1/databases:search | * |
| UpdateDatabase | PATCH | /v1/{database.name=instances/*/databases/*} | database |
| UpdateDatabase | PATCH | /v1/{database.name=projects/*/instances/*/databases/*} | database |
| BatchUpdateDatabases | POST | /v1/{parent=instances/*}/databases:batchUpdate | * |
| BatchUpdateDatabases | POST | /v1/{parent=projects/*/instances/*}/databases:batchUpdate | * |
| SyncDatabase | POST | /v1/{name=instances/*/databases/*}:sync | * |
| SyncDatabase | POST | /v1/{name=projects/*/instances/*/databases/*}:sync | * |
| BatchSyncDatabases | POST | /v1/{parent=instances/*}/databases:batchSync | * |
| BatchSyncDatabases | POST | /v1/{parent=projects/*/instances/*}/databases:batchSync | * |
| GetDatabaseMetadata | GET | /v1/{name=instances/*/databases/*/metadata} | |
| GetDatabaseMetadata | GET | /v1/{name=projects/*/instances/*/databases/*/metadata} | |
| GetDatabaseSchema | GET | /v1/{name=instances/*/databases/*/schema} | |
| GetDatabaseSchema | GET | /v1/{name=projects/*/instances/*/databases/*/schema} | |
| GetDatabaseSDLSchema | GET | /v1/{name=instances/*/databases/*/sdlSchema} | |
| GetDatabaseSDLSchema | GET | /v1/{name=projects/*/instances/*/databases/*/sdlSchema} | |
| DiffSchema | POST | /v1/{name=instances/*/databases/*}:diffSchema | * |
| DiffSchema | POST | /v1/{name=projects/*/instances/*/databases/*}:diffSchema | * |
| DiffSchema | POST | /v1/{name=instances/*/databases/*/changelogs/*}:diffSchema | * |
| DiffSchema | POST | /v1/{name=projects/*/instances/*/databases/*/changelogs/*}:diffSchema | * |
| DiffMetadata | POST | /v1/{name=instances/*/databases/*}:diffMetadata | * |
| DiffMetadata | POST | /v1/{name=projects/*/instances/*/databases/*}:diffMetadata | * |
| GetSchemaString | GET | /v1/{name=instances/*/databases/*/schemaString} | |
| GetSchemaString | GET | /v1/{name=projects/*/instances/*/databases/*/schemaString} |
Request message for batch getting groups.
| Field | Type | Label | Description |
| names | string | repeated | The group names to retrieve. Format: groups/{email} |
Response message for batch getting groups.
| Field | Type | Label | Description |
| groups | Group | repeated | One group per requested name, in the same order as `names`. |
Request message for creating a group.
| Field | Type | Label | Description |
| group | Group | The group to create. |
|
| group_email | string | The email to use for the group, which will become the final component of the group's resource name. |
Request message for deleting a group.
| Field | Type | Label | Description |
| name | string | The name of the group to delete. Format: groups/{email} |
Request message for getting a group.
| Field | Type | Label | Description |
| name | string | The name of the group to retrieve. Format: groups/{email} |
A group of users within the workspace.
| Field | Type | Label | Description |
| name | string | The name of the group to retrieve. Format: groups/{group}, the group should be email or uuid. |
|
| title | string | The display title of the group. |
|
| description | string | The description of the group. |
|
| members | GroupMember | repeated | The members of the group. |
| source | string | The source system where the group originated (e.g., Entra ID for SCIM sync). |
|
| string | The unique email for the group. |
A member of a group with a role.
| Field | Type | Label | Description |
| member | string | Member is the principal who belong to this group. Format: users/hello@world.com |
|
| role | GroupMember.Role | The member's role in the group. |
Request message for listing groups.
| Field | Type | Label | Description |
| page_size | int32 | The maximum number of groups to return. The service may return fewer than this value. If unspecified, at most 10 groups will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListGroups` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListGroups` must match the call that provided the page token. |
|
| filter | string | Filter is used to filter groups returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - title: the group title, support "==" and ".contains()" operator. - email: the group email, support "==" and ".contains()" operator. - project: the project full name in "projects/{id}" format, support "==" operator. For example: title == "dba" email == "dba@bytebase.com" title.contains("dba") email.contains("dba") project == "projects/sample-project" You can combine filter conditions like: title.contains("dba") || email.contains("dba") |
Response message for listing groups.
| Field | Type | Label | Description |
| groups | Group | repeated | The groups from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
Request message for updating a group.
| Field | Type | Label | Description |
| group | Group | The group to update. The group's `name` field is used to identify the group to update. Format: groups/{email} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the group is not found, a new group will be created. In this situation, `update_mask` is ignored. |
The role of a group member.
| Name | Number | Description |
| ROLE_UNSPECIFIED | 0 | Unspecified role. |
| OWNER | 1 | Group owner. |
| MEMBER | 2 | Group member. |
GroupService manages user groups for organizing users and permissions.
| Method Name | Request Type | Response Type | Description |
| GetGroup | GetGroupRequest | Group | Gets a group by name. Group members or users with bb.groups.get permission can get the group. Permissions required: bb.groups.get OR caller is the group member |
| BatchGetGroups | BatchGetGroupsRequest | BatchGetGroupsResponse | Gets multiple groups in a single request. Group members or users with bb.groups.get permission can get the group. One resource per requested name, in request order. The first name that does not resolve fails the whole call (AIP-231: no partial response). Permissions required: bb.groups.get OR caller is the group member |
| ListGroups | ListGroupsRequest | ListGroupsResponse | Lists all groups in the workspace. Permissions required: bb.groups.list |
| CreateGroup | CreateGroupRequest | Group | Creates a new group. Permissions required: bb.groups.create |
| UpdateGroup | UpdateGroupRequest | Group | Updates a group. Group owners or users with bb.groups.update permission can update. Permissions required: bb.groups.update OR caller is group owner When allow_missing=true, also requires: bb.groups.create |
| DeleteGroup | DeleteGroupRequest | .google.protobuf.Empty | Deletes a group. Group owners or users with bb.groups.delete permission can delete. Permissions required: bb.groups.delete OR caller is group owner |
| Method Name | Method | Pattern | Body |
| GetGroup | GET | /v1/{name=groups/*} | |
| BatchGetGroups | GET | /v1/groups:batchGet | |
| ListGroups | GET | /v1/groups | |
| CreateGroup | POST | /v1/groups | group |
| UpdateGroup | PATCH | /v1/{group.name=groups/*} | group |
| DeleteGroup | DELETE | /v1/{name=groups/*} |
| Field | Type | Label | Description |
| parent | string | The parent resource where this instance will be created. Workspace resource name: workspaces/{workspace-id}. Environment resource name: environments/environment-id. |
|
| policy | Policy | The policy to create. |
|
| type | PolicyType | The type of policy to create. |
| Field | Type | Label | Description |
| name | string | The policy's `name` field is used to identify the instance to update. Format: {resource name}/policies/{policy type} Workspace resource name: workspaces/{workspace-id}. Environment resource name: environments/environment-id. |
| Field | Type | Label | Description |
| name | string | The name of the policy to retrieve. Format: {resource type}/{resource id}/policies/{policy type} |
| Field | Type | Label | Description |
| parent | string | The parent, which owns this collection of policies. Format: {resource type}/{resource id} |
|
| policy_type | PolicyType | optional | Filter by specific policy type. |
| show_deleted | bool | Show deleted policies if specified. |
| Field | Type | Label | Description |
| policies | Policy | repeated | The policies from the specified request. |
MaskingExemptionPolicy is the allowlist of users who can access sensitive data.
| Field | Type | Label | Description |
| exemptions | MaskingExemptionPolicy.Exemption | repeated |
|
| Field | Type | Label | Description |
| members | string | repeated | Specifies the principals who are exempt from masking. For users, the member should be: user:{email} For groups, the member should be: group:{email} For service accounts, the member should be: serviceAccount:{email} For workload identities, the member should be: workloadIdentity:{email} |
| condition | google.type.Expr | The condition that is associated with this exception policy instance. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec If the condition is empty, means the user can access all databases without expiration. Support variables: resource.instance_id: the instance resource id. Only support "==" operation. resource.database_name: the database name. Only support "==" operation. resource.schema_name: the schema name. Only support "==" operation. resource.table_name: the table name. Only support "==" operation. resource.column_name: the column name. Only support "==" operation. request.time: the expiration. Only support "<" operation in `request.time < timestamp("{ISO datetime string format}")` All variables should join with "&&" condition. For example: resource.instance_id == "local" && resource.database_name == "employee" && request.time < timestamp("2025-04-30T11:10:39.000Z") resource.instance_id == "local" && resource.database_name == "employee" |
Policy for configuring data masking rules.
| Field | Type | Label | Description |
| rules | MaskingRulePolicy.MaskingRule | repeated | The list of masking rules. |
A rule that defines when and how to mask data.
| Field | Type | Label | Description |
| id | string | A unique identifier for the rule in UUID format. |
|
| condition | google.type.Expr | The condition for the masking rule. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Support variables: resource.environment_id: the environment resource id. resource.project_id: the project resource id. resource.instance_id: the instance resource id. resource.database_name: the database name. resource.table_name: the table name. resource.column_name: the column name. resource.classification_level: the classification level (integer). Each variable support following operations: ==: the value equals the target. !=: the value not equals the target. in: the value matches one of the targets. !(in): the value not matches any of the targets. <, <=, >, >=: numeric comparison (classification_level only). For example: resource.environment_id == "test" && resource.project_id == "sample-project" resource.instance_id == "sample-instance" && resource.database_name == "employee" && resource.table_name in ["table1", "table2"] resource.environment_id != "test" || !(resource.project_id in ["poject1", "prject2"]) resource.instance_id == "sample-instance" && (resource.database_name == "db1" || resource.database_name == "db2") |
|
| semantic_type | string | The semantic type of data to mask (e.g., "SSN", "EMAIL"). |
| Field | Type | Label | Description |
| name | string | The name of the policy. Format: {resource name}/policies/{policy type} Workspace resource name: workspaces/{workspace-id}. Environment resource name: environments/environment-id. |
|
| inherit_from_parent | bool | Whether this policy inherits from its parent resource. |
|
| type | PolicyType | The type of policy. |
|
| rollout_policy | RolloutPolicy |
|
|
| masking_rule_policy | MaskingRulePolicy |
|
|
| masking_exemption_policy | MaskingExemptionPolicy |
|
|
| tag_policy | TagPolicy |
|
|
| query_data_policy | QueryDataPolicy |
|
|
| review_rule_policy | ReviewRulePolicy |
|
|
| review_ai_policy | ReviewAIPolicy |
|
|
| enforce | bool | Whether the policy is enforced. |
|
| resource_type | PolicyResourceType | The resource type for the policy. |
QueryDataPolicy is the policy configuration for querying data in the SQL Editor.
| Field | Type | Label | Description |
| maximum_result_rows | int32 | Support both project-level and workspace-level. The maximum number of rows to return in the SQL editor. The default value <= 0, means no limit. |
|
| disable_export | bool | Deprecated. Deprecated: export is controlled by the bb.sql.export permission. Always false; setting it to true is rejected. |
|
| disable_copy_data | bool | workspace-level policy Disable copying query results in the SQL editor. |
|
| allow_admin_data_source | bool | workspace-level policy Allow using the admin data source to query in the SQL editor. If true, users can select the admin data source or read-only data source If false, 1. when read-only data source is configured, users're force to use the read-only data source 2. otherwise fallback to use the admin data source. |
|
| disable_download | bool | workspace-level policy Disable the Download export destination. Exports can still go to a configured storage destination such as SharePoint. |
| Name | Option |
| disable_export | true |
Natural-language policy for the AI review. Unlike the review rule policy,
both levels apply: the workspace policy and the project policy both reach
the reviewer, and the project policy wins where they conflict.
| Field | Type | Label | Description |
| content | string | The policy text. Must not be blank, at most 64 KiB. |
Standard review rule policy: the rules switched on. The nearest policy
wins: a project's own policy applies as is; a project without one uses
the workspace policy; with neither, every rule is on. Getting the policy
of a project without its own is NOT_FOUND; getting the workspace's when it
has none returns every rule on.
SYNTAX gates the rest: the other rules judge only SQL that parses, so a
list without SYNTAX switches every rule off.
A saved list is explicit, so a rule added to the standard set in a later
release is appended to every saved policy by a data migration in that
release.
| Field | Type | Label | Description |
| rules | ReviewRuleType | repeated | The rules switched on. Unknown or unspecified values are rejected. |
Rollout policy configuration.
| Field | Type | Label | Description |
| automatic | bool | Whether rollout is automatic without manual approval. |
|
| roles | string | repeated | The roles that can approve rollout execution. |
Policy for tagging resources with metadata.
| Field | Type | Label | Description |
| tags | TagPolicy.TagsEntry | repeated | tags is the key - value map for resources. for example, the environment resource can have the sql review config tag, like "bb.tag.review_config": "reviewConfigs/{review config resource id}" |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| policy | Policy | The policy to update. The policy's `name` field is used to identify the instance to update. Format: {resource name}/policies/{policy type} Workspace resource name: workspaces/{workspace-id}. Environment resource name: environments/environment-id. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the policy is not found, a new policy will be created. In this situation, `update_mask` is ignored. |
The resource type that a policy can be attached to.
| Name | Number | Description |
| RESOURCE_TYPE_UNSPECIFIED | 0 | Unspecified resource type. |
| WORKSPACE | 1 | Workspace-level policy. |
| ENVIRONMENT | 2 | Environment-level policy. |
| PROJECT | 3 | Project-level policy. |
The type of organizational policy.
| Name | Number | Description |
| POLICY_TYPE_UNSPECIFIED | 0 | Unspecified policy type. |
| MASKING_RULE | 1 | Data masking rule policy. |
| MASKING_EXEMPTION | 2 | Data masking exemption policy. |
| ROLLOUT_POLICY | 3 | Rollout deployment policy. |
| TAG | 4 | Resource tag policy. |
| DATA_QUERY | 6 | Query data access policy. |
| REVIEW_RULE | 7 | Standard review rule switch. Allowed on WORKSPACE and PROJECT. |
| REVIEW_AI | 8 | Natural-language policy for the AI review. Allowed on WORKSPACE and PROJECT. |
OrgPolicyService manages organizational policies at various resource levels.
| Method Name | Request Type | Response Type | Description |
| GetPolicy | GetPolicyRequest | Policy | Retrieves a policy by name. Permissions required: bb.policies.get |
| ListPolicies | ListPoliciesRequest | ListPoliciesResponse | Lists policies at a specified resource level. Permissions required: bb.policies.list |
| CreatePolicy | CreatePolicyRequest | Policy | Creates a new organizational policy. Permissions required: bb.policies.create |
| UpdatePolicy | UpdatePolicyRequest | Policy | Updates an existing organizational policy. Permissions required: bb.policies.update |
| DeletePolicy | DeletePolicyRequest | .google.protobuf.Empty | Deletes an organizational policy. Permissions required: bb.policies.delete |
| Method Name | Method | Pattern | Body |
| GetPolicy | GET | /v1/{name=workspaces/*/policies/*} | |
| GetPolicy | GET | /v1/{name=projects/*/policies/*} | |
| GetPolicy | GET | /v1/{name=environments/*/policies/*} | |
| ListPolicies | GET | /v1/{parent=workspaces/*}/policies | |
| ListPolicies | GET | /v1/{parent=projects/*}/policies | |
| ListPolicies | GET | /v1/{parent=environments/*}/policies | |
| CreatePolicy | POST | /v1/{parent=workspaces/*}/policies | policy |
| CreatePolicy | POST | /v1/{parent=projects/*}/policies | policy |
| CreatePolicy | POST | /v1/{parent=environments/*}/policies | policy |
| UpdatePolicy | PATCH | /v1/{policy.name=workspaces/*/policies/*} | policy |
| UpdatePolicy | PATCH | /v1/{policy.name=projects/*/policies/*} | policy |
| UpdatePolicy | PATCH | /v1/{policy.name=environments/*/policies/*} | policy |
| DeletePolicy | DELETE | /v1/{name=workspaces/*/policies/*} | |
| DeletePolicy | DELETE | /v1/{name=projects/*/policies/*} | |
| DeletePolicy | DELETE | /v1/{name=environments/*/policies/*} |
Activity types for webhook notifications.
| Field | Type | Label | Description |
| project | string | The name of the project to add the webhook to. Format: projects/{project} |
|
| webhook | Webhook | The webhook to add. |
| Field | Type | Label | Description |
| names | string | repeated | The names of the projects to delete. Format: projects/{project} |
| purge | bool | If set to true, permanently purge the soft-deleted projects and all related resources. This operation is irreversible. Following AIP-165, this should only be used for administrative cleanup of old soft-deleted projects. All projects must already be soft-deleted for this to work. When purge=true, all databases will be moved to the default project before deletion. When purge=false (soft delete/archive), the projects and their databases/issues remain unchanged. |
| Field | Type | Label | Description |
| names | string | repeated | The names of projects to retrieve. Format: projects/{project} |
| Field | Type | Label | Description |
| projects | Project | repeated | One project per requested name, in the same order as `names`. |
| Field | Type | Label | Description |
| project | Project | The project to create. |
|
| project_id | string | The ID to use for the project, which will become the final component of the project's resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/. |
| Field | Type | Label | Description |
| name | string | The name of the project to delete. Format: projects/{project} |
|
| purge | bool | If set to true, permanently purge the soft-deleted project and all related resources. This operation is irreversible. Following AIP-165, this should only be used for administrative cleanup of old soft-deleted projects. The project must already be soft-deleted for this to work. When purge=true, all databases will be moved to the default project before deletion. When purge=false (soft delete/archive), the project and its databases/issues remain unchanged. |
| Field | Type | Label | Description |
| name | string | The name of the project to retrieve. Format: projects/{project} |
A label for categorizing and organizing issues.
| Field | Type | Label | Description |
| value | string | The label value/name. |
|
| color | google.type.Color | The label color. |
|
| group | string | The group this label belongs to. |
| Field | Type | Label | Description |
| page_size | int32 | The maximum number of projects to return. The service may return fewer than this value. If unspecified, at most 10 projects will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListProjects` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListProjects` must match the call that provided the page token. |
|
| show_deleted | bool | Show deleted projects if specified. |
|
| filter | string | Filter the project. Check filter for SearchProjectsRequest for details. Supports filtering by name, resource_id, state, and labels (e.g., labels.environment == "production"). |
|
| order_by | string | The order by of projects. Support title. The default sorting order is ascending. For example: - order_by = "title" - order_by = "title desc" - order_by = "title asc" |
| Field | Type | Label | Description |
| projects | Project | repeated | The projects from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | The name of the project. Format: projects/{project} |
|
| state | State | The lifecycle state of the project. |
|
| title | string | The title or name of a project. It's not unique within the workspace. |
|
| webhooks | Webhook | repeated | The list of webhooks configured for the project. |
| data_classification_config_id | string | The data classification configuration ID for the project. |
|
| issue_labels | Label | repeated | Labels available for tagging issues in this project. |
| force_issue_labels | bool | Force issue labels to be used when creating an issue. |
|
| enforce_issue_title | bool | Enforce issue title to be created by user instead of generated by Bytebase. |
|
| postgres_database_tenant_mode | bool | Whether to enable database tenant mode for PostgreSQL. If enabled, issues will include "set role <db_owner>" statement. |
|
| allow_self_approval | bool | Whether to allow issue creators to self-approve their own issues. |
|
| execution_retry_policy | Project.ExecutionRetryPolicy | Execution retry policy for task runs. |
|
| ci_sampling_size | int32 | The maximum number of databases to sample during CI data validation and AI review. Without specification, sampling is disabled, resulting in full validation. |
|
| parallel_tasks_per_rollout | int32 | The maximum number of parallel tasks allowed during rollout execution. |
|
| labels | Project.LabelsEntry | repeated | Labels are key-value pairs that can be attached to the project. For example, { "environment": "production", "team": "backend" } |
| enforce_sql_review | bool | Whether to enforce SQL review checks to pass before issue creation. If enabled, issues cannot be created when SQL review finds errors. |
|
| require_issue_approval | bool | Whether to require issue approval before rollout. |
|
| require_plan_check_no_error | bool | Whether to require plan check to have no error before rollout. |
|
| allow_request_role | bool |
|
|
| allow_just_in_time_access | bool | Once enabled, users can request and use the just-in-time access in the SQL Editor. |
|
| allow_last_plan_editor_approval | bool | Whether to allow the last Plan editor to approve a database change issue. |
|
| export_setting | Project.ExportSetting | Export configuration for this project. |
Execution retry policy configuration.
| Field | Type | Label | Description |
| maximum_retries | int32 | The maximum number of retries for lock timeout errors. |
Destinations offered for this project's exports, at most one per provider.
| Field | Type | Label | Description |
| sharepoint | SharePointDestination | Unset when the project has no SharePoint destination. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
| Field | Type | Label | Description |
| webhook | Webhook | The webhook to remove. Identified by its url. |
| Field | Type | Label | Description |
| show_deleted | bool | Show deleted projects if specified. |
|
| filter | string | Filter the project. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filters: - name: the project name, support "==" and ".contains()" operator. - resource_id: the project id, support "==" and ".contains()" operator. - exclude_default: if not include the default project, should be "true" or "false", support "==" operator. - state: check the State enum for the values, support "==" operator. - labels.{key}: the project label, support "==" and "in" operators. For example: name == "project name" name.contains("project name") resource_id == "project id" resource_id.contains("project id") exclude_default == true state == "DELETED" labels.environment == "production" labels.tier == "critical" labels.environment in ["staging", "prod"] You can combine filter conditions like: name == "project name" && resource_id.contains("project id") name.contains("project name") || resource_id == "project id" labels.environment == "production" && labels.tier == "critical" |
|
| page_size | int32 | The maximum number of projects to return. The service may return fewer than this value. If unspecified, at most 10 projects will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `SearchProjects` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `SearchProjects` must match the call that provided the page token. |
|
| order_by | string | The order by of projects. Support title. The default sorting order is ascending. For example: - order_by = "title" - order_by = "title desc" - order_by = "title asc" |
| Field | Type | Label | Description |
| projects | Project | repeated | The projects from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
A SharePoint document library root or folder that receives exports.
| Field | Type | Label | Description |
| url | string | The URL of the library root or folder. Normalized to its canonical form and resolved with the workspace credentials on save. |
| Field | Type | Label | Description |
| project | string | The name of the project which owns the webhook to test. Format: projects/{project} |
|
| webhook | Webhook | The webhook to test. The url is what gets posted to. Reads do not return a saved webhook's url, so leave url empty and set name to test the one already stored; set url to test a url before saving it. |
| Field | Type | Label | Description |
| error | string | The result of the test, empty if the test is successful. |
| Field | Type | Label | Description |
| name | string | The name of the deleted project. Format: projects/{project} |
| Field | Type | Label | Description |
| project | Project | The project to update. The project's `name` field is used to identify the project to update. Format: projects/{project} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the project is not found, a new project will be created. In this situation, `update_mask` is ignored. |
| Field | Type | Label | Description |
| webhook | Webhook | The webhook to modify. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the webhook is not found, a new webhook will be created. In this situation, `update_mask` is ignored. |
| Field | Type | Label | Description |
| name | string | name is the name of the webhook, generated by the server. format: projects/{project}/webhooks/{webhook} |
|
| type | WebhookType | Webhook integration type. type is the type of the webhook. |
|
| title | string | title is the title of the webhook. |
|
| url | string | url is the url of the webhook, should be unique within the project. Write-only: an incoming-webhook url is the whole credential for posting into the customer's chat, so reads leave it empty, the same way a data source's password and SSL material are left empty. Set it to change it. Required to create a webhook. Not required on TestWebhook, where an empty url on a request that names a webhook means the one already stored, so the field carries no REQUIRED behavior it would contradict there. |
|
| url_supports_direct_message | bool | Whether the stored url's endpoint form can carry a direct message to the users an event mentions, rather than only a post to the channel the url names. False for a Microsoft Teams Power Automate workflow endpoint, which direct messages bypass entirely: a webhook with direct_message set sends them and returns, so the workflow post never happens. Reads do not return the url, so a client editing a saved webhook cannot work this out for itself. It is a fact about the stored url and says nothing about what the url is. |
|
| direct_message | bool | if direct_message is set, the notification is sent directly to the persons and url will be ignored. IM integration setting should be set for this function to work. |
|
| notification_types | Activity.Type | repeated | notification_types is the list of activities types that the webhook is interested in. Bytebase will only send notifications to the webhook if the activity type is in the list. It should not be empty, and should be a subset of the following: - ISSUE_CREATED - ISSUE_APPROVAL_REQUESTED - ISSUE_SENT_BACK - ISSUE_APPROVED - PIPELINE_FAILED - PIPELINE_COMPLETED |
Activity type enumeration.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified type. |
| ISSUE_CREATED | 10 | ISSUE_CREATED represents a new issue creation event. |
| ISSUE_APPROVAL_REQUESTED | 11 | ISSUE_APPROVAL_REQUESTED represents an approval request event. |
| ISSUE_SENT_BACK | 12 | ISSUE_SENT_BACK represents an issue being sent back by an approver. |
| PIPELINE_FAILED | 13 | PIPELINE_FAILED represents a pipeline failure event. |
| PIPELINE_COMPLETED | 14 | PIPELINE_COMPLETED represents a pipeline completion event. |
| ISSUE_APPROVED | 15 | ISSUE_APPROVED represents an issue being fully approved. |
ProjectService manages projects that group databases and changes.
| Method Name | Request Type | Response Type | Description |
| GetProject | GetProjectRequest | Project | GetProject retrieves a project by name. Users with "bb.projects.get" permission on the workspace or the project owner can access this method. Permissions required: bb.projects.get |
| BatchGetProjects | BatchGetProjectsRequest | BatchGetProjectsResponse | BatchGetProjects retrieves multiple projects by their names. One resource per requested name, in request order. The first name that does not resolve fails the whole call (AIP-231: no partial response). Permissions required: bb.projects.get (on each named project) |
| ListProjects | ListProjectsRequest | ListProjectsResponse | Lists all projects in the workspace with optional filtering. Permissions required: bb.projects.list |
| SearchProjects | SearchProjectsRequest | SearchProjectsResponse | Searches for projects with advanced filtering capabilities. Permissions required: bb.projects.get (or project-level bb.projects.get for specific projects) |
| CreateProject | CreateProjectRequest | Project | Creates a new project in the workspace. Permissions required: bb.projects.create |
| UpdateProject | UpdateProjectRequest | Project | Updates an existing project's properties. Permissions required: bb.projects.update |
| DeleteProject | DeleteProjectRequest | .google.protobuf.Empty | Deletes (soft-delete or purge) a project. Permissions required: bb.projects.delete |
| UndeleteProject | UndeleteProjectRequest | Project | Restores a soft-deleted project. Permissions required: bb.projects.undelete |
| BatchDeleteProjects | BatchDeleteProjectsRequest | .google.protobuf.Empty | Deletes multiple projects in a single operation. Permissions required: bb.projects.delete |
| GetIamPolicy | GetIamPolicyRequest | IamPolicy | Retrieves the IAM policy for a project. Permissions required: bb.projects.getIamPolicy |
| SetIamPolicy | SetIamPolicyRequest | IamPolicy | Sets the IAM policy for a project. Permissions required: bb.projects.setIamPolicy |
| AddWebhook | AddWebhookRequest | Project | Adds a webhook to a project for notifications. Permissions required: bb.projects.update |
| UpdateWebhook | UpdateWebhookRequest | Project | Updates an existing webhook configuration. Permissions required: bb.projects.update |
| RemoveWebhook | RemoveWebhookRequest | Project | Removes a webhook from a project. Permissions required: bb.projects.update |
| TestWebhook | TestWebhookRequest | TestWebhookResponse | Tests a webhook by sending a test notification. Permissions required: bb.projects.update |
| Method Name | Method | Pattern | Body |
| GetProject | GET | /v1/{name=projects/*} | |
| BatchGetProjects | GET | /v1/projects:batchGet | |
| ListProjects | GET | /v1/projects | |
| SearchProjects | POST | /v1/projects:search | * |
| CreateProject | POST | /v1/projects | project |
| UpdateProject | PATCH | /v1/{project.name=projects/*} | project |
| DeleteProject | DELETE | /v1/{name=projects/*} | |
| UndeleteProject | POST | /v1/{name=projects/*}:undelete | * |
| BatchDeleteProjects | POST | /v1/projects:batchDelete | * |
| GetIamPolicy | GET | /v1/{resource=projects/*}:getIamPolicy | |
| SetIamPolicy | POST | /v1/{resource=projects/*}:setIamPolicy | * |
| AddWebhook | POST | /v1/{project=projects/*}:addWebhook | * |
| UpdateWebhook | PATCH | /v1/{webhook.name=projects/*/webhooks/*}:updateWebhook | webhook |
| RemoveWebhook | POST | /v1/{webhook.name=projects/*/webhooks/*}:removeWebhook | * |
| TestWebhook | POST | /v1/{project=projects/*}:testWebhook | * |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
|
| release | Release | The release to check. |
|
| targets | string | repeated | The targets to dry-run the release. Can be database or databaseGroup. Format: projects/{project}/databaseGroups/{databaseGroup} instances/{instance}/databases/{database} projects/{project}/instances/{instance}/databases/{database} |
| custom_rules | string | Custom linting rules in natural language for AI-powered validation. Each rule should be a clear statement describing the desired schema constraint. Example: "All tables must have a primary key" Example: "VARCHAR columns should specify a maximum length" |
|
| vcs_user | VCSUser | The non-bot VCS pull request or merge request creator observed by bytebase-release. If absent, Bytebase skips VCS user tracking and VCS user limit enforcement. |
| Field | Type | Label | Description |
| results | CheckReleaseResponse.CheckResult | repeated | The check results for each file and target combination. |
| affected_rows | int64 | The total affected rows across all checks. |
|
| risk_level | RiskLevel | The aggregated risk level of the check. |
Check result for a single release file on a target database.
| Field | Type | Label | Description |
| file | string | The file path that is being checked. |
|
| target | string | The target that the check is performed on. Should be a database. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| advices | Advice | repeated | The list of advice for the file and the target. |
| affected_rows | int64 | The count of affected rows of the statement on the target. |
|
| risk_level | RiskLevel | The risk level of the statement on the target. |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
|
| release | Release | The release to create. |
|
| release_id_template | string | Template for release ID generation. Available variables: {date}, {time}, {timestamp}, {iteration}. Example: "release_{date}-RC{iteration}" generates "release_20260119-RC00". Default: "release_{date}-RC{iteration}". |
|
| release_id_timezone | string | Timezone for {date} and {time} variables in the template. Must be a valid IANA timezone (e.g., "UTC", "America/Los_Angeles"). Default: "UTC". |
| Field | Type | Label | Description |
| name | string | The name of the release to delete. Format: projects/{project}/releases/{release} |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/releases/{release} |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
| Field | Type | Label | Description |
| categories | string | repeated | The unique category values in the project. |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
|
| page_size | int32 | The maximum number of releases to return. The service may return fewer than this value. If unspecified, at most 10 releases will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListReleases` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListReleases` must match the call that provided the page token. |
|
| show_deleted | bool | Show deleted releases if specified. |
|
| filter | string | Filter is used to filter releases returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filters: - category: release category, support "==" operator. For example: category == "webapp" |
| Field | Type | Label | Description |
| releases | Release | repeated | The releases from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/releases/{release} |
|
| category | string | Category extracted from release name (e.g., "webapp", "analytics"). Set by Bytebase action during release creation. |
|
| files | Release.File | repeated | The SQL files included in the release. |
| vcs_source | Release.VCSSource | The version control source of the release. |
|
| creator | string | Format: users/hello@world.com |
|
| create_time | google.protobuf.Timestamp |
|
|
| state | State | The lifecycle state of the release. |
|
| type | Release.Type | The type of schema change for all files in this release. |
A SQL file in a release.
| Field | Type | Label | Description |
| path | string | The path of the file. e.g., `2.2/V0001_create_table.sql`. |
|
| version | string | The version identifier for the file. |
|
| sheet | string | For inputs, we must either use `sheet` or `statement`. For outputs, we always use `sheet`. `statement` is the preview of the sheet content. The sheet that holds the content. Format: projects/{project}/sheets/{sheet} |
|
| statement | bytes | The raw SQL statement content. |
|
| sheet_sha256 | string | The SHA256 hash value of the sheet content or the statement. |
Version control system source information.
| Field | Type | Label | Description |
| vcs_type | VCSType | The type of VCS. |
|
| url | string | The url link to the e.g., GitHub commit or pull request. |
| Field | Type | Label | Description |
| name | string | The name of the deleted release. Format: projects/{project}/releases/{release} |
| Field | Type | Label | Description |
| release | Release | The release to update. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to be updated. |
| Field | Type | Label | Description |
| vcs_type | VCSType |
|
|
| user_id | string |
|
|
| user_name | string |
|
|
| display_name | string |
|
The type of schema change.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified type. |
| VERSIONED | 1 | Versioned schema migration. |
| DECLARATIVE | 2 | Declarative schema definition. |
ReleaseService manages releases for coordinating deployments.
| Method Name | Request Type | Response Type | Description |
| GetRelease | GetReleaseRequest | Release | Retrieves a release by name. Permissions required: bb.releases.get |
| ListReleases | ListReleasesRequest | ListReleasesResponse | Lists releases in a project. Permissions required: bb.releases.list |
| CreateRelease | CreateReleaseRequest | Release | Creates a new release with SQL files. Permissions required: bb.releases.create |
| UpdateRelease | UpdateReleaseRequest | Release | Updates an existing release. Permissions required: bb.releases.update When allow_missing=true, also requires: bb.releases.create |
| DeleteRelease | DeleteReleaseRequest | .google.protobuf.Empty | Deletes a release. Permissions required: bb.releases.delete |
| UndeleteRelease | UndeleteReleaseRequest | Release | Restores a deleted release. Permissions required: bb.releases.undelete |
| CheckRelease | CheckReleaseRequest | CheckReleaseResponse | Validates a release by dry-running checks on target databases. Permissions required: bb.releases.check |
| ListReleaseCategories | ListReleaseCategoriesRequest | ListReleaseCategoriesResponse | Lists all unique categories in a project. Permissions required: bb.releases.list |
| Method Name | Method | Pattern | Body |
| GetRelease | GET | /v1/{name=projects/*/releases/*} | |
| ListReleases | GET | /v1/{parent=projects/*}/releases | |
| CreateRelease | POST | /v1/{parent=projects/*}/releases | release |
| UpdateRelease | PATCH | /v1/{release.name=projects/*/releases/*} | release |
| DeleteRelease | DELETE | /v1/{name=projects/*/releases/*} | |
| UndeleteRelease | POST | /v1/{name=projects/*/releases/*}:undelete | |
| CheckRelease | POST | /v1/{parent=projects/*}/releases:check | * |
| ListReleaseCategories | GET | /v1/{parent=projects/*}/releases:listCategories |
| Field | Type | Label | Description |
| review_config | ReviewConfig | The SQL review config to create. |
| Field | Type | Label | Description |
| name | string | The name of the SQL review config to delete. Format: reviewConfigs/{reviewConfig} |
| Field | Type | Label | Description |
| name | string | The name of the SQL review config to retrieve. Format: reviewConfigs/{reviewConfig} |
| Field | Type | Label | Description |
| review_configs | ReviewConfig | repeated | The SQL review configs from the specified request. |
| Field | Type | Label | Description |
| name | string | The name of the SQL review config. Format: reviewConfigs/{reviewConfig} |
|
| title | string | The title of the review configuration. |
|
| enabled | bool | Whether the review configuration is enabled. |
|
| rules | SQLReviewRule | repeated | The SQL review rules to enforce. |
| resources | string | repeated | Resources using the config. Format: {resource}/{resource id}, e.g., environments/test. |
SQL review rule configuration. Check the SQL_REVIEW_RULES_DOCUMENTATION.md for details.
| Field | Type | Label | Description |
| type | SQLReviewRule.Type | The type of SQL review rule. |
|
| level | SQLReviewRule.Level | The severity level of the rule. |
|
| naming_payload | SQLReviewRule.NamingRulePayload |
|
|
| number_payload | SQLReviewRule.NumberRulePayload |
|
|
| string_array_payload | SQLReviewRule.StringArrayRulePayload |
|
|
| comment_convention_payload | SQLReviewRule.CommentConventionRulePayload |
|
|
| string_payload | SQLReviewRule.StringRulePayload |
|
|
| naming_case_payload | SQLReviewRule.NamingCaseRulePayload |
|
|
| engine | Engine | The database engine this rule applies to. |
| Field | Type | Label | Description |
| required | bool |
|
|
| max_length | int32 |
|
| Field | Type | Label | Description |
| upper | bool |
|
Payload message types for SQL review rules
| Field | Type | Label | Description |
| max_length | int32 |
|
|
| format | string |
|
| Field | Type | Label | Description |
| number | int32 |
|
| Field | Type | Label | Description |
| list | string | repeated |
|
| Field | Type | Label | Description |
| value | string |
|
| Field | Type | Label | Description |
| review_config | ReviewConfig | The SQL review config to update. The name field is used to identify the SQL review config to update. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the config is not found, a new config will be created. In this situation, `update_mask` is ignored. |
The severity level for SQL review rules.
| Name | Number | Description |
| LEVEL_UNSPECIFIED | 0 | Unspecified level. |
| ERROR | 1 | Rule violation is an error. |
| WARNING | 2 | Rule violation is a warning. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| ENGINE_MYSQL_USE_INNODB | 1 | |
| NAMING_FULLY_QUALIFIED | 2 | |
| NAMING_TABLE | 3 | |
| NAMING_COLUMN | 4 | |
| NAMING_INDEX_PK | 5 | |
| NAMING_INDEX_UK | 6 | |
| NAMING_INDEX_FK | 7 | |
| NAMING_INDEX_IDX | 8 | |
| NAMING_COLUMN_AUTO_INCREMENT | 9 | |
| NAMING_TABLE_NO_KEYWORD | 10 | |
| NAMING_IDENTIFIER_NO_KEYWORD | 11 | |
| NAMING_IDENTIFIER_CASE | 12 | |
| STATEMENT_SELECT_NO_SELECT_ALL | 13 | |
| STATEMENT_WHERE_REQUIRE_SELECT | 14 | |
| STATEMENT_WHERE_REQUIRE_UPDATE_DELETE | 15 | |
| STATEMENT_WHERE_NO_LEADING_WILDCARD_LIKE | 16 | |
| STATEMENT_DISALLOW_ON_DEL_CASCADE | 17 | |
| STATEMENT_DISALLOW_RM_TBL_CASCADE | 18 | |
| STATEMENT_DISALLOW_COMMIT | 19 | |
| STATEMENT_DISALLOW_LIMIT | 20 | |
| STATEMENT_DISALLOW_ORDER_BY | 21 | |
| STATEMENT_MERGE_ALTER_TABLE | 22 | |
| STATEMENT_INSERT_ROW_LIMIT | 23 | |
| STATEMENT_INSERT_MUST_SPECIFY_COLUMN | 24 | |
| STATEMENT_INSERT_DISALLOW_ORDER_BY_RAND | 25 | |
| STATEMENT_AFFECTED_ROW_LIMIT | 26 | |
| STATEMENT_DML_DRY_RUN | 27 | |
| STATEMENT_DISALLOW_ADD_COLUMN_WITH_DEFAULT | 28 | |
| STATEMENT_ADD_CHECK_NOT_VALID | 29 | |
| STATEMENT_ADD_FOREIGN_KEY_NOT_VALID | 30 | |
| STATEMENT_DISALLOW_ADD_NOT_NULL | 31 | |
| STATEMENT_CREATE_SPECIFY_SCHEMA | 33 | |
| STATEMENT_CHECK_SET_ROLE_VARIABLE | 34 | |
| STATEMENT_WHERE_NO_EQUAL_NULL | 37 | |
| STATEMENT_WHERE_DISALLOW_FUNCTIONS_AND_CALCULATIONS | 38 | |
| STATEMENT_WHERE_MAXIMUM_LOGICAL_OPERATOR_COUNT | 40 | |
| STATEMENT_MAXIMUM_STATEMENTS_IN_TRANSACTION | 43 | |
| STATEMENT_NON_TRANSACTIONAL | 45 | |
| STATEMENT_ADD_COLUMN_WITHOUT_POSITION | 46 | |
| STATEMENT_DISALLOW_OFFLINE_DDL | 47 | |
| STATEMENT_DISALLOW_CROSS_DB_QUERIES | 48 | |
| STATEMENT_MAX_EXECUTION_TIME | 49 | |
| STATEMENT_REQUIRE_ALGORITHM_OPTION | 50 | |
| STATEMENT_REQUIRE_LOCK_OPTION | 51 | |
| STATEMENT_OBJECT_OWNER_CHECK | 52 | |
| TABLE_REQUIRE_PK | 53 | |
| TABLE_NO_FOREIGN_KEY | 54 | |
| TABLE_DROP_NAMING_CONVENTION | 55 | |
| TABLE_COMMENT | 56 | |
| TABLE_DISALLOW_PARTITION | 57 | |
| TABLE_DISALLOW_TRIGGER | 58 | |
| TABLE_NO_DUPLICATE_INDEX | 59 | |
| TABLE_TEXT_FIELDS_TOTAL_LENGTH | 60 | |
| TABLE_DISALLOW_SET_CHARSET | 61 | |
| TABLE_DISALLOW_DDL | 62 | |
| TABLE_DISALLOW_DML | 63 | |
| TABLE_LIMIT_SIZE | 64 | |
| TABLE_REQUIRE_CHARSET | 65 | |
| TABLE_REQUIRE_COLLATION | 66 | |
| COLUMN_REQUIRED | 67 | |
| COLUMN_NO_NULL | 68 | |
| COLUMN_DISALLOW_CHANGE_TYPE | 69 | |
| COLUMN_SET_DEFAULT_FOR_NOT_NULL | 70 | |
| COLUMN_DISALLOW_CHANGE | 71 | |
| COLUMN_DISALLOW_CHANGING_ORDER | 72 | |
| COLUMN_DISALLOW_DROP | 73 | |
| COLUMN_DISALLOW_DROP_IN_INDEX | 74 | |
| COLUMN_COMMENT | 75 | |
| COLUMN_AUTO_INCREMENT_MUST_INTEGER | 76 | |
| COLUMN_TYPE_DISALLOW_LIST | 77 | |
| COLUMN_DISALLOW_SET_CHARSET | 78 | |
| COLUMN_MAXIMUM_CHARACTER_LENGTH | 79 | |
| COLUMN_MAXIMUM_VARCHAR_LENGTH | 80 | |
| COLUMN_AUTO_INCREMENT_INITIAL_VALUE | 81 | |
| COLUMN_AUTO_INCREMENT_MUST_UNSIGNED | 82 | |
| COLUMN_CURRENT_TIME_COUNT_LIMIT | 83 | |
| COLUMN_REQUIRE_DEFAULT | 84 | |
| COLUMN_DEFAULT_DISALLOW_VOLATILE | 85 | |
| COLUMN_ADD_NOT_NULL_REQUIRE_DEFAULT | 86 | |
| COLUMN_REQUIRE_CHARSET | 87 | |
| COLUMN_REQUIRE_COLLATION | 88 | |
| SCHEMA_BACKWARD_COMPATIBILITY | 89 | |
| DATABASE_DROP_EMPTY_DATABASE | 90 | |
| INDEX_NO_DUPLICATE_COLUMN | 91 | |
| INDEX_KEY_NUMBER_LIMIT | 92 | |
| INDEX_PK_TYPE_LIMIT | 93 | |
| INDEX_TYPE_NO_BLOB | 94 | |
| INDEX_TOTAL_NUMBER_LIMIT | 95 | |
| INDEX_PRIMARY_KEY_TYPE_ALLOWLIST | 96 | |
| INDEX_CREATE_CONCURRENTLY | 97 | |
| INDEX_TYPE_ALLOW_LIST | 98 | |
| INDEX_NOT_REDUNDANT | 99 | |
| SYSTEM_CHARSET_ALLOWLIST | 100 | |
| SYSTEM_COLLATION_ALLOWLIST | 101 | |
| SYSTEM_COMMENT_LENGTH | 102 | |
| SYSTEM_PROCEDURE_DISALLOW_CREATE | 103 | |
| SYSTEM_EVENT_DISALLOW_CREATE | 104 | |
| SYSTEM_VIEW_DISALLOW_CREATE | 105 | |
| SYSTEM_FUNCTION_DISALLOW_CREATE | 106 | |
| SYSTEM_FUNCTION_DISALLOWED_LIST | 107 | |
| ADVICE_ONLINE_MIGRATION | 108 | |
| BUILTIN_PRIOR_BACKUP_CHECK | 109 | |
| BUILTIN_WALK_THROUGH_CHECK | 110 | |
| STATEMENT_DISALLOW_TRUNCATE | 111 | |
| BUILTIN_STATEMENT_MAXIMUM_SQL_SIZE | 112 |
ReviewConfigService manages approval flow configurations.
| Method Name | Request Type | Response Type | Description |
| CreateReviewConfig | CreateReviewConfigRequest | ReviewConfig | Creates a new SQL review configuration. Permissions required: bb.reviewConfigs.create |
| ListReviewConfigs | ListReviewConfigsRequest | ListReviewConfigsResponse | Lists all SQL review configurations. Permissions required: bb.reviewConfigs.list |
| GetReviewConfig | GetReviewConfigRequest | ReviewConfig | Retrieves a SQL review configuration by name. Permissions required: bb.reviewConfigs.get |
| UpdateReviewConfig | UpdateReviewConfigRequest | ReviewConfig | Updates a SQL review configuration. Permissions required: bb.reviewConfigs.update When allow_missing=true, also requires: bb.reviewConfigs.create |
| DeleteReviewConfig | DeleteReviewConfigRequest | .google.protobuf.Empty | Deletes a SQL review configuration. Permissions required: bb.reviewConfigs.delete |
| Method Name | Method | Pattern | Body |
| CreateReviewConfig | POST | /v1/reviewConfigs | review_config |
| ListReviewConfigs | GET | /v1/reviewConfigs | |
| GetReviewConfig | GET | /v1/{name=reviewConfigs/*} | |
| UpdateReviewConfig | PATCH | /v1/{review_config.name=reviewConfigs/*} | review_config |
| DeleteReviewConfig | DELETE | /v1/{name=reviewConfigs/*} |
| Field | Type | Label | Description |
| parent | string | The parent resource shared by all revisions being created. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| requests | CreateRevisionRequest | repeated | The request message specifying the revisions to create. A maximum of 100 revisions can be created in a batch. |
| Field | Type | Label | Description |
| revisions | Revision | repeated | The created revisions. |
| Field | Type | Label | Description |
| parent | string | Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| revision | Revision | The revision to create. |
| Field | Type | Label | Description |
| name | string | The name of the revision to delete. Format: instances/{instance}/databases/{database}/revisions/{revision} or projects/{project}/instances/{instance}/databases/{database}/revisions/{revision} |
| Field | Type | Label | Description |
| name | string | The name of the revision. Format: instances/{instance}/databases/{database}/revisions/{revision} or projects/{project}/instances/{instance}/databases/{database}/revisions/{revision} |
| Field | Type | Label | Description |
| parent | string | The parent of the revisions. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| page_size | int32 | The maximum number of revisions to return. The service may return fewer than this value. If unspecified, at most 10 revisions will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListRevisions` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListRevisions` must match the call that provided the page token. |
|
| show_deleted | bool | Whether to include deleted revisions in the results. |
| Field | Type | Label | Description |
| revisions | Revision | repeated | The revisions from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| Field | Type | Label | Description |
| name | string | Format: instances/{instance}/databases/{database}/revisions/{revision} or projects/{project}/instances/{instance}/databases/{database}/revisions/{revision} |
|
| release | string | Format: projects/{project}/releases/{release} Can be empty. |
|
| create_time | google.protobuf.Timestamp |
|
|
| deleter | string | Format: users/hello@world.com Can be empty. |
|
| delete_time | google.protobuf.Timestamp | Can be empty. |
|
| file | string | Format: projects/{project}/releases/{release}/files/{file_path} The file_path segment is URL-encoded since file paths may contain "/". Can be empty. |
|
| version | string | The schema version string for this revision. |
|
| sheet | string | The sheet that holds the content. Format: projects/{project}/sheets/{sheet} |
|
| sheet_sha256 | string | The SHA256 hash value of the sheet. |
|
| task_run | string | The task run associated with the revision. Can be empty. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun} |
|
| type | Revision.Type | The type of the revision. |
The type of schema revision.
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | Unspecified type. |
| VERSIONED | 1 | Versioned schema migration. |
| DECLARATIVE | 2 | Declarative schema definition. |
RevisionService manages schema revision history.
| Method Name | Request Type | Response Type | Description |
| ListRevisions | ListRevisionsRequest | ListRevisionsResponse | Lists schema revisions for a database. Permissions required: bb.revisions.list |
| GetRevision | GetRevisionRequest | Revision | Retrieves a schema revision by name. Permissions required: bb.revisions.get |
| BatchCreateRevisions | BatchCreateRevisionsRequest | BatchCreateRevisionsResponse | Creates multiple schema revisions in a single operation. Permissions required: bb.revisions.create |
| DeleteRevision | DeleteRevisionRequest | .google.protobuf.Empty | Deletes a schema revision. Permissions required: bb.revisions.delete |
| Method Name | Method | Pattern | Body |
| ListRevisions | GET | /v1/{parent=instances/*/databases/*}/revisions | |
| ListRevisions | GET | /v1/{parent=projects/*/instances/*/databases/*}/revisions | |
| GetRevision | GET | /v1/{name=instances/*/databases/*/revisions/*} | |
| GetRevision | GET | /v1/{name=projects/*/instances/*/databases/*/revisions/*} | |
| BatchCreateRevisions | POST | /v1/{parent=instances/*/databases/*}/revisions:batchCreate | * |
| BatchCreateRevisions | POST | /v1/{parent=projects/*/instances/*/databases/*}/revisions:batchCreate | * |
| DeleteRevision | DELETE | /v1/{name=instances/*/databases/*/revisions/*} | |
| DeleteRevision | DELETE | /v1/{name=projects/*/instances/*/databases/*/revisions/*} |
| Field | Type | Label | Description |
| role | Role | The role to create. |
|
| role_id | string | The ID to use for the role, which will become the final component of the role's resource name. This value should be 4-63 characters, and valid characters are /[a-z][A-Z][0-9]/. |
| Field | Type | Label | Description |
| name | string | The name of the role to delete. Format: roles/{role} |
| Field | Type | Label | Description |
| name | string | The name of the role to retrieve. Format: roles/{role} |
| Field | Type | Label | Description |
| roles | Role | repeated | The roles from the specified request. |
Role defines a set of permissions that can be assigned to users.
| Field | Type | Label | Description |
| name | string | Resource name. Format: roles/{role} |
|
| title | string | Human-readable title. |
|
| description | string | Optional description of the role. |
|
| permissions | string | repeated | List of permission identifiers granted by this role. |
| type | Role.Type | Role type indicating if it's built-in or custom. |
| Field | Type | Label | Description |
| role | Role | The role to update. |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. |
|
| allow_missing | bool | If set to true, and the role is not found, a new role will be created. In this situation, `update_mask` is ignored. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| BUILT_IN | 1 | System-defined role that cannot be modified. |
| CUSTOM | 2 | User-defined role that can be modified. |
RoleService manages workspace roles and permissions.
| Method Name | Request Type | Response Type | Description |
| ListRoles | ListRolesRequest | ListRolesResponse | Lists roles in the workspace. Permissions required: bb.roles.list |
| GetRole | GetRoleRequest | Role | Retrieves a role by name. Permissions required: bb.roles.get |
| CreateRole | CreateRoleRequest | Role | Creates a new custom role. Permissions required: bb.roles.create |
| UpdateRole | UpdateRoleRequest | Role | Updates a role's properties. Permissions required: bb.roles.update When allow_missing=true, also requires: bb.roles.create |
| DeleteRole | DeleteRoleRequest | .google.protobuf.Empty | Deletes a custom role. Permissions required: bb.roles.delete |
| Method Name | Method | Pattern | Body |
| ListRoles | GET | /v1/roles | |
| GetRole | GET | /v1/{name=roles/*} | |
| CreateRole | POST | /v1/roles | role |
| UpdateRole | PATCH | /v1/{role.name=roles/*} | role |
| DeleteRole | DELETE | /v1/{name=roles/*} |
| Field | Type | Label | Description |
| parent | string | The project to create the saved query in. Format: projects/{project} |
|
| saved_query | SavedQuery | The saved query to create. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/savedQueries/{savedQuery} |
| Field | Type | Label | Description |
| resource | string | Format: projects/{project}/savedQueries/{savedQuery} |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/savedQueries/{savedQuery} |
| Field | Type | Label | Description |
| parent | string | The project to list saved queries in, or "projects/-" for every project. Format: projects/{project} |
|
| filter | string | Filter the result, in CEL. See https://github.com/google/cel-spec Supported fields: - creator: the creator in "users/{email}" format. Supports "==" and "!=". For example: creator == "users/alice@example.com" |
|
| page_size | int32 | The maximum number of saved queries to return. The service may return fewer. Defaults to 10; values above 1000 are coerced to 1000. |
|
| page_token | string | A page token from a previous ListSavedQueries call. Keep every other parameter the same as the call that returned it. |
|
| order_by | string | Sort the results, per https://google.aip.dev/132#ordering. Supported fields: `update_time`, `create_time`, `title`; append " desc" for descending, e.g. "update_time desc" for most recently modified first. A modification is a title, content, database, or folder write; sharing and stars do not count, and a never-modified saved query counts its create time. Empty means `title` ascending. `resource_id` is always appended as a final tiebreak so pages stay stable. |
| Field | Type | Label | Description |
| saved_queries | SavedQuery | repeated |
|
| next_page_token | string | Pass to the next ListSavedQueries call to fetch the following page. Empty on the last page. |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
|
| source_folder | string | The folder to move, descendants included, e.g. "a/b". |
|
| target_folder | string | Where it lands. A path like "a/b/c"; empty drops the `source_folder` prefix, promoting the folder's contents toward the root. |
| Field | Type | Label | Description |
| moved_count | int32 | How many moved. |
| Field | Type | Label | Description |
| name | string | Server-generated. Format: projects/{project}/savedQueries/{savedQuery} |
|
| project | string | Format: projects/{project} |
|
| database | string | The connected database, which must belong to the saved query's own project. Empty when none is connected, or when the database no longer exists. Format: instances/{instance}/databases/{database} or projects/{project}/instances/{instance}/databases/{database} |
|
| title | string | The title of the saved query. |
|
| creator | string | The owner. Ownership does not transfer. Format: users/{email} |
|
| create_time | google.protobuf.Timestamp |
|
|
| update_time | google.protobuf.Timestamp |
|
|
| content | bytes | The SQL text. SearchSavedQueries returns a truncated preview; GetSavedQuery returns the full text. |
|
| content_size | int64 | The full size of the content, which may exceed the `content` returned. |
|
| starred | bool | Whether the calling user starred it. |
|
| folder | string | The folder holding this saved query. A path like "a/b/c"; empty means unfiled. |
Binds members to one access level on one saved query.
| Field | Type | Label | Description |
| level | SavedQueryBinding.Level |
|
|
| members | string | repeated | The members granted `level`: "user:{email}" or "group:{email}" only. Service accounts cannot be grantees — they reach their own saved queries as the creator. Naming one under "user:" grants nothing rather than failing. Groups are stored as references, so membership stays live. |
Who a saved query is shared with, and at what level. No bindings means
private. The creator is never a binding member; ownership cannot be granted.
| Field | Type | Label | Description |
| bindings | SavedQueryBinding | repeated | At most one binding per level. A member listed under two levels is rejected rather than resolved to the higher one. |
| etag | string | The etag of the policy as read. SetSavedQueryPolicy requires it and fails with ABORTED when it no longer matches. |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
|
| filter | string | Filter the result, in CEL. See https://github.com/google/cel-spec Supported fields: - name: the saved query name. Supports "==" and "in [...]". - title: the title. Supports "contains". - creator: the creator in "users/{email}" format. Supports "==" and "!=". - shared: whether a binding shares the saved query with the caller. Their own saved queries, and ones visible only through a project-level bb.savedQueries.get, are not "shared". Supports "==". - starred: whether the caller starred it. Supports "==". - folder: the exact folder path. Supports "==". Use `creator == "users/{me}"` for a My view and `shared == true` for a Shared view. Prefer `shared` over `creator !=`: with a project-level bb.savedQueries.get, `creator !=` also matches saved queries nobody shared with the caller. For example: creator == "users/alice@example.com" shared == true starred == true title.contains("weekly report") folder == "foo/bar" |
|
| page_size | int32 | The maximum number of saved queries to return. The service may return fewer. Defaults to 10; values above 1000 are coerced to 1000. |
|
| page_token | string | A page token from a previous SearchSavedQueries call. Keep every other parameter the same as the call that returned it. |
| Field | Type | Label | Description |
| saved_queries | SavedQuery | repeated |
|
| next_page_token | string | Pass to the next SearchSavedQueries call to fetch the following page. Empty on the last page. |
| Field | Type | Label | Description |
| parent | string | Format: projects/{project} |
|
| filter | string | Filter folders by the saved queries they hold. Takes the same fields and syntax as SearchSavedQueries.filter, except `title`. A folder is returned when at least one saved query the caller can read matches. |
| Field | Type | Label | Description |
| folders | string | repeated | Folder paths, every ancestor prefix included, sorted. A folder is a path on saved queries ("a/b/c"), so empty folders cannot exist. |
| Field | Type | Label | Description |
| resource | string | Format: projects/{project}/savedQueries/{savedQuery} |
|
| policy | SavedQueryPolicy | The new policy, replacing the stored one in full. Empty `bindings` makes the saved query private again. |
| Field | Type | Label | Description |
| saved_query | SavedQuery | `saved_query.name` identifies the saved query to update. Format: projects/{project}/savedQueries/{savedQuery} |
|
| update_mask | google.protobuf.FieldMask | Fields to update, relative to the saved query (`title`, not `saved_query.title`). Supported: `title`, `content`, `database`, `folder`. At least one path is required. |
| Field | Type | Label | Description |
| name | string | Format: projects/{project}/savedQueries/{savedQuery} |
|
| starred | bool | Whether the caller stars the saved query. |
Nested to avoid colliding with the package-scoped EDITOR in
DatabaseChangeMode.
| Name | Number | Description |
| LEVEL_UNSPECIFIED | 0 | |
| VIEWER | 1 | Holds bb.savedQueries.get and bb.savedQueries.getIamPolicy on the saved query: open and read it, and see who it is shared with. |
| EDITOR | 2 | VIEWER, plus bb.savedQueries.update: write the title, content, database, and folder. Not deletion, not setIamPolicy. |
SavedQueryService manages saved queries in the SQL Editor.
A saved query is private to its creator until shared. Permissions come from
three places:
- The creator owns the saved query and holds every permission on it.
- A VIEWER binding grants bb.savedQueries.get and getIamPolicy; an EDITOR
binding adds update.
- Permissions granted on the project or workspace apply to every saved
query in the project, private ones included.
A caller without a method's permission gets NotFound, not
PermissionDenied, so private names stay unprobeable. Running a saved query
is governed by the SQL Editor's database permissions, not by this service.
| Method Name | Request Type | Response Type | Description |
| CreateSavedQuery | CreateSavedQueryRequest | SavedQuery | Create a saved query. The creator becomes the owner and the saved query starts private. Permissions required: bb.savedQueries.create on the project |
| GetSavedQuery | GetSavedQueryRequest | SavedQuery | Get a saved query with its full content. Permissions required: bb.savedQueries.get (creator, VIEWER/EDITOR binding, or project-level grant) |
| ListSavedQueries | ListSavedQueriesRequest | ListSavedQueriesResponse | List saved queries for auditing. The permission alone grants reading every matched saved query with full content, private ones included; bindings are ignored. Use parent "projects/-" for all projects. Results default to title ascending; see `order_by`. Permissions required: bb.savedQueries.list on the project, or on the workspace when the parent is "projects/-" |
| SearchSavedQueries | SearchSavedQueriesRequest | SearchSavedQueriesResponse | Search saved queries in one project. Returns content previews of the saved queries the caller can read, the same access rule as GetSavedQuery. Permissions required: bb.savedQueries.search on the project |
| SearchSavedQueryFolders | SearchSavedQueryFoldersRequest | SearchSavedQueryFoldersResponse | Search folder paths. A path is returned when it holds at least one saved query the caller can read, the same access rule as SearchSavedQueries. Permissions required: bb.savedQueries.search on the project |
| UpdateSavedQuery | UpdateSavedQueryRequest | SavedQuery | Update a saved query. `database` must belong to the saved query's project. Permissions required: bb.savedQueries.update (creator, EDITOR binding, or project-level grant) |
| UpdateSavedQueryStar | UpdateSavedQueryStarRequest | SavedQuery | Star or unstar a saved query for the caller. Stars are personal: nobody else sees them and they grant nothing. The caller can star any saved query they can read. When access is lost the star is hidden, not deleted; it comes back if access returns. Permissions required: bb.savedQueries.get (creator, VIEWER/EDITOR binding, or project-level grant) |
| MoveMySavedQueries | MoveMySavedQueriesRequest | MoveMySavedQueriesResponse | Move the caller's saved queries filed under `source_folder`, descendants included, into `target_folder`: renaming "a/b" to "a/c" also moves "a/b/deep". Only the caller's own saved queries move; the response counts how many did. Re-filing a single saved query is UpdateSavedQuery's `folder` field. Permissions required: creator |
| DeleteSavedQuery | DeleteSavedQueryRequest | .google.protobuf.Empty | Delete a saved query and every user's stars on it. An EDITOR binding cannot delete. Permissions required: bb.savedQueries.delete (creator or project-level grant) |
| GetSavedQueryPolicy | GetSavedQueryPolicyRequest | SavedQueryPolicy | Get a saved query's sharing policy: who it is shared with, at what level. Permissions required: bb.savedQueries.getIamPolicy (creator, VIEWER/EDITOR binding, or project-level grant) |
| SetSavedQueryPolicy | SetSavedQueryPolicyRequest | SavedQueryPolicy | Replace a saved query's sharing policy in full. `policy.etag` must match the stored policy; a mismatch fails with ABORTED. Permissions required: bb.savedQueries.setIamPolicy (creator or project-level grant; no predefined role carries it) |
| Method Name | Method | Pattern | Body |
| CreateSavedQuery | POST | /v1/{parent=projects/*}/savedQueries | saved_query |
| GetSavedQuery | GET | /v1/{name=projects/*/savedQueries/*} | |
| ListSavedQueries | GET | /v1/{parent=projects/*}/savedQueries | |
| SearchSavedQueries | POST | /v1/{parent=projects/*}/savedQueries:search | * |
| SearchSavedQueryFolders | POST | /v1/{parent=projects/*}/savedQueries:searchFolders | * |
| UpdateSavedQuery | PATCH | /v1/{saved_query.name=projects/*/savedQueries/*} | saved_query |
| UpdateSavedQueryStar | POST | /v1/{name=projects/*/savedQueries/*}:updateStar | * |
| MoveMySavedQueries | POST | /v1/{parent=projects/*}/savedQueries:moveMy | * |
| DeleteSavedQuery | DELETE | /v1/{name=projects/*/savedQueries/*} | |
| GetSavedQueryPolicy | GET | /v1/{resource=projects/*/savedQueries/*}:getPolicy | |
| SetSavedQueryPolicy | POST | /v1/{resource=projects/*/savedQueries/*}:setPolicy | * |
Request message for creating a service account.
| Field | Type | Label | Description |
| parent | string | The parent resource where this service account will be created. Format: projects/{project} for project-level, workspaces/{id} for workspace-level. |
|
| service_account_id | string | The ID to use for the service account, which will become the final component of the service account's email in the format: {service_account_id}@service.bytebase.com or {service_account_id}@{project-id}.service.bytebase.com |
|
| service_account | ServiceAccount | The service account to create. |
Request message for deleting a service account.
| Field | Type | Label | Description |
| name | string | The name of the service account to delete. Format: serviceAccounts/{email} |
Request message for getting a service account.
| Field | Type | Label | Description |
| name | string | The name of the service account to retrieve. Format: serviceAccounts/{email} |
Request message for listing service accounts.
| Field | Type | Label | Description |
| parent | string | The parent resource. Format: projects/{project} for project-level, workspaces/{id} for workspace-level. |
|
| page_size | int32 | The maximum number of service accounts to return. The service may return fewer than this value. If unspecified, at most 10 service accounts will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListServiceAccounts` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListServiceAccounts` must match the call that provided the page token. |
|
| show_deleted | bool | Show deleted service accounts if specified. |
|
| filter | string | Filter is used to filter service accounts returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - name: the service account name, support "==" and ".contains()" operator. - email: the service account email, support "==" and ".contains()" operator. - state: check State enum for values, support "==" operator. For example: name == "ed" name.contains("ed") state == "DELETED" email == "ed@service.bytebase.com" email.contains("ed") |
Response message for listing service accounts.
| Field | Type | Label | Description |
| service_accounts | ServiceAccount | repeated | The service accounts from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
ServiceAccount represents an API integration account.
| Field | Type | Label | Description |
| name | string | The name of the service account. Format: serviceAccounts/{email} |
|
| state | State | The state of the service account. |
|
| string | The email of the service account. For workspace-level: {name}@service.bytebase.com For project-level: {name}@{project-id}.service.bytebase.com |
||
| title | string | The display title of the service account. |
|
| service_key | string | The service key for authentication. Only returned on creation or key rotation. |
|
| create_time | google.protobuf.Timestamp | The timestamp when the service account was created. |
Request message for restoring a deleted service account.
| Field | Type | Label | Description |
| name | string | The name of the deleted service account. Format: serviceAccounts/{email} |
Request message for updating a service account.
| Field | Type | Label | Description |
| service_account | ServiceAccount | The service account to update. The service account's `name` field is used to identify the service account to update. Format: serviceAccounts/{email} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. Supported fields: title, service_key (triggers key rotation) |
ServiceAccountService manages service accounts for API integrations.
| Method Name | Request Type | Response Type | Description |
| CreateServiceAccount | CreateServiceAccountRequest | ServiceAccount | Creates a new service account. For workspace-level: parent is workspaces/{id}, permission bb.serviceAccounts.create on workspace. For project-level: parent is projects/{project}, permission bb.serviceAccounts.create on project. |
| GetServiceAccount | GetServiceAccountRequest | ServiceAccount | Gets a service account by name. Permissions required: bb.serviceAccounts.get |
| ListServiceAccounts | ListServiceAccountsRequest | ListServiceAccountsResponse | Lists service accounts. For workspace-level: parent is workspaces/{id}, permission bb.serviceAccounts.list on workspace. For project-level: parent is projects/{project}, permission bb.serviceAccounts.list on project. |
| UpdateServiceAccount | UpdateServiceAccountRequest | ServiceAccount | Updates a service account. Permissions required: bb.serviceAccounts.update |
| DeleteServiceAccount | DeleteServiceAccountRequest | .google.protobuf.Empty | Deletes a service account. Permissions required: bb.serviceAccounts.delete |
| UndeleteServiceAccount | UndeleteServiceAccountRequest | ServiceAccount | Restores a deleted service account. Permissions required: bb.serviceAccounts.undelete |
| Method Name | Method | Pattern | Body |
| CreateServiceAccount | POST | /v1/{parent=projects/*}/serviceAccounts | service_account |
| CreateServiceAccount | POST | /v1/{parent=workspaces/*}/serviceAccounts | service_account |
| GetServiceAccount | GET | /v1/{name=serviceAccounts/*} | |
| ListServiceAccounts | GET | /v1/{parent=projects/*}/serviceAccounts | |
| ListServiceAccounts | GET | /v1/{parent=workspaces/*}/serviceAccounts | |
| UpdateServiceAccount | PATCH | /v1/{service_account.name=serviceAccounts/*} | service_account |
| DeleteServiceAccount | DELETE | /v1/{name=serviceAccounts/*} | |
| UndeleteServiceAccount | POST | /v1/{name=serviceAccounts/*}:undelete | * |
| Field | Type | Label | Description |
| parent | string | The parent resource where all sheets will be created. Format: projects/{project} |
|
| requests | CreateSheetRequest | repeated |
|
| Field | Type | Label | Description |
| sheets | Sheet | repeated |
|
| Field | Type | Label | Description |
| parent | string | The parent resource where this sheet will be created. Format: projects/{project} |
|
| sheet | Sheet | The sheet to create. |
| Field | Type | Label | Description |
| name | string | The name of the sheet to retrieve. Format: projects/{project}/sheets/{sheet} |
|
| raw | bool | By default, the content of the sheet is cut off, set the `raw` to true to retrieve the full content. |
| Field | Type | Label | Description |
| name | string | The name of the sheet resource. Format: projects/{project}/sheets/{sheet} The sheet ID is generated by the server on creation and cannot be changed. |
|
| content | bytes | The content of the sheet. By default, it will be cut off, if it doesn't match the `content_size`, you can set the `raw` to true in GetSheet request to retrieve the full content. |
|
| content_size | int64 | content_size is the full size of the content, may not match the size of the `content` field. |
SheetService manages SQL scripts and saved queries.
| Method Name | Request Type | Response Type | Description |
| CreateSheet | CreateSheetRequest | Sheet | Creates a new SQL sheet. Permissions required: bb.sheets.create |
| BatchCreateSheets | BatchCreateSheetsRequest | BatchCreateSheetsResponse | Creates multiple SQL sheets in a single operation. Permissions required: bb.sheets.create |
| GetSheet | GetSheetRequest | Sheet | Retrieves a SQL sheet by name. Permissions required: bb.sheets.get |
| Method Name | Method | Pattern | Body |
| CreateSheet | POST | /v1/{parent=projects/*}/sheets | sheet |
| BatchCreateSheets | POST | /v1/{parent=projects/*}/sheets:batchCreate | * |
| GetSheet | GET | /v1/{name=projects/*/sheets/*} |
| Field | Type | Label | Description |
| feedback | string | Reason the customer is canceling. Maps to Stripe's cancellation_details.feedback. Valid Stripe values: "customer_service", "low_quality", "missing_features", "switched_service", "too_complex", "too_expensive", "unused", "other". Required. |
|
| comment | string | Optional free-form comment. Max 500 chars (Stripe limit). |
| Field | Type | Label | Description |
| plan | PlanType |
|
|
| interval | BillingInterval |
|
|
| seats | int32 |
|
| Field | Type | Label | Description |
| content | bytes |
|
| Field | Type | Label | Description |
| plans | PurchasePlan | repeated |
|
| Field | Type | Label | Description |
| total_price | string | Total amount paid for the current billing period, in the smallest currency unit (e.g. cents). |
|
| currency | string |
|
|
| period_start | string |
|
|
| period_end | string |
|
|
| invoice_url | string | Stripe Billing Portal URL for invoice management. |
|
| cancel_at_period_end | bool | Whether the subscription is scheduled to cancel at the end of the current billing period. |
|
| next_period_price | string | Amount that will be charged at the next renewal, in the smallest currency unit (e.g. cents). Empty when the subscription will not renew (e.g. scheduled to cancel at period end). |
PlanConfig represents the configuration for all plans loaded from plan.yaml
| Field | Type | Label | Description |
| plans | PlanLimitConfig | repeated |
|
| instance_features | PlanFeature | repeated |
|
PlanLimitConfig represents a single plan's configuration
| Field | Type | Label | Description |
| type | PlanType |
|
|
| maximum_instance_count | int32 |
|
|
| maximum_seat_count | int32 |
|
|
| features | PlanFeature | repeated |
|
| Field | Type | Label | Description |
| interval | BillingInterval |
|
|
| discount | PurchaseDiscount |
|
| Field | Type | Label | Description |
| type | PurchaseDiscount.Type |
|
|
| value | int32 |
|
| Field | Type | Label | Description |
| type | PlanType |
|
|
| self_service_purchase | bool |
|
|
| additionals | PurchasePlanAdditional | repeated |
|
| billing_methods | PurchaseBillingMethod | repeated |
|
| Field | Type | Label | Description |
| type | PurchasePlanAdditional.Type |
|
|
| unit_price | int32 | Price in USD cents per month. |
|
| free_count | int32 |
|
|
| minimum_count | int32 |
|
|
| maximum_count | int32 | -1 means unlimited. |
| Field | Type | Label | Description |
| payment_url | string | If set, redirect to this Stripe Checkout URL. If empty, the update was applied directly using the existing payment method. |
|
| session_id | string | Stripe Checkout Session ID. Used to verify the session after redirect. |
| Field | Type | Label | Description |
| plan | PlanType |
|
|
| seats | int32 |
|
|
| instances | int32 |
|
|
| active_instances | int32 |
|
|
| expires_time | google.protobuf.Timestamp |
|
|
| trialing | bool |
|
|
| org_name | string |
|
|
| ha | bool | Whether high availability (multiple replicas) is enabled. |
|
| etag | string | Etag for optimistic concurrency on purchase updates. Only set in SaaS mode. |
| Field | Type | Label | Description |
| plan | PlanType |
|
|
| interval | BillingInterval |
|
|
| seats | int32 |
|
|
| etag | string |
|
| Field | Type | Label | Description |
| license | string |
|
| Field | Type | Label | Description |
| session_id | string | The same Stripe Checkout Session ID PurchaseResponse mints, arriving back the other way, so it carries the same classification. VerifyCheckoutSession is EXCLUDED, and a refusal of it streams its request to the stdout audit log, so leaving this unannotated would write the id into that line while the response that produced it was redacted. |
| Field | Type | Label | Description |
| status | string | Stripe Checkout Session status: "complete", "expired", or "open". |
| Name | Number | Description |
| BILLING_INTERVAL_UNSPECIFIED | 0 | |
| MONTH | 1 | |
| YEAR | 2 |
PlanFeature represents the available features in Bytebase
| Name | Number | Description |
| FEATURE_UNSPECIFIED | 0 | |
| FEATURE_DATABASE_CHANGE | 1 | Database Change Management |
| FEATURE_GIT_BASED_SCHEMA_VERSION_CONTROL | 2 | |
| FEATURE_DECLARATIVE_SCHEMA_MIGRATION | 3 | |
| FEATURE_COMPARE_AND_SYNC_SCHEMA | 4 | |
| FEATURE_ONLINE_SCHEMA_CHANGE | 5 | |
| FEATURE_PRE_DEPLOYMENT_SQL_REVIEW | 6 | |
| FEATURE_AUTOMATIC_BACKUP_BEFORE_DATA_CHANGES | 7 | |
| FEATURE_ONE_CLICK_DATA_ROLLBACK | 8 | |
| FEATURE_MULTI_DATABASE_BATCH_CHANGES | 9 | |
| FEATURE_PROGRESSIVE_ENVIRONMENT_DEPLOYMENT | 10 | |
| FEATURE_SCHEDULED_ROLLOUT_TIME | 11 | |
| FEATURE_DATABASE_CHANGELOG | 12 | |
| FEATURE_SCHEMA_DRIFT_DETECTION | 13 | |
| FEATURE_ROLLOUT_POLICY | 14 | |
| FEATURE_WEB_BASED_SQL_EDITOR | 15 | SQL Editor & Development |
| FEATURE_SQL_EDITOR_ADMIN_MODE | 16 | |
| FEATURE_NATURAL_LANGUAGE_TO_SQL | 17 | |
| FEATURE_AI_QUERY_EXPLANATION | 18 | |
| FEATURE_AI_QUERY_SUGGESTIONS | 19 | |
| FEATURE_AUTO_COMPLETE | 20 | |
| FEATURE_SCHEMA_DIAGRAM | 21 | |
| FEATURE_SCHEMA_EDITOR | 22 | |
| FEATURE_DATA_EXPORT | 23 | |
| FEATURE_DATA_OFFLINE_EXPORT | 24 | |
| FEATURE_QUERY_HISTORY | 25 | |
| FEATURE_SAVED_AND_SHARED_SQL_SCRIPTS | 26 | |
| FEATURE_BATCH_QUERY | 27 | |
| FEATURE_INSTANCE_READ_ONLY_CONNECTION | 28 | |
| FEATURE_QUERY_POLICY | 29 | |
| FEATURE_RESTRICT_COPYING_DATA | 30 | |
| FEATURE_IAM | 31 | Security & Compliance |
| FEATURE_INSTANCE_SSL_CONNECTION | 32 | |
| FEATURE_INSTANCE_CONNECTION_OVER_SSH_TUNNEL | 33 | |
| FEATURE_INSTANCE_CONNECTION_IAM_AUTHENTICATION | 34 | |
| FEATURE_GOOGLE_AND_GITHUB_SSO | 35 | |
| FEATURE_USER_GROUPS | 36 | |
| FEATURE_DISALLOW_SELF_SERVICE_SIGNUP | 37 | |
| FEATURE_CUSTOM_INSTANCE_SYNC_TIME | 38 | |
| FEATURE_CUSTOM_INSTANCE_CONNECTION_LIMIT | 39 | |
| FEATURE_RISK_ASSESSMENT | 40 | |
| FEATURE_APPROVAL_WORKFLOW | 41 | |
| FEATURE_AUDIT_LOG | 42 | |
| FEATURE_ENTERPRISE_SSO | 43 | |
| FEATURE_TWO_FA | 44 | |
| FEATURE_PASSWORD_RESTRICTIONS | 45 | |
| FEATURE_DISALLOW_PASSWORD_SIGNIN | 46 | |
| FEATURE_CUSTOM_ROLES | 47 | |
| FEATURE_REQUEST_ROLE_WORKFLOW | 48 | |
| FEATURE_JIT | 49 | |
| FEATURE_DATA_MASKING | 50 | |
| FEATURE_DATA_CLASSIFICATION | 51 | |
| FEATURE_SCIM | 52 | |
| FEATURE_DIRECTORY_SYNC | 53 | |
| FEATURE_TOKEN_DURATION_CONTROL | 54 | |
| FEATURE_EXTERNAL_SECRET_MANAGER | 55 | |
| FEATURE_USER_EMAIL_DOMAIN_RESTRICTION | 56 | |
| FEATURE_PROJECT_MANAGEMENT | 57 | Administration & Support |
| FEATURE_ENVIRONMENT_MANAGEMENT | 58 | |
| FEATURE_IM_NOTIFICATIONS | 59 | |
| FEATURE_TERRAFORM_PROVIDER | 60 | |
| FEATURE_DATABASE_GROUPS | 61 | |
| FEATURE_ENVIRONMENT_TIERS | 62 | |
| FEATURE_DASHBOARD_ANNOUNCEMENT | 63 | |
| FEATURE_API_INTEGRATION_GUIDANCE | 64 | |
| FEATURE_CUSTOM_LOGO | 65 | |
| FEATURE_WATERMARK | 66 | |
| FEATURE_ROADMAP_PRIORITIZATION | 67 | |
| FEATURE_CUSTOM_MSA | 68 | |
| FEATURE_COMMUNITY_SUPPORT | 69 | |
| FEATURE_EMAIL_SUPPORT | 70 | |
| FEATURE_DEDICATED_SUPPORT_WITH_SLA | 71 | |
| FEATURE_SHAREPOINT_EXPORT | 72 | Upload exports to SharePoint. |
| Name | Number | Description |
| PLAN_TYPE_UNSPECIFIED | 0 | Unspecified plan type. |
| FREE | 1 | Free plan with basic features and no cost. |
| TEAM | 2 | Team plan with collaboration features for small to medium teams. |
| ENTERPRISE | 3 | Enterprise plan with advanced features and dedicated support. |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| PERCENTAGE_OFF | 1 | |
| FIXED_MONTH_OFF | 2 | |
| FIXED_PRICE_OFF | 3 |
| Name | Number | Description |
| TYPE_UNSPECIFIED | 0 | |
| USER | 1 |
SubscriptionService manages enterprise subscriptions and licensing.
| Method Name | Request Type | Response Type | Description |
| GetSubscription | GetSubscriptionRequest | Subscription | GetSubscription returns the current subscription. If there is no license, we will return a free plan subscription without expiration time. If there is expired license, we will return a free plan subscription with the expiration time of the expired license. |
| ExportVCSProviderUsers | ExportVCSProviderUsersRequest | ExportVCSProviderUsersResponse | Exports active VCS users as CSV. |
| UploadLicense | UploadLicenseRequest | Subscription | Uploads an enterprise license (self-hosted only). |
| StartTrial | StartTrialRequest | Subscription | StartTrial starts a free trial for an eligible SaaS workspace. |
| CreatePurchase | CreatePurchaseRequest | PurchaseResponse | CreatePurchase creates a new subscription purchase (SaaS only). Returns a Stripe Checkout URL for the user to complete payment. |
| UpdatePurchase | UpdatePurchaseRequest | PurchaseResponse | UpdatePurchase updates an existing subscription (SaaS only). May return a Stripe Checkout URL if payment method change is needed. |
| CancelPurchase | CancelPurchaseRequest | PurchaseResponse | CancelPurchase cancels an active subscription (SaaS only). |
| GetPaymentInfo | GetPaymentInfoRequest | PaymentInfo | GetPaymentInfo returns payment details for the current subscription (SaaS only). |
| VerifyCheckoutSession | VerifyCheckoutSessionRequest | VerifyCheckoutSessionResponse | VerifyCheckoutSession verifies a Stripe Checkout Session status (SaaS only). |
| ListPurchasePlans | ListPurchasePlansRequest | ListPurchasePlansResponse | ListPurchasePlans returns available plans for self-service purchase. |
| Method Name | Method | Pattern | Body |
| GetSubscription | GET | /v1/subscription | |
| ExportVCSProviderUsers | GET | /v1/subscription:vcsProviderUsersExport | |
| UploadLicense | PATCH | /v1/subscription/license | * |
| StartTrial | POST | /v1/subscription:startTrial | * |
| CreatePurchase | POST | /v1/subscription:purchase | * |
| UpdatePurchase | POST | /v1/subscription:updatePurchase | * |
| CancelPurchase | POST | /v1/subscription:cancelPurchase | * |
| GetPaymentInfo | GET | /v1/subscription/paymentInfo | |
| VerifyCheckoutSession | GET | /v1/subscription/checkoutSession/{session_id} | |
| ListPurchasePlans | GET | /v1/subscription/plans |
Request message for creating a workload identity.
| Field | Type | Label | Description |
| parent | string | The parent resource where this workload identity will be created. Format: projects/{project} for project-level, workspaces/{id} for workspace-level. |
|
| workload_identity_id | string | The ID to use for the workload identity, which will become the final component of the workload identity's email in the format: {workload_identity_id}@workload.bytebase.com or {workload_identity_id}@{project-id}.workload.bytebase.com |
|
| workload_identity | WorkloadIdentity | The workload identity to create. |
Request message for deleting a workload identity.
| Field | Type | Label | Description |
| name | string | The name of the workload identity to delete. Format: workloadIdentities/{email} |
Request message for getting a workload identity.
| Field | Type | Label | Description |
| name | string | The name of the workload identity to retrieve. Format: workloadIdentities/{email} |
Request message for listing workload identities.
| Field | Type | Label | Description |
| parent | string | The parent resource. Format: projects/{project} for project-level, workspaces/{id} for workspace-level. |
|
| page_size | int32 | The maximum number of workload identities to return. The service may return fewer than this value. If unspecified, at most 10 workload identities will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
|
| page_token | string | A page token, received from a previous `ListWorkloadIdentities` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListWorkloadIdentities` must match the call that provided the page token. |
|
| show_deleted | bool | Show deleted workload identities if specified. |
|
| filter | string | Filter is used to filter workload identities returned in the list. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec Supported filter: - name: the workload identity name, support "==" and ".contains()" operator. - email: the workload identity email, support "==" and ".contains()" operator. - state: check State enum for values, support "==" operator. For example: name == "ed" name.contains("ed") state == "DELETED" email == "ed@workload.bytebase.com" email.contains("ed") |
Response message for listing workload identities.
| Field | Type | Label | Description |
| workload_identities | WorkloadIdentity | repeated | The workload identities from the specified request. |
| next_page_token | string | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
Request message for restoring a deleted workload identity.
| Field | Type | Label | Description |
| name | string | The name of the deleted workload identity. Format: workloadIdentities/{email} |
Request message for updating a workload identity.
| Field | Type | Label | Description |
| workload_identity | WorkloadIdentity | The workload identity to update. The workload identity's `name` field is used to identify the workload identity to update. Format: workloadIdentities/{email} |
|
| update_mask | google.protobuf.FieldMask | The list of fields to update. Supported fields: title, workload_identity_config |
WorkloadIdentity represents an external CI/CD workload identity.
| Field | Type | Label | Description |
| name | string | The name of the workload identity. Format: workloadIdentities/{email} |
|
| state | State | The state of the workload identity. |
|
| string | The email of the workload identity. For workspace-level: {name}@workload.bytebase.com For project-level: {name}@{project-id}.workload.bytebase.com |
||
| title | string | The display title of the workload identity. |
|
| create_time | google.protobuf.Timestamp | The timestamp when the workload identity was created. |
|
| workload_identity_config | WorkloadIdentityConfig | The workload identity configuration for OIDC token validation. |
WorkloadIdentityConfig for API layer
| Field | Type | Label | Description |
| provider_type | WorkloadIdentityConfig.ProviderType | Provider configuration mode. |
|
| issuer_url | string | HTTPS URL of the OIDC issuer. The exchange fetches {issuer_url}/.well-known/openid-configuration to verify a token, unless jwks_url names the key set directly. |
|
| allowed_audiences | string | repeated | Audiences a token may be minted for. A token authenticates if its `aud` claim matches any entry. |
| subject_pattern | string | The subject a token must carry, e.g. "repo:owner/repo:ref:refs/heads/main". A trailing "*" is a prefix match. For GitHub and GitLab subjects it must complete an owner or group segment, so "repo:my-org/*" is accepted and "repo:*" is not. Other issuers write other vocabularies, so a wildcard outside those two is accepted as given. |
|
| jwks_url | string | Optional JWKS endpoint. When empty, use OIDC discovery from issuer_url. |
ProviderType identifies the workload identity configuration mode.
| Name | Number | Description |
| PROVIDER_TYPE_UNSPECIFIED | 0 | |
| GITHUB | 1 | |
| GITLAB | 2 | |
| OIDC | 3 |
WorkloadIdentityService manages workload identities for external CI/CD integrations.
| Method Name | Request Type | Response Type | Description |
| CreateWorkloadIdentity | CreateWorkloadIdentityRequest | WorkloadIdentity | Creates a new workload identity. For workspace-level: parent is workspaces/{id}, permission bb.workloadIdentities.create on workspace. For project-level: parent is projects/{project}, permission bb.workloadIdentities.create on project. |
| GetWorkloadIdentity | GetWorkloadIdentityRequest | WorkloadIdentity | Gets a workload identity by name. Permissions required: bb.workloadIdentities.get |
| ListWorkloadIdentities | ListWorkloadIdentitiesRequest | ListWorkloadIdentitiesResponse | Lists workload identities. For workspace-level: parent is workspaces/{id}, permission bb.workloadIdentities.list on workspace. For project-level: parent is projects/{project}, permission bb.workloadIdentities.list on project. |
| UpdateWorkloadIdentity | UpdateWorkloadIdentityRequest | WorkloadIdentity | Updates a workload identity. Permissions required: bb.workloadIdentities.update |
| DeleteWorkloadIdentity | DeleteWorkloadIdentityRequest | .google.protobuf.Empty | Deletes a workload identity. Permissions required: bb.workloadIdentities.delete |
| UndeleteWorkloadIdentity | UndeleteWorkloadIdentityRequest | WorkloadIdentity | Restores a deleted workload identity. Permissions required: bb.workloadIdentities.undelete |
| Method Name | Method | Pattern | Body |
| CreateWorkloadIdentity | POST | /v1/{parent=projects/*}/workloadIdentities | workload_identity |
| CreateWorkloadIdentity | POST | /v1/{parent=workspaces/*}/workloadIdentities | workload_identity |
| GetWorkloadIdentity | GET | /v1/{name=workloadIdentities/*} | |
| ListWorkloadIdentities | GET | /v1/{parent=projects/*}/workloadIdentities | |
| ListWorkloadIdentities | GET | /v1/{parent=workspaces/*}/workloadIdentities | |
| UpdateWorkloadIdentity | PATCH | /v1/{workload_identity.name=workloadIdentities/*} | workload_identity |
| DeleteWorkloadIdentity | DELETE | /v1/{name=workloadIdentities/*} | |
| UndeleteWorkloadIdentity | POST | /v1/{name=workloadIdentities/*}:undelete | * |
| Field | Type | Label | Description |
| name | string | Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| name | string | The workspace name, format: workspaces/{workspace}. Use "workspaces/-" to get the current/default workspace. |
| Field | Type | Label | Description |
| name | string | Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| workspaces | Workspace | repeated |
|
| Field | Type | Label | Description |
| name | string | The workspace whose directory sync token is rotated. Format: workspaces/{workspace} |
| Field | Type | Label | Description |
| token | string | The new token, in plaintext. This is the only time it is ever returned. |
| Field | Type | Label | Description |
| workspace | Workspace |
|
|
| update_mask | google.protobuf.FieldMask |
|
| Field | Type | Label | Description |
| name | string | Format: workspaces/{workspace} |
|
| title | string |
|
|
| logo | string | The branding logo. |
WorkspaceService manages workspace-level operations and profile.
| Method Name | Request Type | Response Type | Description |
| GetWorkspace | GetWorkspaceRequest | Workspace | Gets a workspace by name. Supports "workspaces/-" to resolve the current workspace: - Authenticated: uses the workspace from JWT context - Self-hosted unauthenticated: returns the single workspace - SaaS unauthenticated: returns minimal response |
| ListWorkspaces | ListWorkspacesRequest | ListWorkspacesResponse | Lists all workspaces the current user is a member of. |
| UpdateWorkspace | UpdateWorkspaceRequest | Workspace | Updates a workspace. Currently only title can be updated. |
| GetIamPolicy | GetIamPolicyRequest | IamPolicy | Retrieves IAM policy for the workspace. Permissions required: bb.workspaces.getIamPolicy |
| DeleteWorkspace | DeleteWorkspaceRequest | LoginResponse | Deletes a workspace. SaaS only. Cancels any active subscription and soft-deletes the workspace so all associated data becomes inaccessible. Requires workspace admin permission. |
| LeaveWorkspace | LeaveWorkspaceRequest | LoginResponse | Removes the calling user from a workspace and switches to the next available workspace. Available to any workspace member. Fails if the caller is the last workspace admin. |
| SetIamPolicy | SetIamPolicyRequest | IamPolicy | Sets IAM policy for the workspace. Permissions required: bb.workspaces.setIamPolicy |
| RotateDirectorySyncToken | RotateDirectorySyncTokenRequest | RotateDirectorySyncTokenResponse | Mints a new directory sync (SCIM) token, immediately invalidating the previous one. The plaintext token is returned exactly once and cannot be retrieved afterwards; only its hash is stored. Callers that lose it must rotate again and update their identity provider. Permissions required: bb.workspaces.rotateDirectorySyncToken |
| Method Name | Method | Pattern | Body |
| GetWorkspace | GET | /v1/{name=workspaces/*} | |
| ListWorkspaces | GET | /v1/workspaces | |
| UpdateWorkspace | PATCH | /v1/{workspace.name=workspaces/*} | * |
| GetIamPolicy | GET | /v1/{resource=workspaces/*}:getIamPolicy | |
| DeleteWorkspace | DELETE | /v1/{name=workspaces/*} | |
| LeaveWorkspace | POST | /v1/{name=workspaces/*}:leave | * |
| SetIamPolicy | POST | /v1/{resource=workspaces/*}:setIamPolicy | * |
| RotateDirectorySyncToken | POST | /v1/{name=workspaces/*}:rotateDirectorySyncToken | * |
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
| double | double | double | float | float64 | double | float | Float | |
| float | float | float | float | float32 | float | float | Float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |