Protocol Documentation

The issue associated with the access grant.

The target databases for this access grant. Format: instances/{instance}/databases/{database}

The query permission granted.

Whether the grant allows unmasking sensitive data.

The requested duration for the access grant. Stored when the user provides a TTL instead of an absolute expire_time. The server computes expire_time from this value at activation time.

Whether export the query result.

The default schema to execute the query.

The container name to execute the query against, used for CosmosDB only.

Lowercase hex SHA-256 of query after trimming boundary space, tab, LF, CR, vertical tab, and form feed. Derived by the store for grant matching.

Maximum number of items to return.

Number of items to skip before starting to return results.

Bounds later pages to the rows that existed when the traversal started, inclusive. Set by a list whose own reads write rows it would page over.

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 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)

Start index (inclusive).

End index (exclusive).

The advice status.

The advice code.

The advice title.

The advice content.

The start_position is inclusive and the end_position is exclusive. TODO: use range instead.

List of role names that must approve, in order.

The approval workflow specification.

Human-readable title of the approval template.

Detailed description of when this template applies.

The approval template being used for this issue.

List of approvers and their current status.

Whether the system has finished finding a matching approval template. False means the backend is still searching for matching templates.

The plan approval input version used to generate this approval flow.

The current approval status.

The principal who is the approver. Format: users/{email}.

The project or workspace the audit log belongs to. Formats: - projects/{project} - workspaces/{workspace}

Example: /bytebase.v1.SQLService/Query

The resource name. Example: projects/{project}

The principal who performed the action. Formats: users/{email}, serviceAccounts/{email}, or workloadIdentities/{email}.

Marshalled request.

Marshalled response. Some fields are omitted because they are too large or contain sensitive information.

The latency of the RPC.

The service-specific data about the request, response, and other activities.

Metadata about the operation.

MCP delegation provenance. Present exactly when the entry belongs to MCP: the audited call arrived through the MCP server's delegated credential, or it is one of the two MCP doors that sit outside the API — the /mcp connection gate and the OAuth2 consent that mints the credential it checks. Never set for public API calls. Presence of this message is the MCP-origin marker.

The OAuth2 grant's consented scope, e.g. "mcp:read-only". Empty when the grant recorded no scope.

The grant's stored MCP resource URI. Empty for pre-grant legacy sessions.

The OAuth2 client the grant was consented to. Empty for legacy web-session tokens at /mcp.

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. Empty on the entries that belong to no session — a refused consent, which never reached that boundary, and a refused connection, which is decided before the SDK resolves a session. Filling those with a fresh value would read as a session ID that correlates exactly one row, and a mid-session refusal would get an ID different from the rows the session already wrote.

The IP address of the caller.

The user agent of the caller. This information is not authenticated and should be treated accordingly.

Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun}

The name of the column.

The user labels for a column.

The schema_configs is the list of configs for schemas in a database.

The release that was last applied to this database. Format: projects/{project}/releases/{release_id}

The sync status of the database.

The error message if sync failed.

The role name. It's unique within the instance.

The grant display string on the instance. It's generated by database engine.

The schema name. It is an empty string for databases without such concept such as MySQL.

The table_configs is the list of configs for tables in a schema.

The name of the table.

The column_configs is the ordered list of configs for columns in a table.

Member is the principal who belongs to this group. Format: users/{email}.

The source indicates where the group comes from. For now we support Entra ID SCIM sync, so the source could be Entra ID.

Identifier is the field name of the unique identifier in 3rd-party idp user info. Required.

DisplayName is the field name of display name in 3rd-party idp user info. Optional.

Phone is the field name of primary phone in 3rd-party idp user info. Optional.

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/

Identifier is the value of the unique identifier in 3rd-party idp user info.

DisplayName is the value of display name in 3rd-party idp user info.

Phone is the value of primary phone in 3rd-party idp user info.

Groups is the value of groups in 3rd-party idp user info. Mainly used for OIDC: https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/

Host is the hostname or IP address of the LDAP server, e.g. "ldap.example.com".

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.

SkipTLSVerify controls whether to skip TLS certificate verification.

BindDN is the DN of the user to bind as a service account to perform search requests.

BindPassword is the password of the user to bind as a service account.

BaseDN is the base DN to search for users, e.g. "ou=users,dc=example,dc=com".

UserFilter is the filter to search for users, e.g. "(uid=%s)".

SecurityProtocol is the security protocol to be used for establishing connections with the LDAP server.

FieldMapping is the mapping of the user attributes returned by the LDAP server.

Use SSL to connect to the data source. By default, we use the system's SSL configuration.

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).

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 is the database name to authenticate against, which stores the user credentials.

replica_set is used for MongoDB replica set.

sid and service_name are used for Oracle.

SSH related The hostname of the SSH server agent.

The port of the SSH server agent. It's 22 typically.

The user to login the server.

The password to login the server. If it's empty string, no password is required.

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").

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.

Passphrase for the encrypted PKCS#8 private key. Only used when the private key is encrypted.

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.

additional_addresses is used for MongoDB replica set.

direct_connection is used for MongoDB to dispatch all the operations to the node specified in the connection string.

Region is the location of the database, used for AWS RDS. For example, us-east-1.

warehouse_id is used by Databricks.

master_name is the master name used by connecting redis-master via redis sentinel.

master_username and master_obfuscated_password are master credentials used by redis sentinel mode.

Extra connection parameters for the database connection. For PostgreSQL HA, this can be used to set target_session_attrs=read-write

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).

ARN of IAM role to assume for cross-account access. See: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

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

How to interpret the token field when auth_type is TOKEN.

engine name is the name for secret engine.

the secret name in the engine to store the password.

the key name for the password.

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.

CA certificate for Vault server verification.

Client certificate for mutual TLS authentication with Vault.

Client private key for mutual TLS authentication with Vault.

The secret ID for the role without TTL.

The path where the approle auth method is mounted.

The interval between automatic instance synchronizations.

Enable sync for the following databases. Not set means sync all schemas & databases.

The lower_case_table_names config for MySQL instances. It is used to determine whether the table names and database names are case sensitive.

Labels are key-value pairs that can be attached to the instance. For example, { "org_group": "infrastructure", "environment": "production" }

The role name.

The connection count limit for this role.

The expiration for the role's password.

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 is 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

Approval information for the issue workflow.

Role grant details if this is a role grant issue.

Labels attached to categorize and filter the issue.

Risk level for the issue, calculated from statement types.

The access grant id for ACCESS_GRANT type issue.

Whether this issue is a Draft Review Issue. Missing from persisted payloads means false.

The role being requested for the user. Format: roles/{role}.

The user who will receive the role. Format: users/{email}.

Optional conditional expression that limits when the grant applies.

Duration after which the grant automatically expires.

Whether the plan has started the rollout.

Internal monotonic version for plan inputs that affect approval generation. Starts at the proto default 0 for compatibility with existing plans.

The list of targets. Multi-database format: [instances/{instance-id}/databases/{database-name}]. Single database group format: [projects/{project}/databaseGroups/{databaseGroup}].

The SHA256 hash of the sheet content (hex-encoded).

The resource name of the release. Format: projects/{project}/releases/{release}

If set, a backup of the modified data will be created automatically before any changes are applied.

The resource name of the instance on which the database is created. Format: instances/{instance}

The name of the database to create.

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 is the character set of the database.

collation is the collation of the database.

cluster is the cluster of the database. This is only applicable to ClickHouse for "ON CLUSTER <<cluster>>".

owner is the owner of the database. This is only applicable to Postgres for "WITH OWNER <<owner>>".

The environment resource. Format: environments/prod where prod is the environment resource ID.

A UUID4 string that uniquely identifies the Spec.

Fatal execution error for the FAILED status, e.g. "metadata not synced: instances/prod/databases/db1, db2, db3 (+497 more)". Written by the executor or by the reaper.

The plan's PlanConfig.approval_input_version when the slot was reset: the version of the plan's SQL this run reviews. Completion keeps it.

The statement context an inline comment references. Set at creation and immutable afterward; never set together with an event.

Present on review results only, beside the text and never together with an event. Written by the review executor; CreateIssueComment rejects it. The anchor is statement_anchor; a result without one addresses the whole change.

The reviewer slot that posted the result; review_run.type stores the same enum by name.

The rule judged against. Set if and only if run_type is RULE.

A result merged across databases carries the highest priority among them.

Every database the result applies to, sorted. Always complete; the renderer collapses it when it equals the spec's target set. Format: instances/{instance}/databases/{database}

A later run of the same reviewer has completed, so the result is not from the latest review. Set by that run whatever the thread state, and never cleared.

UUID of the anchored plan spec (PlanConfig.Spec.id); may no longer resolve after the spec is deleted from the plan.

SHA256 hex of the anchored sheet revision.

The anchored range. When both columns are 0, the anchor spans whole lines from start_position.line to end_position.line inclusive — overriding Position's "column 0 means unknown" convention. When both columns are set, start_position is inclusive and end_position is exclusive, in one-based lines and code-point columns (see Position). Setting exactly one column to 0 is invalid.

The canonical resource URI (RFC 8707) this grant is bound to, validated at consent time against the configured external URL. Empty for clients that omit the resource parameter.

The single mode consented to, normalized from the client's requested scope set to its maximum. Empty means no scope was requested.

The canonical resource URI (RFC 8707) this grant is bound to, validated at consent time against the configured external URL. Empty for clients that omit the resource parameter.

The single mode consented to, normalized from the client's requested scope set to its maximum. Empty means no scope was requested.

The estimated row count of the table.

The plan approval input version this check run was created for.

Target identification for consolidated results Format: instances/{instance}/databases/{database}

sheet_sha256 is the content hash of the SQL sheet used to produce this result. Empty for checks that are not tied to a SQL sheet.

Position of the SQL statement.

statement_types are the types of statements found in the SQL.

The role that is assigned to the members. Format: roles/{role}

Specifies the principals requesting access for a Bytebase resource. For users, the member should be: users/{email} For groups, the member should be: groups/{email}

The condition that is associated with this binding. 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.

Collection of binding. A binding binds one or more members or groups to a single role.

Members who bind to this exemption. Format: users/{email} or groups/{group email}

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"

A unique identifier for a node in UUID format.

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.

workspace-level policy Disable copying data.

workspace-level policy Allow using the admin data source to query in the SQL editor.

workspace-level policy Disable the Download export destination. Exports can still go to a configured storage destination such as SharePoint.

================ Deprecate following fields. Disallow running DDL statements in the SQL editor.

Disallow running DML statements in the SQL editor.

tags is the key-value map for resources. For example, the environment resource can have the SQL review config tag, such as "bb.tag.review_config": "reviewConfigs/{review config resource id}".

The display text of the label.

The color for the label.

Optional group name for organizing related labels.

Available labels that can be applied to issues in this project.

Force issue labels to be used when creating an issue.

Enforce issue title created by user instead of generated by Bytebase.

Whether to enable the database tenant mode for PostgreSQL. If enabled, the issue will be created with the prepend "set role <db_owner>" statement.

Whether to allow the issue creator to self-approve the issue.

Configuration for automatic retry on task execution failures.

The maximum number of databases to sample during CI data validation and AI review. If not specified, sampling is disabled, resulting in a full validation.

The maximum number of parallel tasks to run during the rollout.

Labels are key-value pairs that can be attached to the project. For example, { "environment": "production", "team": "backend" }

Whether to enforce SQL review checks to pass before issue creation. If enabled, issues cannot be created when SQL review finds errors.

Whether issue approval is required before proceeding with rollout.

Whether to block rollout when plan check finds errors.

The data classification configuration ID for the project.

Once enabled, users can request and use the just-in-time access in the SQL Editor.

Whether to allow the last Plan editor to approve a database change issue.

Destinations offered for this project's exports.

The maximum number of retry attempts for lock timeout errors.

The canonical URL of a SharePoint document library root or folder.

Webhook type.

Webhook title.

Webhook URL.

List of activities that trigger this webhook.

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.

The path of the file, e.g., `2.2/V0001_create_table.sql`.

The SHA256 hash of the sheet content (hex-encoded).

Format: projects/{project}/releases/{release} Can be empty.

The file filepath. Can be empty.

The SHA256 hash of the sheet content (hex-encoded).

The task run associated with the revision. Can be empty. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/{taskRun}

The type of the revision.

The project that authored this revision's change — where the plan or release that produced it ran. Stamped by the server at creation from the database's then-current project; rows predating the field are backfilled from corroborated provenance (migration 3.22.5). Not a scope: revisions stay keyed by (instance, db_name) and follow the database across project transfers, while the statement's sheet stays readable under this project. Can be empty when no owner could be corroborated; such statements are unreadable and the revision carries no sheet name.

Principals in the same resource-name form the IAM policy payloads use: "users/{email}" and "groups/{email}". The v1 API takes the binding form ("user:", "group:") and converts once on write, as the project policy does. Groups are named by reference and never expanded.

The connected database, stored as its canonical resource name: instances/{instance}/databases/{database} for a workspace instance, projects/{project}/instances/{instance}/databases/{database} for a project instance. Validated against the saved query's own project at write time; the reference is soft and may dangle after the database is deleted or transferred, degrading to "no database" in the UI.

Authentication secret for token signing (32-character random string).

Whether the AI SQL review may run. It is a consent of its own beside `enabled`, because a review sends the statements of a change to the provider and can send the schema of its target databases.

substitution is the string used to replace the original value, the max length of the string is 16 bytes.

salt is the salt value to generate a different hash that with the word alone.

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.

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 is the end character index (exclusive) of the original value. Uses character indices (not byte offsets) for display-oriented masking.

OriginalValue[start:end) would be replaced with substitution.

Azure AD tenant ID (Directory ID).

Azure AD application (client) ID.

Azure AD client secret.

id is the uuid for classification. Each project can chose one classification config.

levels is user defined level list for classification.

classification is the id - DataClassification map. The id should in [0-9]+-[0-9]+-[0-9]+ format.

id is the classification id in [0-9]+-[0-9]+-[0-9]+ format.

The sensitivity level. Maps to Level.level.

The numeric level for ordering. Higher = more sensitive.