本頁由 docs-site/scripts/sync-api-docs.sh 從 proto/gen/grpc-doc/ 自動產生。 不要直接編輯本檔；改 proto + 跑 make proto 後重新同步。

Protocol Documentation

Table of Contents

• v1/annotation.proto

  • AuthMethod

  • File-level Extensions

  • File-level Extensions

  • File-level Extensions

  • File-level Extensions

• v1/access_grant_service.proto

  • AccessGrant

  • ActivateAccessGrantRequest

  • CreateAccessGrantRequest

  • GetAccessGrantRequest

  • ListAccessGrantsRequest

  • ListAccessGrantsResponse

  • RevokeAccessGrantRequest

  • SearchMyAccessGrantsRequest

  • SearchMyAccessGrantsResponse

  • AccessGrant.Status

  • AccessGrantService

• v1/common.proto

  • PermissionDeniedDetail

  • Position

  • Range

  • Engine

  • ExportFormat

  • RiskLevel

  • State

  • StatementType

  • VCSType

  • WebhookType

• v1/issue_service.proto

  • ApprovalFlow

  • ApprovalTemplate

  • ApproveIssueRequest

  • BatchUpdateIssuesStatusRequest

  • BatchUpdateIssuesStatusResponse

  • CreateIssueCommentRequest

  • CreateIssueRequest

  • GetIssueRequest

  • Issue

  • Issue.Approver

  • IssueComment

  • IssueComment.Approval

  • IssueComment.IssueUpdate

  • IssueComment.PlanSpecUpdate

  • ListIssueCommentsRequest

  • ListIssueCommentsResponse

  • ListIssuesRequest

  • ListIssuesResponse

  • RejectIssueRequest

  • RequestIssueRequest

  • RoleGrant

  • SearchIssuesRequest

  • SearchIssuesResponse

  • UpdateIssueCommentRequest

  • UpdateIssueRequest

  • Issue.ApprovalStatus

  • Issue.Approver.Status

  • Issue.Type

  • IssueComment.Approval.Status

  • IssueStatus

  • IssueService

• v1/setting_service.proto

  • AISetting

  • Algorithm

  • Algorithm.FullMask

  • Algorithm.InnerOuterMask

  • Algorithm.MD5Mask

  • Algorithm.RangeMask

  • Algorithm.RangeMask.Slice

  • Announcement

  • AppIMSetting

  • AppIMSetting.DingTalk

  • AppIMSetting.Feishu

  • AppIMSetting.IMSetting

  • AppIMSetting.Lark

  • AppIMSetting.Slack

  • AppIMSetting.Teams

  • AppIMSetting.Telegram

  • AppIMSetting.Wecom

  • DataClassificationSetting

  • DataClassificationSetting.DataClassificationConfig

  • DataClassificationSetting.DataClassificationConfig.ClassificationEntry

  • DataClassificationSetting.DataClassificationConfig.DataClassification

  • DataClassificationSetting.DataClassificationConfig.Level

  • EmailSetting

  • EmailSetting.SMTPConfig

  • EnvironmentSetting

  • EnvironmentSetting.Environment

  • EnvironmentSetting.Environment.TagsEntry

  • GetSettingRequest

  • GetSettingResponse

  • ListSettingsRequest

  • ListSettingsResponse

  • SemanticTypeSetting

  • SemanticTypeSetting.SemanticType

  • Setting

  • SettingValue

  • TestEmailSettingRequest

  • TestEmailSettingResponse

  • UpdateSettingRequest

  • WorkspaceApprovalSetting

  • WorkspaceApprovalSetting.Rule

  • WorkspaceProfileSetting

  • WorkspaceProfileSetting.PasswordRestriction

  • AISetting.Provider

  • Algorithm.InnerOuterMask.MaskType

  • Announcement.AlertLevel

  • DatabaseChangeMode

  • EmailSetting.SMTPConfig.Authentication

  • EmailSetting.SMTPConfig.Encryption

  • EmailSetting.Type

  • Setting.SettingName

  • WorkspaceApprovalSetting.Rule.Source

  • SettingService

• v1/actuator_service.proto

  • ActuatorInfo

  • DeleteCacheRequest

  • GetActuatorInfoRequest

  • Restriction

  • ActuatorService

• v1/ai_service.proto

  • AIChatMessage

  • AIChatRequest

  • AIChatResponse

  • AIChatToolCall

  • AIChatToolDefinition

  • AIChatUsage

  • AIChatMessageRole

  • AIService

• v1/iam_policy.proto

  • Binding

  • BindingDelta

  • GetIamPolicyRequest

  • IamPolicy

  • PolicyDelta

  • SetIamPolicyRequest

  • BindingDelta.Action

• v1/audit_log_service.proto

  • AuditData

  • AuditLog

  • ExportAuditLogsRequest

  • ExportAuditLogsResponse

  • RequestMetadata

  • SearchAuditLogsRequest

  • SearchAuditLogsResponse

  • AuditLog.Severity

  • AuditLogService

• v1/user_service.proto

  • BatchGetUsersRequest

  • BatchGetUsersResponse

  • CreateUserRequest

  • DeleteUserRequest

  • GetUserRequest

  • ListUsersRequest

  • ListUsersResponse

  • UndeleteUserRequest

  • UpdateEmailRequest

  • UpdateUserRequest

  • User

  • User.Profile

  • UserService

• v1/auth_service.proto

  • ExchangeTokenRequest

  • ExchangeTokenResponse

  • IdentityProviderContext

  • LoginRequest

  • LoginResponse

  • LogoutRequest

  • OAuth2IdentityProviderContext

  • OIDCIdentityProviderContext

  • RefreshRequest

  • RefreshResponse

  • RequestPasswordResetRequest

  • ResetPasswordRequest

  • SendEmailLoginCodeRequest

  • SignupRequest

  • SwitchWorkspaceRequest

  • AuthService

• v1/cel_service.proto

  • BatchDeparseRequest

  • BatchDeparseResponse

  • BatchParseRequest

  • BatchParseResponse

  • CelService

• v1/database_catalog_service.proto

  • ColumnCatalog

  • ColumnCatalog.LabelsEntry

  • DatabaseCatalog

  • GetDatabaseCatalogRequest

  • ObjectSchema

  • ObjectSchema.ArrayKind

  • ObjectSchema.StructKind

  • ObjectSchema.StructKind.PropertiesEntry

  • SchemaCatalog

  • TableCatalog

  • TableCatalog.Columns

  • UpdateDatabaseCatalogRequest

  • ObjectSchema.Type

  • DatabaseCatalogService

• v1/database_group_service.proto

  • CreateDatabaseGroupRequest

  • DatabaseGroup

  • DatabaseGroup.Database

  • DeleteDatabaseGroupRequest

  • GetDatabaseGroupRequest

  • ListDatabaseGroupsRequest

  • ListDatabaseGroupsResponse

  • UpdateDatabaseGroupRequest

  • DatabaseGroupView

  • DatabaseGroupService

• v1/instance_role_service.proto

  • InstanceRole

  • ListInstanceRolesRequest

  • ListInstanceRolesResponse

  • InstanceRoleService

• v1/instance_service.proto

  • AddDataSourceRequest

  • BatchSyncInstancesRequest

  • BatchSyncInstancesResponse

  • BatchUpdateInstancesRequest

  • BatchUpdateInstancesResponse

  • CreateInstanceRequest

  • DataSource

  • DataSource.AWSCredential

  • DataSource.Address

  • DataSource.AzureCredential

  • DataSource.ExtraConnectionParametersEntry

  • DataSource.GCPCredential

  • DataSourceExternalSecret

  • DataSourceExternalSecret.AppRoleAuthOption

  • DeleteInstanceRequest

  • GetInstanceRequest

  • Instance

  • Instance.LabelsEntry

  • InstanceResource

  • KerberosConfig

  • ListInstanceDatabaseRequest

  • ListInstanceDatabaseResponse

  • ListInstancesRequest

  • ListInstancesResponse

  • RemoveDataSourceRequest

  • SASLConfig

  • SyncInstanceRequest

  • SyncInstanceResponse

  • UndeleteInstanceRequest

  • UpdateDataSourceRequest

  • UpdateInstanceRequest

  • DataSource.AuthenticationType

  • DataSource.RedisType

  • DataSourceExternalSecret.AppRoleAuthOption.SecretType

  • DataSourceExternalSecret.AuthType

  • DataSourceExternalSecret.SecretType

  • DataSourceType

  • InstanceService

• v1/database_service.proto

  • BatchGetDatabasesRequest

  • BatchGetDatabasesResponse

  • BatchSyncDatabasesRequest

  • BatchSyncDatabasesResponse

  • BatchUpdateDatabasesRequest

  • BatchUpdateDatabasesResponse

  • BoundingBox

  • Changelog

  • CheckConstraintMetadata

  • ColumnMetadata

  • Database

  • Database.LabelsEntry

  • DatabaseMetadata

  • DatabaseSDLSchema

  • DatabaseSchema

  • DependencyColumn

  • DependencyTable

  • DiffSchemaRequest

  • DiffSchemaResponse

  • DimensionConstraint

  • DimensionalConfig

  • EnumTypeMetadata

  • EventMetadata

  • ExtensionMetadata

  • ExternalTableMetadata

  • ForeignKeyMetadata

  • FunctionMetadata

  • GenerationMetadata

  • GetChangelogRequest

  • GetDatabaseMetadataRequest

  • GetDatabaseRequest

  • GetDatabaseSDLSchemaRequest

  • GetDatabaseSchemaRequest

  • GetSchemaStringRequest

  • GetSchemaStringResponse

  • GridLevel

  • IndexMetadata

  • ListChangelogsRequest

  • ListChangelogsResponse

  • ListDatabasesRequest

  • ListDatabasesResponse

  • MaterializedViewMetadata

  • PackageMetadata

  • ProcedureMetadata

  • SchemaMetadata

  • SequenceMetadata

  • SpatialIndexConfig

  • StorageConfig

  • StreamMetadata

  • SyncDatabaseRequest

  • SyncDatabaseResponse

  • TableMetadata

  • TablePartitionMetadata

  • TaskMetadata

  • TessellationConfig

  • TriggerMetadata

  • UpdateDatabaseRequest

  • ViewMetadata

  • Changelog.Status

  • ChangelogView

  • ColumnMetadata.IdentityGeneration

  • GenerationMetadata.Type

  • GetDatabaseSDLSchemaRequest.SDLFormat

  • GetSchemaStringRequest.ObjectType

  • StreamMetadata.Mode

  • StreamMetadata.Type

  • SyncStatus

  • TablePartitionMetadata.Type

  • TaskMetadata.State

  • DatabaseService

• v1/group_service.proto

  • BatchGetGroupsRequest

  • BatchGetGroupsResponse

  • CreateGroupRequest

  • DeleteGroupRequest

  • GetGroupRequest

  • Group

  • GroupMember

  • ListGroupsRequest

  • ListGroupsResponse

  • UpdateGroupRequest

  • GroupMember.Role

  • GroupService

• v1/idp_service.proto

  • CreateIdentityProviderRequest

  • DeleteIdentityProviderRequest

  • FieldMapping

  • GetIdentityProviderRequest

  • IdentityProvider

  • IdentityProviderConfig

  • LDAPIdentityProviderConfig

  • ListIdentityProvidersRequest

  • ListIdentityProvidersResponse

  • OAuth2IdentityProviderConfig

  • OAuth2IdentityProviderTestRequestContext

  • OIDCIdentityProviderConfig

  • OIDCIdentityProviderTestRequestContext

  • TestIdentityProviderRequest

  • TestIdentityProviderResponse

  • TestIdentityProviderResponse.ClaimsEntry

  • TestIdentityProviderResponse.UserInfoEntry

  • UpdateIdentityProviderRequest

  • IdentityProviderType

  • LDAPIdentityProviderConfig.SecurityProtocol

  • OAuth2AuthStyle

  • IdentityProviderService

• v1/org_policy_service.proto

  • CreatePolicyRequest

  • DeletePolicyRequest

  • GetPolicyRequest

  • ListPoliciesRequest

  • ListPoliciesResponse

  • MaskingExemptionPolicy

  • MaskingExemptionPolicy.Exemption

  • MaskingRulePolicy

  • MaskingRulePolicy.MaskingRule

  • Policy

  • QueryDataPolicy

  • RolloutPolicy

  • TagPolicy

  • TagPolicy.TagsEntry

  • UpdatePolicyRequest

  • PolicyResourceType

  • PolicyType

  • OrgPolicyService

• v1/rollout_service.proto

  • BatchCancelTaskRunsRequest

  • BatchCancelTaskRunsResponse

  • BatchRunTasksRequest

  • BatchRunTasksResponse

  • BatchSkipTasksRequest

  • BatchSkipTasksResponse

  • CreateRolloutRequest

  • GetRolloutRequest

  • GetTaskRunLogRequest

  • GetTaskRunRequest

  • GetTaskRunSessionRequest

  • ListRolloutsRequest

  • ListRolloutsResponse

  • ListTaskRunsRequest

  • ListTaskRunsResponse

  • PreviewTaskRunRollbackRequest

  • PreviewTaskRunRollbackResponse

  • Rollout

  • Stage

  • Task

  • Task.DatabaseCreate

  • Task.DatabaseDataExport

  • Task.DatabaseUpdate

  • TaskRun

  • TaskRun.SchedulerInfo

  • TaskRun.SchedulerInfo.WaitingCause

  • TaskRun.SchedulerInfo.WaitingCause.EmergencyPause

  • TaskRun.SchedulerInfo.WaitingCause.MaintenanceWindow

  • TaskRunLog

  • TaskRunLogEntry

  • TaskRunLogEntry.CommandExecute

  • TaskRunLogEntry.CommandExecute.CommandResponse

  • TaskRunLogEntry.ComputeDiff

  • TaskRunLogEntry.DatabaseSync

  • TaskRunLogEntry.PriorBackup

  • TaskRunLogEntry.PriorBackup.PriorBackupDetail

  • TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item

  • TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item.Table

  • TaskRunLogEntry.ReleaseFileExecute

  • TaskRunLogEntry.RetryInfo

  • TaskRunLogEntry.SchemaDump

  • TaskRunLogEntry.TransactionControl

  • TaskRunSession

  • TaskRunSession.Postgres

  • TaskRunSession.Postgres.Session

  • Task.Status

  • Task.Type

  • TaskRun.ExportArchiveStatus

  • TaskRun.Status

  • TaskRunLogEntry.TransactionControl.Type

  • TaskRunLogEntry.Type

  • RolloutService

• v1/sql_service.proto

  • AICompletionRequest

  • AICompletionRequest.Message

  • AICompletionResponse

  • AICompletionResponse.Candidate

  • AICompletionResponse.Candidate.Content

  • AICompletionResponse.Candidate.Content.Part

  • AdminExecuteRequest

  • AdminExecuteResponse

  • Advice

  • DiffMetadataRequest

  • DiffMetadataResponse

  • ExportRequest

  • ExportResponse

  • MaskingReason

  • QueryHistory

  • QueryOption

  • QueryRequest

  • QueryResponse

  • QueryResult

  • QueryResult.CommandError

  • QueryResult.Message

  • QueryResult.PostgresError

  • QueryResult.SyntaxError

  • QueryRow

  • RowValue

  • RowValue.Timestamp

  • RowValue.TimestampTZ

  • SearchQueryHistoriesRequest

  • SearchQueryHistoriesResponse

  • Advice.Level

  • Advice.RuleType

  • QueryHistory.Type

  • QueryOption.MSSQLExplainFormat

  • QueryOption.RedisRunCommandsOn

  • QueryResult.CommandError.Type

  • QueryResult.Message.Level

  • SQLService

• v1/plan_service.proto

  • CancelPlanCheckRunRequest

  • CancelPlanCheckRunResponse

  • CreatePlanRequest

  • GetPlanCheckRunRequest

  • GetPlanRequest

  • ListPlansRequest

  • ListPlansResponse

  • Plan

  • Plan.ChangeDatabaseConfig

  • Plan.CreateDatabaseConfig

  • Plan.ExportDataConfig

  • Plan.PlanCheckRunStatusCountEntry

  • Plan.RolloutStageSummary

  • Plan.Spec

  • Plan.TaskStatusCount

  • PlanCheckRun

  • PlanCheckRun.Result

  • PlanCheckRun.Result.SqlReviewReport

  • PlanCheckRun.Result.SqlSummaryReport

  • RunPlanChecksRequest

  • RunPlanChecksResponse

  • UpdatePlanRequest

  • PlanCheckRun.Result.Type

  • PlanCheckRun.Status

  • PlanService

• v1/project_service.proto

  • Activity

  • AddWebhookRequest

  • BatchDeleteProjectsRequest

  • BatchGetProjectsRequest

  • BatchGetProjectsResponse

  • CreateProjectRequest

  • DeleteProjectRequest

  • GetProjectRequest

  • Label

  • ListProjectsRequest

  • ListProjectsResponse

  • Project

  • Project.ExecutionRetryPolicy

  • Project.LabelsEntry

  • RemoveWebhookRequest

  • SearchProjectsRequest

  • SearchProjectsResponse

  • TestWebhookRequest

  • TestWebhookResponse

  • UndeleteProjectRequest

  • UpdateProjectRequest

  • UpdateWebhookRequest

  • Webhook

  • Activity.Type

  • ProjectService

• v1/release_service.proto

  • CheckReleaseRequest

  • CheckReleaseResponse

  • CheckReleaseResponse.CheckResult

  • CreateReleaseRequest

  • DeleteReleaseRequest

  • GetReleaseRequest

  • ListReleaseCategoriesRequest

  • ListReleaseCategoriesResponse

  • ListReleasesRequest

  • ListReleasesResponse

  • Release

  • Release.File

  • Release.VCSSource

  • UndeleteReleaseRequest

  • UpdateReleaseRequest

  • Release.Type

  • ReleaseService

• v1/review_config_service.proto

  • CreateReviewConfigRequest

  • DeleteReviewConfigRequest

  • GetReviewConfigRequest

  • ListReviewConfigsRequest

  • ListReviewConfigsResponse

  • ReviewConfig

  • SQLReviewRule

  • SQLReviewRule.CommentConventionRulePayload

  • SQLReviewRule.NamingCaseRulePayload

  • SQLReviewRule.NamingRulePayload

  • SQLReviewRule.NumberRulePayload

  • SQLReviewRule.StringArrayRulePayload

  • SQLReviewRule.StringRulePayload

  • UpdateReviewConfigRequest

  • SQLReviewRule.Level

  • SQLReviewRule.Type

  • ReviewConfigService

• v1/revision_service.proto

  • BatchCreateRevisionsRequest

  • BatchCreateRevisionsResponse

  • CreateRevisionRequest

  • DeleteRevisionRequest

  • GetRevisionRequest

  • ListRevisionsRequest

  • ListRevisionsResponse

  • Revision

  • Revision.Type

  • RevisionService

• v1/role_service.proto

  • CreateRoleRequest

  • DeleteRoleRequest

  • GetRoleRequest

  • ListRolesRequest

  • ListRolesResponse

  • Role

  • UpdateRoleRequest

  • Role.Type

  • RoleService

• v1/service_account_service.proto

  • CreateServiceAccountRequest

  • DeleteServiceAccountRequest

  • GetServiceAccountRequest

  • ListServiceAccountsRequest

  • ListServiceAccountsResponse

  • ServiceAccount

  • UndeleteServiceAccountRequest

  • UpdateServiceAccountRequest

  • ServiceAccountService

• v1/sheet_service.proto

  • BatchCreateSheetsRequest

  • BatchCreateSheetsResponse

  • CreateSheetRequest

  • GetSheetRequest

  • Sheet

  • SheetService

• v1/subscription_service.proto

  • CancelPurchaseRequest

  • CreatePurchaseRequest

  • GetPaymentInfoRequest

  • GetSubscriptionRequest

  • ListPurchasePlansRequest

  • ListPurchasePlansResponse

  • PaymentInfo

  • PlanConfig

  • PlanLimitConfig

  • PurchaseBillingMethod

  • PurchaseDiscount

  • PurchasePlan

  • PurchasePlanAdditional

  • PurchaseResponse

  • Subscription

  • UpdatePurchaseRequest

  • UploadLicenseRequest

  • VerifyCheckoutSessionRequest

  • VerifyCheckoutSessionResponse

  • BillingInterval

  • PlanFeature

  • PlanType

  • PurchaseDiscount.Type

  • PurchasePlanAdditional.Type

  • SubscriptionService

• v1/workload_identity_service.proto

  • CreateWorkloadIdentityRequest

  • DeleteWorkloadIdentityRequest

  • GetWorkloadIdentityRequest

  • ListWorkloadIdentitiesRequest

  • ListWorkloadIdentitiesResponse

  • UndeleteWorkloadIdentityRequest

  • UpdateWorkloadIdentityRequest

  • WorkloadIdentity

  • WorkloadIdentityConfig

  • WorkloadIdentityConfig.ProviderType

  • WorkloadIdentityService

• v1/worksheet_service.proto

  • BatchUpdateWorksheetOrganizerRequest

  • BatchUpdateWorksheetOrganizerResponse

  • CreateWorksheetRequest

  • DeleteWorksheetRequest

  • GetWorksheetRequest

  • SearchWorksheetsRequest

  • SearchWorksheetsResponse

  • UpdateWorksheetOrganizerRequest

  • UpdateWorksheetRequest

  • Worksheet

  • WorksheetOrganizer

  • Worksheet.Visibility

  • WorksheetService

• v1/workspace_service.proto

  • GetWorkspaceRequest

  • ListWorkspacesRequest

  • ListWorkspacesResponse

  • UpdateWorkspaceRequest

  • Workspace

  • WorkspaceService

• Scalar Value Types

Top

v1/annotation.proto

AuthMethod

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.

File-level Extensions

Extension	Type	Base	Number	Description
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.
permission	string	.google.protobuf.MethodOptions	100001	The permission required to call this method.

Top

v1/access_grant_service.proto

AccessGrant

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. Format: users/
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/
targets	string	repeated	The target databases for this access grant. Format: instances/{instance}/databases/
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

ActivateAccessGrantRequest

Field	Type	Label	Description
name	string		The name of the access grant to activate. Format: projects/{project}/accessGrants/

CreateAccessGrantRequest

Field	Type	Label	Description
parent	string		The parent project for the access grant. Format: projects/
access_grant	AccessGrant		The access grant to create.

GetAccessGrantRequest

Field	Type	Label	Description
name	string		The name of the access grant to retrieve. Format: projects/{project}/accessGrants/

ListAccessGrantsRequest

Field	Type	Label	Description
parent	string		The parent project of the access grants. Format: projects/
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 - target: the target database fullname, support "==" operator.

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

ListAccessGrantsResponse

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.

RevokeAccessGrantRequest

Field	Type	Label	Description
name	string		The name of the access grant to revoke. Format: projects/{project}/accessGrants/

SearchMyAccessGrantsRequest

Field	Type	Label	Description
parent	string		The parent project to search in. Format: projects/
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.

SearchMyAccessGrantsResponse

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.

AccessGrant.Status

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

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.

Top

v1/common.proto

PermissionDeniedDetail

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

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

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

Engine

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.
SQLITE	5	SQLite embedded database.
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.

ExportFormat

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.

RiskLevel

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.

State

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

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

VCSType

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.

WebhookType

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.
TELEGRAM	9	[Argus P1-4 M4.0] Telegram Bot API integration.

Top

v1/issue_service.proto

ApprovalFlow

Field	Type	Label	Description
roles	string	repeated	The roles required for approval in order.

ApprovalTemplate

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.

ApproveIssueRequest

Field	Type	Label	Description
name	string		The name of the issue to add an approver. Format: projects/{project}/issues/
comment	string		The comment explaining the approval decision.

BatchUpdateIssuesStatusRequest

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/
status	IssueStatus		The new status.
reason	string		The reason for the status change.

BatchUpdateIssuesStatusResponse

CreateIssueCommentRequest

Field	Type	Label	Description
parent	string		The issue name Format: projects/{project}/issues/
issue_comment	IssueComment		The comment to create.

CreateIssueRequest

Field	Type	Label	Description
parent	string		The parent, which owns this collection of issues. Format: projects/
issue	Issue		The issue to create.

GetIssueRequest

Field	Type	Label	Description
name	string		The name of the issue to retrieve. Format: projects/{project}/issues/
force	bool		If set to true, bypass cache and fetch the latest data.

Issue

Field	Type	Label	Description
name	string		The name of the issue. Format: projects/{project}/issues/
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/
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	Issue.ApprovalStatus
access_grant	string		The access grant associated with this issue. Format: projects/{project}/accessGrants/

Issue.Approver

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

IssueComment

A comment on an issue.

Field	Type	Label	Description
name	string		Format: projects/{project}/issues/{issue}/issueComments/
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/
approval	IssueComment.Approval		Approval event.
issue_update	IssueComment.IssueUpdate		Issue update event.
plan_spec_update	IssueComment.PlanSpecUpdate		Plan spec update event.

IssueComment.Approval

Approval event information.

Field	Type	Label	Description
status	IssueComment.Approval.Status		The approval status.

IssueComment.IssueUpdate

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

IssueComment.PlanSpecUpdate

Plan spec update event information (tracks sheet changes to plan specs).

Field	Type	Label	Description
spec	string		The spec that was updated. Format: projects/{project}/plans/{plan}/specs/
from_sheet	string	optional	The previous sheet. Format: projects/{project}/sheets/
to_sheet	string	optional	The new sheet. Format: projects/{project}/sheets/

ListIssueCommentsRequest

Field	Type	Label	Description
parent	string		Format: projects/{projects}/issues/
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. |

ListIssueCommentsResponse

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.

ListIssuesRequest

Field	Type	Label	Description
parent	string		The parent, which owns this collection of issues. Format: projects/
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" |

ListIssuesResponse

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.

RejectIssueRequest

Field	Type	Label	Description
name	string		The name of the issue to add a rejection. Format: projects/{project}/issues/
comment	string		The comment explaining the rejection decision.

RequestIssueRequest

Field	Type	Label	Description
name	string		The name of the issue to request a issue. Format: projects/{project}/issues/
comment	string		The comment explaining the request.

RoleGrant

Field	Type	Label	Description
role	string		The requested role. Format: roles/EXPORTER.
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.

SearchIssuesRequest

Field	Type	Label	Description
parent	string		The parent, which owns this collection of issues. Format: projects/{project} Use "projects/-" to list all issues from all projects.
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" |

SearchIssuesResponse

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.

UpdateIssueCommentRequest

Field	Type	Label	Description
parent	string		The issue name Format: projects/{project}/issues/
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.

UpdateIssueRequest

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

Issue.ApprovalStatus

The overall approval status for the issue.

Name	Number	Description
APPROVAL_STATUS_UNSPECIFIED	0	Unspecified approval status.
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.

Issue.Approver.Status

The approval status of an approver.

Name	Number	Description
STATUS_UNSPECIFIED	0	Unspecified status.
PENDING	1	Awaiting approval.
APPROVED	2	Approved.
REJECTED	3	Rejected.

Issue.Type

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.
DATABASE_EXPORT	3	Database data export request.
ACCESS_GRANT	4	Temporary access grant request.

IssueComment.Approval.Status

Approval status values.

Name	Number	Description
STATUS_UNSPECIFIED	0	Unspecified status.
PENDING	1	Approval pending.
APPROVED	2	Approved.
REJECTED	3	Rejected.

IssueStatus

The status of an issue.

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.

IssueService

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)

Top

v1/setting_service.proto

AISetting

Field	Type	Label	Description
enabled	bool
provider	AISetting.Provider
endpoint	string
api_key	string
model	string
version	string

Algorithm

Field	Type	Label	Description
full_mask	Algorithm.FullMask
range_mask	Algorithm.RangeMask
md5_mask	Algorithm.MD5Mask
inner_outer_mask	Algorithm.InnerOuterMask

Algorithm.FullMask

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.

Algorithm.InnerOuterMask

Field	Type	Label	Description
prefix_len	int32
suffix_len	int32
type	Algorithm.InnerOuterMask.MaskType
substitution	string

Algorithm.MD5Mask

Field	Type	Label	Description
salt	string		salt is the salt value to generate a different hash that with the word alone.

Algorithm.RangeMask

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.

Algorithm.RangeMask.Slice

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

Announcement

Field	Type	Label	Description
level	Announcement.AlertLevel		The alert level of announcement
text	string		The text of announcement
link	string		The optional link, user can follow the link to check extra details

AppIMSetting

Field	Type	Label	Description
settings	AppIMSetting.IMSetting	repeated

AppIMSetting.DingTalk

Field	Type	Label	Description
client_id	string
client_secret	string
robot_code	string

AppIMSetting.Feishu

Field	Type	Label	Description
app_id	string
app_secret	string

AppIMSetting.IMSetting

Field	Type	Label	Description
type	WebhookType
slack	AppIMSetting.Slack
feishu	AppIMSetting.Feishu
wecom	AppIMSetting.Wecom
lark	AppIMSetting.Lark
dingtalk	AppIMSetting.DingTalk
teams	AppIMSetting.Teams
telegram	AppIMSetting.Telegram

AppIMSetting.Lark

Field	Type	Label	Description
app_id	string
app_secret	string

AppIMSetting.Slack

Field	Type	Label	Description
token	string

AppIMSetting.Teams

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.

AppIMSetting.Telegram

[Argus P1-4 M4.0] Telegram Bot API credentials.

Field	Type	Label	Description
bot_token	string
chat_id	string

AppIMSetting.Wecom

Field	Type	Label	Description
corp_id	string
agent_id	string
secret	string

DataClassificationSetting

Field	Type	Label	Description
configs	DataClassificationSetting.DataClassificationConfig	repeated

DataClassificationSetting.DataClassificationConfig

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.

DataClassificationSetting.DataClassificationConfig.ClassificationEntry

Field	Type	Label	Description
key	string
value	DataClassificationSetting.DataClassificationConfig.DataClassification

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.

DataClassificationSetting.DataClassificationConfig.Level

Field	Type	Label	Description
title	string
level	int32		The numeric level for ordering. Higher = more sensitive.

EmailSetting

Field	Type	Label	Description
from	string
from_name	string
type	EmailSetting.Type
smtp	EmailSetting.SMTPConfig

EmailSetting.SMTPConfig

Field	Type	Label	Description
host	string
port	int32
username	string
password	string
encryption	EmailSetting.SMTPConfig.Encryption
authentication	EmailSetting.SMTPConfig.Authentication

EnvironmentSetting

Field	Type	Label	Description
environments	EnvironmentSetting.Environment	repeated

EnvironmentSetting.Environment

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	string

EnvironmentSetting.Environment.TagsEntry

Field	Type	Label	Description
key	string
value	string

GetSettingRequest

The request message for getting a setting.

Field	Type	Label	Description
name	string		The resource name of the setting.

GetSettingResponse

The response message for getting a setting.

Field	Type	Label	Description
setting	Setting

ListSettingsRequest

ListSettingsResponse

Field	Type	Label	Description
settings	Setting	repeated	The settings from the specified request.

SemanticTypeSetting

Field	Type	Label	Description
types	SemanticTypeSetting.SemanticType	repeated

SemanticTypeSetting.SemanticType

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.

Setting

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.

SettingValue

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
email	EmailSetting

TestEmailSettingRequest

Field	Type	Label	Description
parent	string
email_setting	EmailSetting
to	string

TestEmailSettingResponse

Field	Type	Label	Description
success	bool
error	string

UpdateSettingRequest

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

WorkspaceApprovalSetting

Field	Type	Label	Description
rules	WorkspaceApprovalSetting.Rule	repeated

WorkspaceApprovalSetting.Rule

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 EXPORT_DATA, support: resource.environment_id, resource.project_id, resource.db_engine, resource.database_name, resource.schema_name, resource.table_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, request.unmask

For examples: resource.environment_id == "prod" && statement.affected_rows >= 100 resource.table_name.matches("sensitive_.*") && resource.db_engine == "MYSQL" | | source | WorkspaceApprovalSetting.Rule.Source | | |

WorkspaceProfileSetting

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_role_expiration	google.protobuf.Duration		The max duration for role expired.
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 to disallow password signin. (Except workspace admins)
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.
directory_sync_token	string		The token for directory sync authentication.
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.
disallow_self_approval_default	bool		[Argus P0-1] Zero-trust default: when true, every project is treated as if project.setting.allow_self_approval were false, regardless of the project value. Projects may only loosen self-approval when this flag is off. New workspaces seed this to true.

WorkspaceProfileSetting.PasswordRestriction

Field	Type	Label	Description
min_length	int32		min_length is the minimum length for password, should no less than 8.
require_number	bool		require_number requires the password must contains at least one number.
require_letter	bool		require_letter requires the password must contains at least one letter, regardless of upper case or lower case
require_uppercase_letter	bool		require_uppercase_letter requires the password must contains at least one upper case letter.
require_special_character	bool		require_special_character requires the password must contains at least one special character.
require_reset_password_for_first_login	bool		require_reset_password_for_first_login requires users to reset their password after the 1st login.
password_rotation	google.protobuf.Duration		password_rotation requires users to reset their password after the duration.

AISetting.Provider

Name	Number	Description
PROVIDER_UNSPECIFIED	0
OPEN_AI	1
CLAUDE	2
GEMINI	3
AZURE_OPENAI	4

Algorithm.InnerOuterMask.MaskType

Name	Number	Description
MASK_TYPE_UNSPECIFIED	0
INNER	1
OUTER	2

Announcement.AlertLevel

We support three levels of AlertLevel: INFO, WARNING, and ERROR.

Name	Number	Description
ALERT_LEVEL_UNSPECIFIED	0
INFO	1
WARNING	2
CRITICAL	3

DatabaseChangeMode

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.

EmailSetting.SMTPConfig.Authentication

Name	Number	Description
AUTHENTICATION_UNSPECIFIED	0
AUTHENTICATION_NONE	1
PLAIN	2
LOGIN	3
CRAM_MD5	4

EmailSetting.SMTPConfig.Encryption

Name	Number	Description
ENCRYPTION_UNSPECIFIED	0
ENCRYPTION_NONE	1
STARTTLS	2
SSL_TLS	3

EmailSetting.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
SMTP	1

Setting.SettingName

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
EMAIL	8

WorkspaceApprovalSetting.Rule.Source

Name	Number	Description
SOURCE_UNSPECIFIED	0
CHANGE_DATABASE	1
CREATE_DATABASE	2
EXPORT_DATA	3
REQUEST_ROLE	4
REQUEST_ACCESS	5

SettingService

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

Top

v1/actuator_service.proto

ActuatorInfo

System information and configuration for the Argus instance. Actuator concept is similar to the Spring Boot Actuator.

Field	Type	Label	Description
version	string		The Argus server version.
git_commit	string		The git commit hash of the build.
readonly	bool		Whether the Argus instance is running in read-only mode.
saas	bool		Whether the Argus instance is running in SaaS mode where some features cannot be edited by users.
demo	bool		Whether the Argus instance is running in demo mode.
host	string		The host address of the Argus instance.
port	string		The port number of the Argus instance.
external_url	string		The external URL where users or webhook callbacks access Argus.
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/
unlicensed_features	string	repeated	List of features that are not licensed.
docker	bool		Whether the Argus instance is running in Docker.
activated_user_count	int32		The number of activated users.
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).
restriction	Restriction
default_project	string		The default project for unassigned databases. Format: projects/
user_count_in_iam	int32		The number of users in the workspace IAM (for seat limit display).

DeleteCacheRequest

Request message for deleting cache.

GetActuatorInfoRequest

Request message for getting actuator information.

Field	Type	Label	Description
name	string		Optional. The workspace to scope the response to. Format: workspaces/{workspace} When unset, the workspace is resolved from the request context (self-hosted) or no workspace-scoped fields are returned (SaaS).

Restriction

Field	Type	Label	Description
disallow_signup	bool		Whether self-service user signup is disabled.
disallow_password_signin	bool		Whether password-based signin is disabled (except for workspace admins).
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.

ActuatorService

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 Argus instance. When name is provided (or the workspace-scoped binding is used), the response includes workspace-scoped fields for that workspace. Permissions required: None
DeleteCache	DeleteCacheRequest	.google.protobuf.Empty	Clears the system cache to force data refresh. Permissions required: None

Top

v1/ai_service.proto

AIChatMessage

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.

AIChatRequest

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.

AIChatResponse

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.

AIChatToolCall

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.

AIChatToolDefinition

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.

AIChatUsage

Token usage for a single AI provider call.

Field	Type	Label	Description
total_tokens	int32		Total tokens used by the provider call.

AIChatMessageRole

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.

AIService

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.

Top

v1/iam_policy.proto

Binding

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/
members	string	repeated	Specifies the principals requesting access for a Argus 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:
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 database full name in "instances/{instance}/databases/{database}" format, used by the "roles/sqlEditorUser" and "roles/sqlEditorReadUser" roles, support "==" operator. resource.schema_name: the schema name, used by the "roles/sqlEditorUser" and "roles/sqlEditorReadUser" roles, support "==" operator. resource.table_name: the table name, used by the "roles/sqlEditorUser" and "roles/sqlEditorReadUser" roles, 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}").

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

BindingDelta

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.

GetIamPolicyRequest

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/

IamPolicy

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. If an etag is provided and does not match the current etag of the policy, the call will be blocked and an ABORTED error will be returned.

PolicyDelta

Describes changes between two IAM policies.

Field	Type	Label	Description
binding_deltas	BindingDelta	repeated	The delta for Bindings between two policies.

SetIamPolicyRequest

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/
policy	IamPolicy
etag	string		The current etag of the policy.

BindingDelta.Action

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.

Top

v1/audit_log_service.proto

AuditData

Additional audit data specific to certain operations.

Field	Type	Label	Description
policy_delta	PolicyDelta		Changes to IAM policies.

AuditLog

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/
create_time	google.protobuf.Timestamp		The timestamp when the audit log was created.
user	string		The user who performed the action. Format: users/
method	string		The method or action being audited. For example: /argus.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.

ExportAuditLogsRequest

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.

ExportAuditLogsResponse

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.

RequestMetadata

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.

SearchAuditLogsRequest

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, should start with "/argus.v1." prefix. For example "/argus.v1.UserService/CreateUser". Support "==" operator. - severity: support "==" operator, check Severity enum in AuditLog message for values. - user: the actor, in "users/{login_id}" format (Identity Model L2), support "==" operator. - create_time: support ">=" and "<=" operator.

For example: - filter = "method == '/argus.v1.SQLService/Query'" - filter = "method == '/argus.v1.SQLService/Query' && severity == 'ERROR'" - filter = "method == '/argus.v1.SQLService/Query' && severity == 'ERROR' && user == 'users/alice'" - filter = "method == '/argus.v1.SQLService/Query' && severity == 'ERROR' && create_time <= '2021-01-01T00:00:00Z' && create_time >= '2020-01-01T00:00:00Z'" | | 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. |

SearchAuditLogsResponse

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.

AuditLog.Severity

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

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

Top

v1/user_service.proto

BatchGetUsersRequest

Field	Type	Label	Description
names	string	repeated	The user names to retrieve. Format: users/

BatchGetUsersResponse

Field	Type	Label	Description
users	User	repeated	The users from the specified request.

CreateUserRequest

Field	Type	Label	Description
user	User		The user to create.

DeleteUserRequest

Field	Type	Label	Description
name	string		The name of the user to delete. Format: users/

GetUserRequest

Field	Type	Label	Description
name	string		The name of the user to retrieve. Format: users/

ListUsersRequest

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

ListUsersResponse

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.

UndeleteUserRequest

Field	Type	Label	Description
name	string		The name of the deleted user. Format: users/

UpdateEmailRequest

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.
email	string		The new email address.

UpdateUserRequest

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. | | otp_code | string | optional | The otp_code is used to verify the user's identity by MFA. | | regenerate_temp_mfa_secret | bool | | The regenerate_temp_mfa_secret flag means to regenerate temporary MFA secret for user. This is used for MFA setup. The temporary MFA secret and recovery codes will be returned in the response. | | regenerate_recovery_codes | bool | | The regenerate_recovery_codes flag means to regenerate recovery codes for user. | | 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. |

User

Field	Type	Label	Description
name	string		The name of the user. Format: users/
state	State		The lifecycle state of the user account.
email	string		The email address of the user, used for notifications. Identity Model L2 (P0-AUTH-6): contact-only; may be empty for principals created without an email claim (Mode B contractors / IdP JIT).
login_id	string		login_id is the principal's primary identifier under Identity Model L2 (P0-AUTH-6). Lower-cased; allowed chars [a-z0-9._@-]; max 256. Settable on CreateUser; ignored on UpdateUser (login_id is permanent after creation — rotate via DeleteUser + CreateUser if needed).
password	string		The password for authentication. Only used during user creation or password updates.
service_key	string		The service key for service account authentication.
mfa_enabled	bool		The mfa_enabled flag means if the user has enabled MFA.
temp_otp_secret	string		Temporary OTP secret used during MFA setup and regeneration.
temp_recovery_codes	string	repeated	Temporary recovery codes used during MFA setup and regeneration.
temp_otp_secret_created_time	google.protobuf.Timestamp		Timestamp when temp_otp_secret was created. Used by frontend to show countdown timer.
profile	User.Profile		User profile metadata.
groups	string	repeated	The groups for the user. Format: groups/
workspace	string		The current workspace. Format: workspaces/

User.Profile

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.
account_locked	bool		P1-AUTH-9: account_locked is true when the account is currently locked due to too many failed password attempts. Read-only when retrieved; set to false via UpdateUser update_mask "profile.account_locked" to manually unlock the account (admin only).
idp_only	bool		P1-AUTH-1/10: idp_only marks users that MUST authenticate through an external IdP (SSO). When true, the password-login path is blocked. Toggled by admins via UpdateUser update_mask "profile.idp_only". Automatically set to true for JIT-provisioned SSO users.

UserService

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

Top

v1/auth_service.proto

ExchangeTokenRequest

Field	Type	Label	Description
token	string		External OIDC token (JWT) from CI/CD platform.
email	string		Workload Identity email for identifying which identity to authenticate as. Format: {name}@workload.bytebase.com

ExchangeTokenResponse

Field	Type	Label	Description
access_token	string		Argus access token.

IdentityProviderContext

Context for identity provider authentication.

Field	Type	Label	Description
oauth2_context	OAuth2IdentityProviderContext		OAuth2 authentication context.
oidc_context	OIDCIdentityProviderContext		OpenID Connect authentication context.

LoginRequest

Field	Type	Label	Description
email	string		User's email address. DEPRECATED for password login: prefer login_id (Identity Model L2, P0-AUTH-5D, docs/modules/auth-internal-deployment.md §3.0.3). Still used as the fallback identifier for clients that haven't been updated and as the pairing key for email_code passwordless login.
password	string		User's password for authentication.
login_id	string		login_id is the principal's primary identifier under Identity Model L2 (Argus internal, P0-AUTH-5). When non-empty it takes precedence over email for password login. SSO login resolves login_id from the IdP identifier — this field is unused on that path.
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_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/

LoginResponse

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.
require_mfa_enrollment	bool		Whether the user must enrol TOTP before continuing (P0-AUTH-12). Mirrors require_reset_password's pattern: an access token is still issued so the user can reach /2fa/setup and call UpdateUser on themselves, but the frontend router force-redirects to the enrollment page until mfa_enabled flips true. Triggered when the workspace require_mfa setting is true OR when the user holds workspaceAdmin (hardcoded guardrail per A3 v1.2).

LogoutRequest

Request to logout current user session.

OAuth2IdentityProviderContext

OAuth2 authentication context.

Field	Type	Label	Description
code	string		Authorization code from OAuth2 provider.

OIDCIdentityProviderContext

OpenID Connect authentication context.

Field	Type	Label	Description
code	string		Authorization code from OIDC provider.

RefreshRequest

Request to refresh the access token.

RefreshResponse

Response from refreshing the access token.

RequestPasswordResetRequest

Field	Type	Label	Description
email	string		The email address of the account to reset.
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/

ResetPasswordRequest

Field	Type	Label	Description
email	string		The email address of the account.
code	string		The 6-digit code from the reset email.
new_password	string		The new password to set.

SendEmailLoginCodeRequest

Field	Type	Label	Description
email	string		The email address to send the code to.
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/

SignupRequest

Field	Type	Label	Description
email	string		The email for the new account. Identity Model L2 (P0-AUTH-6): becomes optional contact info; clients should send login_id as the primary identifier. Empty stays NULL on the principal row. Pre-existing clients that send only email continue to work — the backend mirrors it into login_id (see auth_service.go).
password	string		The password for the new account.
title	string		The display name of the user.
login_id	string		login_id is the principal's primary identifier (Identity Model L2, P0-AUTH-6). Lower-cased; allowed chars [a-z0-9._@-]; max 256. When empty, the backend falls back to mirroring email.

SwitchWorkspaceRequest

Field	Type	Label	Description
workspace	string		The target workspace to switch to. Format: workspaces/
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

AuthService handles user authentication operations.

Method Name	Request Type	Response Type	Description
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 Argus 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. 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. Permissions required: None

Top

v1/cel_service.proto

BatchDeparseRequest

Request message for batch deparsing CEL expressions.

Field	Type	Label	Description
expressions	google.api.expr.v1alpha1.Expr	repeated	The CEL expression ASTs to deparse.

BatchDeparseResponse

Response message for batch deparsing CEL expressions.

Field	Type	Label	Description
expressions	string	repeated	The deparsed CEL expressions as strings.

BatchParseRequest

Request message for batch parsing CEL expressions.

Field	Type	Label	Description
expressions	string	repeated	The CEL expression strings to parse.

BatchParseResponse

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

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

Top

v1/database_catalog_service.proto

ColumnCatalog

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.

ColumnCatalog.LabelsEntry

Field	Type	Label	Description
key	string
value	string

DatabaseCatalog

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
schemas	SchemaCatalog	repeated	The schemas in the database.

GetDatabaseCatalogRequest

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

ObjectSchema

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.

ObjectSchema.ArrayKind

Array type with element schema.

Field	Type	Label	Description
kind	ObjectSchema		The schema of array elements.

ObjectSchema.StructKind

Structure type with named properties.

Field	Type	Label	Description
properties	ObjectSchema.StructKind.PropertiesEntry	repeated	Properties of the struct.

ObjectSchema.StructKind.PropertiesEntry

Field	Type	Label	Description
key	string
value	ObjectSchema

SchemaCatalog

Schema metadata within a database.

Field	Type	Label	Description
name	string		The schema name.
tables	TableCatalog	repeated	The tables in the schema.

TableCatalog

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.

TableCatalog.Columns

Column list for regular tables.

Field	Type	Label	Description
columns	ColumnCatalog	repeated	The columns in the table.

UpdateDatabaseCatalogRequest

Request message for updating a database catalog.

Field	Type	Label	Description
catalog	DatabaseCatalog		The database catalog to update.

The catalog's name field is used to identify the database catalog to update. Format: instances/{instance}/databases/{database}/catalog | | allow_missing | bool | | If set to true, and the database catalog is not found, a new database catalog will be created. In this situation, update_mask is ignored. |

ObjectSchema.Type

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

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

Top

v1/database_group_service.proto

CreateDatabaseGroupRequest

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

DatabaseGroup

A group of databases matched by expressions.

Field	Type	Label	Description
name	string		The name of the database group. Format: projects/{project}/databaseGroups/
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. |

DatabaseGroup.Database

A database within a database group.

Field	Type	Label	Description
name	string		The resource name of the database. Format: instances/{instance}/databases/

DeleteDatabaseGroupRequest

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/

GetDatabaseGroupRequest

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/
view	DatabaseGroupView		The view to return. Defaults to DATABASE_GROUP_VIEW_BASIC.

ListDatabaseGroupsRequest

Request message for listing database groups.

Field	Type	Label	Description
parent	string		The parent resource whose database groups are to be listed. Format: projects/
view	DatabaseGroupView		The view to return. Defaults to DATABASE_GROUP_VIEW_BASIC.

ListDatabaseGroupsResponse

Response message for listing database groups.

Field	Type	Label	Description
database_groups	DatabaseGroup	repeated	The database groups from the specified request.

UpdateDatabaseGroupRequest

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

DatabaseGroupView

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

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

Top

v1/instance_role_service.proto

InstanceRole

InstanceRole is the API message for instance role.

Field	Type	Label	Description
name	string		The name of the role. Format: 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

ListInstanceRolesRequest

Field	Type	Label	Description
parent	string		The parent, which owns this collection of roles. Format: instances/
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. |

ListInstanceRolesResponse

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

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

Top

v1/instance_service.proto

AddDataSourceRequest

Field	Type	Label	Description
name	string		The name of the instance to add a data source to. Format: instances/
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.

BatchSyncInstancesRequest

Field	Type	Label	Description
requests	SyncInstanceRequest	repeated	The request message specifying the instances to sync. A maximum of 1000 instances can be synced in a batch.

BatchSyncInstancesResponse

BatchUpdateInstancesRequest

Field	Type	Label	Description
requests	UpdateInstanceRequest	repeated	The request message specifying the resources to update.

BatchUpdateInstancesResponse

Field	Type	Label	Description
instances	Instance	repeated

CreateInstanceRequest

Field	Type	Label	Description
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. |

DataSource

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
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
cluster	string		Cluster is the cluster name for the data source. Used by CockroachDB.
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

DataSource.AWSCredential

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

DataSource.Address

Field	Type	Label	Description
host	string
port	string

DataSource.AzureCredential

Field	Type	Label	Description
tenant_id	string
client_id	string
client_secret	string

DataSource.ExtraConnectionParametersEntry

Field	Type	Label	Description
key	string
value	string

DataSource.GCPCredential

Field	Type	Label	Description
content	string

DataSourceExternalSecret

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

DataSourceExternalSecret.AppRoleAuthOption

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.

DeleteInstanceRequest

Field	Type	Label	Description
name	string		The name of the instance to delete. Format: instances/
force	bool		If set to true, any databases and sheets from this project will also be moved to default project, and all open issues will be closed.
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.

GetInstanceRequest

Field	Type	Label	Description
name	string		The name of the instance to retrieve. Format: instances/

Instance

Field	Type	Label	Description
name	string		The name of the instance. Format: instances/
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.
roles	InstanceRole	repeated	Database roles available in this instance.
sync_interval	google.protobuf.Duration		How often the instance is synced.
sync_databases	string	repeated	Enable sync for following databases. Default empty, 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" }

Instance.LabelsEntry

Field	Type	Label	Description
key	string
value	string

InstanceResource

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.
name	string		The name of the instance. Format: instances/
environment	string	optional	The environment resource. Format: environments/prod where prod is the environment resource ID.

KerberosConfig

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

ListInstanceDatabaseRequest

Field	Type	Label	Description
name	string		The name of the instance. Format: instances/
instance	Instance	optional	The target instance. We need to set this field if the target instance is not created yet.

ListInstanceDatabaseResponse

Field	Type	Label	Description
databases	string	repeated	All database name list in the instance.

ListInstancesRequest

Field	Type	Label	Description
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" |

ListInstancesResponse

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.

RemoveDataSourceRequest

Field	Type	Label	Description
name	string		The name of the instance to remove a data source from. Format: instances/
data_source	DataSource		Identified by data source ID. Only READ_ONLY data source can be removed.

SASLConfig

Field	Type	Label	Description
krb_config	KerberosConfig		Kerberos authentication configuration.

SyncInstanceRequest

Field	Type	Label	Description
name	string		The name of instance. Format: instances/
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.

SyncInstanceResponse

Field	Type	Label	Description
databases	string	repeated	All database name list in the instance.

UndeleteInstanceRequest

Field	Type	Label	Description
name	string		The name of the deleted instance. Format: instances/

UpdateDataSourceRequest

Field	Type	Label	Description
name	string		The name of the instance to update a data source. Format: instances/
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.

UpdateInstanceRequest

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

DataSource.AuthenticationType

Name	Number	Description
AUTHENTICATION_UNSPECIFIED	0
PASSWORD	1
GOOGLE_CLOUD_SQL_IAM	2
AWS_RDS_IAM	3
AZURE_IAM	4

DataSource.RedisType

Name	Number	Description
REDIS_TYPE_UNSPECIFIED	0
STANDALONE	1
SENTINEL	2
CLUSTER	3

DataSourceExternalSecret.AppRoleAuthOption.SecretType

Name	Number	Description
SECRET_TYPE_UNSPECIFIED	0	Unspecified secret type.
PLAIN	1	Plain text secret.
ENVIRONMENT	2	Secret from environment variable.

DataSourceExternalSecret.AuthType

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

DataSourceExternalSecret.SecretType

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

DataSourceType

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

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 all database instances. Permissions required: bb.instances.list
CreateInstance	CreateInstanceRequest	Instance	Creates a new database instance. 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. Permissions required: bb.instances.delete
UndeleteInstance	UndeleteInstanceRequest	Instance	Restores a soft-deleted database instance. 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

Top

v1/database_service.proto

BatchGetDatabasesRequest

Field	Type	Label	Description
parent	string		The parent resource shared by all databases being retrieved. - projects/{project}: batch get databases in a project; - instances/{instances}: batch get databases in a instance; Use "-" as wildcard to batch get databases across parent.
names	string	repeated	The list of database names to retrieve.

BatchGetDatabasesResponse

Field	Type	Label	Description
databases	Database	repeated	The databases from the specified request.

BatchSyncDatabasesRequest

Field	Type	Label	Description
parent	string		The parent resource shared by all databases being updated. Format: 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.

BatchSyncDatabasesResponse

BatchUpdateDatabasesRequest

Field	Type	Label	Description
parent	string		The parent resource shared by all databases being updated. Format: 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.

BatchUpdateDatabasesResponse

Field	Type	Label	Description
databases	Database	repeated	Databases updated.

BoundingBox

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

Changelog

Field	Type	Label	Description
name	string		Format: instances/{instance}/databases/{database}/changelogs/
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/
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.

CheckConstraintMetadata

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

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

Database

Field	Type	Label	Description
name	string		The name of the database. Format: 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/
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.

Database.LabelsEntry

Field	Type	Label	Description
key	string
value	string

DatabaseMetadata

DatabaseMetadata is the metadata for databases.

Field	Type	Label	Description
name	string		The database metadata name.

Format: 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

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

DatabaseSchema is the metadata for databases.

Field	Type	Label	Description
schema	string		The schema dump from database.

DependencyColumn

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.

DependencyTable

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.

DiffSchemaRequest

Field	Type	Label	Description
name	string		The name of the database or changelog. Format: database: instances/{instance}/databases/{database} changelog: instances/{instance}/databases/{database}/changelogs/
schema	string		The target schema.
changelog	string		The resource name of the changelog Format: instances/{instance}/databases/{database}/changelogs/

DiffSchemaResponse

Field	Type	Label	Description
diff	string

DimensionConstraint

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

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

EnumTypeMetadata

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.

EventMetadata

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

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.

ExternalTableMetadata

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

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

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

GenerationMetadata

Field	Type	Label	Description
type	GenerationMetadata.Type
expression	string

GetChangelogRequest

Field	Type	Label	Description
name	string		The name of the changelog to retrieve. Format: instances/{instance}/databases/{database}/changelogs/
view	ChangelogView

GetDatabaseMetadataRequest

Field	Type	Label	Description
name	string		The name of the database to retrieve metadata. Format: 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. |

GetDatabaseRequest

Field	Type	Label	Description
name	string		The name of the database to retrieve. Format: instances/{instance}/databases/

GetDatabaseSDLSchemaRequest

Field	Type	Label	Description
name	string		The name of the database to retrieve SDL schema. Format: instances/{instance}/databases/{database}/sdlSchema
format	GetDatabaseSDLSchemaRequest.SDLFormat		The format of the SDL schema output.

GetDatabaseSchemaRequest

Field	Type	Label	Description
name	string		The name of the database to retrieve schema. Format: instances/{instance}/databases/{database}/schema

GetSchemaStringRequest

Field	Type	Label	Description
name	string		The name of the database. Format: instances/{instance}/databases/
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.

GetSchemaStringResponse

Field	Type	Label	Description
schema_string	string

GridLevel

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

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

ListChangelogsRequest

Field	Type	Label	Description
parent	string		The parent of the changelogs. Format: instances/{instance}/databases/
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. - create_time: the changelog create time in "2006-01-02T15:04:05Z07:00" format, support ">=" or "<=" operator.

Example: status == "DONE" status == "FAILED" && type == "SDL" create_time >= "2024-01-01T00:00:00Z" && create_time <= "2024-01-02T00:00:00Z" |

ListChangelogsResponse

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.

ListDatabasesRequest

Field	Type	Label	Description
parent	string		- projects/{project}: list databases in a project, require "bb.projects.get" permission. - workspaces/{id}: list databases in the workspace, require "bb.databases.list" permission. - instances/{instances}: list databases in a 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}" 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}" 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" |

ListDatabasesResponse

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

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

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

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

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.

SequenceMetadata

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

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

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

StreamMetadata

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.

SyncDatabaseRequest

Field	Type	Label	Description
name	string		The name of the database to sync. Format: instances/{instance}/databases/

SyncDatabaseResponse

TableMetadata

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

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

TaskMetadata

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

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)

TriggerMetadata

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.

UpdateDatabaseRequest

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} | | update_mask | google.protobuf.FieldMask | | The list of fields to update. | | allow_missing | bool | | If set to true, and the database is not found, a new database will be created. In this situation, update_mask is ignored. |

ViewMetadata

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

Changelog.Status

Name	Number	Description
STATUS_UNSPECIFIED	0
PENDING	1
DONE	2
FAILED	3

ChangelogView

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

ColumnMetadata.IdentityGeneration

Name	Number	Description
IDENTITY_GENERATION_UNSPECIFIED	0
ALWAYS	1
BY_DEFAULT	2

GenerationMetadata.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
VIRTUAL	1
STORED	2

GetDatabaseSDLSchemaRequest.SDLFormat

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

GetSchemaStringRequest.ObjectType

Name	Number	Description
OBJECT_TYPE_UNSPECIFIED	0
DATABASE	1
SCHEMA	2
TABLE	3
VIEW	4
MATERIALIZED_VIEW	5
FUNCTION	6
PROCEDURE	7
SEQUENCE	8

StreamMetadata.Mode

Name	Number	Description
MODE_UNSPECIFIED	0
DEFAULT	1
APPEND_ONLY	2
INSERT_ONLY	3

StreamMetadata.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
DELTA	1

SyncStatus

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.

TablePartitionMetadata.Type

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

TaskMetadata.State

Name	Number	Description
STATE_UNSPECIFIED	0
STARTED	1
SUSPENDED	2

DatabaseService

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. Permissions required: bb.databases.get
ListDatabases	ListDatabasesRequest	ListDatabasesResponse	Lists databases in a project, instance, or workspace. Permissions required: bb.projects.get (for project parent), bb.databases.list (for workspace parent), or bb.instances.get (for instance parent)
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
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
GetSchemaString	GetSchemaStringRequest	GetSchemaStringResponse	Generates schema DDL for a database object. Permissions required: bb.databases.getSchema

Top

v1/group_service.proto

BatchGetGroupsRequest

Request message for batch getting groups.

Field	Type	Label	Description
names	string	repeated	The group names to retrieve. Format: groups/

BatchGetGroupsResponse

Response message for batch getting groups.

Field	Type	Label	Description
groups	Group	repeated	The groups from the specified request.

CreateGroupRequest

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.

DeleteGroupRequest

Request message for deleting a group.

Field	Type	Label	Description
name	string		The name of the group to delete. Format: groups/

GetGroupRequest

Request message for getting a group.

Field	Type	Label	Description
name	string		The name of the group to retrieve. Format: groups/

Group

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).
email	string		The unique email for the group.

GroupMember

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

ListGroupsRequest

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

ListGroupsResponse

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.

UpdateGroupRequest

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

GroupMember.Role

The role of a group member.

Name	Number	Description
ROLE_UNSPECIFIED	0	Unspecified role.
OWNER	1	Group owner.
MEMBER	2	Group member.

GroupService

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

Top

v1/idp_service.proto

CreateIdentityProviderRequest

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

DeleteIdentityProviderRequest

Field	Type	Label	Description
name	string		The name of the identity provider to delete. Format: idps/

FieldMapping

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/

GetIdentityProviderRequest

Field	Type	Label	Description
name	string		The name of the identity provider to retrieve. Format: idps/

IdentityProvider

Field	Type	Label	Description
name	string		The name of the identity provider. Format: idps/
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.

IdentityProviderConfig

Field	Type	Label	Description
oauth2_config	OAuth2IdentityProviderConfig		OAuth2 protocol configuration.
oidc_config	OIDCIdentityProviderConfig		OIDC protocol configuration.
ldap_config	LDAPIdentityProviderConfig		LDAP protocol configuration.

LDAPIdentityProviderConfig

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.

ListIdentityProvidersRequest

Field	Type	Label	Description
parent	string		The parent workspace whose identity providers should be listed. Format: workspaces/{workspace} When unset, the workspace is resolved from the request context.

ListIdentityProvidersResponse

Field	Type	Label	Description
identity_providers	IdentityProvider	repeated	The identity providers from the specified request.

OAuth2IdentityProviderConfig

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.

OAuth2IdentityProviderTestRequestContext

Field	Type	Label	Description
code	string		Authorize code from website.

OIDCIdentityProviderConfig

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.

OIDCIdentityProviderTestRequestContext

Field	Type	Label	Description
code	string		Authorize code from OIDC provider.

TestIdentityProviderRequest

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.

TestIdentityProviderResponse

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.

TestIdentityProviderResponse.ClaimsEntry

Field	Type	Label	Description
key	string
value	string

TestIdentityProviderResponse.UserInfoEntry

Field	Type	Label	Description
key	string
value	string

UpdateIdentityProviderRequest

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

IdentityProviderType

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.

LDAPIdentityProviderConfig.SecurityProtocol

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.

OAuth2AuthStyle

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

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 all configured identity providers (public endpoint for login page). Permissions required: None
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

Top

v1/org_policy_service.proto

CreatePolicyRequest

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. Instance resource name: instances/instance-id. Database resource name: instances/instance-id/databases/database-name.
policy	Policy		The policy to create.
type	PolicyType		The type of policy to create.

DeletePolicyRequest

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. Instance resource name: instances/instance-id. Database resource name: instances/instance-id/databases/database-name.

GetPolicyRequest

Field	Type	Label	Description
name	string		The name of the policy to retrieve. Format: {resource type}/{resource id}/policies/

ListPoliciesRequest

Field	Type	Label	Description
parent	string		The parent, which owns this collection of policies. Format: {resource type}/
policy_type	PolicyType	optional	Filter by specific policy type.
show_deleted	bool		Show deleted policies if specified.

ListPoliciesResponse

Field	Type	Label	Description
policies	Policy	repeated	The policies from the specified request.

MaskingExemptionPolicy

MaskingExemptionPolicy is the allowlist of users who can access sensitive data.

Field	Type	Label	Description
exemptions	MaskingExemptionPolicy.Exemption	repeated

MaskingExemptionPolicy.Exemption

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:
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" |

MaskingRulePolicy

Policy for configuring data masking rules.

Field	Type	Label	Description
rules	MaskingRulePolicy.MaskingRule	repeated	The list of masking rules.

MaskingRulePolicy.MaskingRule

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

Policy

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. Instance resource name: instances/instance-id. Database resource name: instances/instance-id/databases/database-name.
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
enforce	bool		Whether the policy is enforced.
resource_type	PolicyResourceType		The resource type for the policy.

QueryDataPolicy

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		workspace-level policy Disable data export in the SQL editor.
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.

RolloutPolicy

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.

TagPolicy

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}"

TagPolicy.TagsEntry

Field	Type	Label	Description
key	string
value	string

UpdatePolicyRequest

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. Instance resource name: instances/instance-id. Database resource name: instances/instance-id/databases/database-name. | | 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. |

PolicyResourceType

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.

PolicyType

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.

OrgPolicyService

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

Top

v1/rollout_service.proto

BatchCancelTaskRunsRequest

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/

BatchCancelTaskRunsResponse

BatchRunTasksRequest

Field	Type	Label	Description
parent	string		The stage name for the tasks. Format: projects/{project}/plans/{plan}/rollout/stages/
tasks	string	repeated	The tasks to run. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/
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.

BatchRunTasksResponse

BatchSkipTasksRequest

Field	Type	Label	Description
parent	string		The stage name for the tasks. Format: projects/{project}/plans/{plan}/rollout/stages/
tasks	string	repeated	The tasks to skip. Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/
reason	string		The reason for skipping the tasks.

BatchSkipTasksResponse

CreateRolloutRequest

Field	Type	Label	Description
parent	string		The parent plan for which this rollout will be created. Format: projects/{project}/plans/
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.

GetRolloutRequest

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

GetTaskRunLogRequest

Field	Type	Label	Description
parent	string		Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/

GetTaskRunRequest

Field	Type	Label	Description
name	string		Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/

GetTaskRunSessionRequest

Field	Type	Label	Description
parent	string		Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/

ListRolloutsRequest

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_EXPORT"] |

ListRolloutsResponse

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.

ListTaskRunsRequest

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.

ListTaskRunsResponse

Field	Type	Label	Description
task_runs	TaskRun	repeated	The taskRuns from the specified request.

PreviewTaskRunRollbackRequest

Field	Type	Label	Description
name	string		Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/

PreviewTaskRunRollbackResponse

Field	Type	Label	Description
statement	string		The rollback SQL statement that would undo the task run.

Rollout

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

Stage

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.

Task

Field	Type	Label	Description
name	string		Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/
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} if the task is DatabaseCreate. Format: instances/{instance}/databases/
database_create	Task.DatabaseCreate
database_update	Task.DatabaseUpdate
database_data_export	Task.DatabaseDataExport
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.

Task.DatabaseCreate

Payload for creating a new database.

Field	Type	Label	Description
sheet	string		Format: projects/{project}/sheets/

Task.DatabaseDataExport

Payload for exporting database data.

Field	Type	Label	Description
sheet	string		The resource name of the sheet. Format: projects/{project}/sheets/

Task.DatabaseUpdate

Payload for updating a database schema.

Field	Type	Label	Description
sheet	string		Format: projects/{project}/sheets/
release	string		Format: projects/{project}/releases/

TaskRun

Field	Type	Label	Description
name	string		Format: projects/{project}/plans/{plan}/rollout/stages/{stage}/tasks/{task}/taskRuns/
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.
export_archive_status	TaskRun.ExportArchiveStatus		The export archive status for data export tasks.
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.

TaskRun.SchedulerInfo

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.

TaskRun.SchedulerInfo.WaitingCause

Information about why a task run is waiting.

Field	Type	Label	Description
parallel_tasks_limit	bool		Waiting due to parallel tasks limit.
maintenance_window	TaskRun.SchedulerInfo.WaitingCause.MaintenanceWindow		[Argus P0-5 G2] Waiting for the next maintenance window. The pending scheduler auto-promotes the task on the next window opening. See docs/modules/preflight-checklist.md §5.2.
emergency_pause	TaskRun.SchedulerInfo.WaitingCause.EmergencyPause		[Argus P1-4 G4] Held by the workspace emergency kill-switch. No auto-resume — an admin must Clear the pause explicitly. See docs/modules/monitoring-bridge.md §5.

TaskRun.SchedulerInfo.WaitingCause.EmergencyPause

Field	Type	Label	Description
reason	string		Free-form reason captured at pause time.
set_by	string		login_id of the admin who set the kill-switch.

TaskRun.SchedulerInfo.WaitingCause.MaintenanceWindow

Field	Type	Label	Description
rule_name	string		Rule whose window the task is waiting for.
next_window_start_unix	int64		Unix timestamp (seconds) when the next window opens.

TaskRunLog

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.

TaskRunLogEntry

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

TaskRunLogEntry.CommandExecute

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.

TaskRunLogEntry.CommandExecute.CommandResponse

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.

TaskRunLogEntry.ComputeDiff

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.

TaskRunLogEntry.DatabaseSync

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.

TaskRunLogEntry.PriorBackup

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.

TaskRunLogEntry.PriorBackup.PriorBackupDetail

Prior backup detail for rollback purposes.

Field	Type	Label	Description
items	TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item	repeated	The list of backed up tables.

TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item

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.

TaskRunLogEntry.PriorBackup.PriorBackupDetail.Item.Table

Table information.

Field	Type	Label	Description
database	string		The database information. Format: instances/{instance}/databases/
schema	string		The schema name.
table	string		The table name.

TaskRunLogEntry.ReleaseFileExecute

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

TaskRunLogEntry.RetryInfo

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.

TaskRunLogEntry.SchemaDump

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.

TaskRunLogEntry.TransactionControl

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.

TaskRunSession

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.

TaskRunSession.Postgres

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.

TaskRunSession.Postgres.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.

Task.Status

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.

Task.Type

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.
DATABASE_EXPORT	4	Database export task that exports query results or table data. Use payload DatabaseDataExport.

TaskRun.ExportArchiveStatus

Name	Number	Description
EXPORT_ARCHIVE_STATUS_UNSPECIFIED	0	Unspecified export archive status.
READY	1	Export archive is ready for download.
EXPORTED	2	Export archive has been downloaded by the user.

TaskRun.Status

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.

TaskRunLogEntry.TransactionControl.Type

Transaction control type.

Name	Number	Description
TYPE_UNSPECIFIED	0	Unspecified type.
BEGIN	1	Begin transaction.
COMMIT	2	Commit transaction.
ROLLBACK	3	Rollback transaction.

TaskRunLogEntry.Type

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.

RolloutService

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 (or issue creator for data export issues)
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 issue creator for data export issues, 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 issue creator for data export issues, or user with rollout policy role for the environment)
BatchCancelTaskRuns	BatchCancelTaskRunsRequest	BatchCancelTaskRunsResponse	Cancels multiple running task executions. Permissions required: bb.taskRuns.create (or issue creator for data export issues, 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

Top

v1/sql_service.proto

AICompletionRequest

Field	Type	Label	Description
messages	AICompletionRequest.Message	repeated

AICompletionRequest.Message

Field	Type	Label	Description
role	string
content	string

AICompletionResponse

Field	Type	Label	Description
candidates	AICompletionResponse.Candidate	repeated	candidates is used for results with multiple choices and candidates. Used for OpenAI and Gemini.

AICompletionResponse.Candidate

Field	Type	Label	Description
content	AICompletionResponse.Candidate.Content

AICompletionResponse.Candidate.Content

Field	Type	Label	Description
parts	AICompletionResponse.Candidate.Content.Part	repeated	parts is used for a result content with multiple parts.

AICompletionResponse.Candidate.Content.Part

Field	Type	Label	Description
text	string

AdminExecuteRequest

Field	Type	Label	Description
name	string		The name is the instance name to execute the query against. Format: instances/{instance}/databases/
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.

AdminExecuteResponse

Field	Type	Label	Description
results	QueryResult	repeated	The query results.

Advice

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.

DiffMetadataRequest

Field	Type	Label	Description
source_metadata	DatabaseMetadata		The metadata of the source schema.
target_metadata	DatabaseMetadata		The metadata of the target schema.
engine	Engine		The database engine of the schema.

DiffMetadataResponse

Field	Type	Label	Description
diff	string		The diff of the metadata.

ExportRequest

Field	Type	Label	Description
name	string		The name is the resource name to execute the export against. Format: instances/{instance}/databases/{database} Format: instances/{instance} Format: projects/{project}/plans/{plan}/rollout Format: projects/{project}/plans/{plan}/rollout/stages/
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.

ExportResponse

Field	Type	Label	Description
content	bytes		The export file content.

MaskingReason

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

QueryHistory

Field	Type	Label	Description
name	string		The name for the query history. Format: projects/{project}/queryHistories/
database	string		The database name to execute the query. Format: instances/{instance}/databases/
creator	string
create_time	google.protobuf.Timestamp
statement	string
error	string	optional
duration	google.protobuf.Duration
type	QueryHistory.Type

QueryOption

Field	Type	Label	Description
redis_run_commands_on	QueryOption.RedisRunCommandsOn
mssql_explain_format	QueryOption.MSSQLExplainFormat

QueryRequest

Field	Type	Label	Description
name	string		The name is the instance name to execute the query against. Format: instances/{instance}/databases/
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.

QueryResponse

Field	Type	Label	Description
results	QueryResult	repeated	The query results.

QueryResult

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

QueryResult.CommandError

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.

QueryResult.Message

Field	Type	Label	Description
level	QueryResult.Message.Level
content	string

QueryResult.PostgresError

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

QueryResult.SyntaxError

Syntax error with position information for editor highlighting

Field	Type	Label	Description
start_position	Position		Position information for highlighting in editor

QueryRow

Field	Type	Label	Description
values	RowValue	repeated	Row values of the query result.

RowValue

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.

RowValue.Timestamp

Field	Type	Label	Description
google_timestamp	google.protobuf.Timestamp
accuracy	int32		The accuracy is the number of digits after the decimal point.

RowValue.TimestampTZ

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

SearchQueryHistoriesRequest

Field	Type	Label	Description
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}" format, support "==" operator. - instance: the instance full name in "instances/{id}" format, support "==" operator. - type: the type, should be "QUERY" or "EXPORT", support "==" operator. - statement: the SQL statement, support ".contains()" operator.

For example: project == "projects/{project}" database == "instances/{instance}/databases/{database}" instance == "instances/{instance}" type == "QUERY" type == "EXPORT" statement.contains("select") type == "QUERY" && statement.contains("select") |

SearchQueryHistoriesResponse

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.

Advice.Level

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.

Advice.RuleType

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.

QueryHistory.Type

Name	Number	Description
TYPE_UNSPECIFIED	0	Unspecified query history type.
QUERY	1	Query execution for data retrieval.
EXPORT	2	Data export operation to file.

QueryOption.MSSQLExplainFormat

Name	Number	Description
MSSQL_EXPLAIN_FORMAT_UNSPECIFIED	0	defaults to SHOWPLAN_ALL
MSSQL_EXPLAIN_FORMAT_ALL	1	SHOWPLAN_ALL
MSSQL_EXPLAIN_FORMAT_XML	2	SHOWPLAN_XML

QueryOption.RedisRunCommandsOn

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.

QueryResult.CommandError.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
DDL	1
DML	2
NON_READ_ONLY	3

QueryResult.Message.Level

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

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	SearchQueryHistories searches query histories for the caller. Permissions required: None (only returns caller's own query histories)
Export	ExportRequest	ExportResponse	Exports query results to a file format. Permissions required: bb.databases.get
DiffMetadata	DiffMetadataRequest	DiffMetadataResponse	Computes schema differences between two database metadata. Permissions required: None
AICompletion	AICompletionRequest	AICompletionResponse	Provides AI-powered SQL completion and generation. Permissions required: None (authenticated users only, requires AI to be enabled)

Top

v1/plan_service.proto

CancelPlanCheckRunRequest

Field	Type	Label	Description
name	string		The name of the plan check run to cancel. Format: projects/{project}/plans/{plan}/planCheckRun

CancelPlanCheckRunResponse

CreatePlanRequest

Field	Type	Label	Description
parent	string		The parent project where this plan will be created. Format: projects/
plan	Plan		The plan to create.

GetPlanCheckRunRequest

Field	Type	Label	Description
name	string		The name of the plan check run to retrieve. Format: projects/{project}/plans/{plan}/planCheckRun

GetPlanRequest

Field	Type	Label	Description
name	string		The name of the plan to retrieve. Format: projects/{project}/plans/

ListPlansRequest

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". - has_issue: the plan has issue or not, 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", "change_database_config", or "export_data_config". - state: the plan state, support "==" operator, the value should be "ACTIVE" or "DELETED".

For example: creator == "users/ed@bytebase.com" && create_time >= "2025-01-02T15:04:05Z07:00" has_rollout == false && has_issue == true title == "My Plan" title.contains("database migration") spec_type == "change_database_config" state == "ACTIVE" |

ListPlansResponse

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.

Plan

Field	Type	Label	Description
name	string		The name of the plan. plan is a system generated ID. Format: projects/{project}/plans/
state	State		The state of the plan.
issue	string		The issue associated with the plan. Can be empty. Format: projects/{project}/issues/
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	Issue.ApprovalStatus		The approval status of the linked issue. Unspecified when no linked issue exists.
rollout_stage_summaries	Plan.RolloutStageSummary	repeated	Per-stage rollout status summary. Ordered by environment deployment order. Empty when no rollout exists.

Plan.ChangeDatabaseConfig

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/
release	string		The resource name of the release. Format: projects/{project}/releases/
enable_prior_backup	bool		If set, a backup of the modified data will be created automatically before any changes are applied.
rollback_sheet	string	optional	[Argus P0-5 G1] The resource name of the rollback SQL sheet. Format: projects/{project}/sheets/{sheet} Optional. The PRE_FLIGHT plan check requires this for DDL and DML changes; missing rollback sheet on such changes produces an ERROR result that blocks issue approval. See docs/modules/preflight-checklist.md §4.

Plan.CreateDatabaseConfig

Field	Type	Label	Description
target	string		The resource name of the instance on which the database is created. Format: instances/
database	string		The name of the database to create.
table	string		table is the name of the table, if it is not empty, Argus 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.

Plan.ExportDataConfig

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/
format	ExportFormat		The format of the exported file.
password	string	optional	The zip password provide by users. Leave it empty if no needs to encrypt the zip file.

Plan.PlanCheckRunStatusCountEntry

Field	Type	Label	Description
key	string
value	int32

Plan.RolloutStageSummary

Field	Type	Label	Description
stage	string		The stage resource name. Format: projects/{project}/plans/{plan}/rollout/stages/
task_status_counts	Plan.TaskStatusCount	repeated	Task status counts for this stage.

Plan.Spec

Field	Type	Label	Description
id	string		A UUID4 string that uniquely identifies the Spec.
create_database_config	Plan.CreateDatabaseConfig
change_database_config	Plan.ChangeDatabaseConfig
export_data_config	Plan.ExportDataConfig

Plan.TaskStatusCount

Field	Type	Label	Description
status	Task.Status		The task status.
count	int32		The number of tasks in the status.

PlanCheckRun

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

PlanCheckRun.Result

Field	Type	Label	Description
status	Advice.Level
title	string
content	string
code	int32
target	string		Target identification for consolidated results. Format: instances/{instance}/databases/
type	PlanCheckRun.Result.Type
sql_summary_report	PlanCheckRun.Result.SqlSummaryReport
sql_review_report	PlanCheckRun.Result.SqlReviewReport

PlanCheckRun.Result.SqlReviewReport

Field	Type	Label	Description
start_position	Position		Position of the SQL statement.
end_position	Position

PlanCheckRun.Result.SqlSummaryReport

Field	Type	Label	Description
statement_types	StatementType	repeated	statement_types are the types of statements that are found in the sql.
affected_rows	int64

RunPlanChecksRequest

Field	Type	Label	Description
name	string		The plan to run plan checks. Format: projects/{project}/plans/
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.

RunPlanChecksResponse

UpdatePlanRequest

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

PlanCheckRun.Result.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
STATEMENT_ADVISE	1
STATEMENT_SUMMARY_REPORT	2
GHOST_SYNC	3
PRE_FLIGHT	4	[Argus P0-5] Pre-flight checklist result. Mirrors store.PlanCheckType.PLAN_CHECK_TYPE_PRE_FLIGHT — kept in sync by backend/api/v1 convertPlanCheckRunResultType (see docs/modules/preflight-checklist.md §7).

PlanCheckRun.Status

Name	Number	Description
STATUS_UNSPECIFIED	0
RUNNING	1
DONE	2
FAILED	3
CANCELED	4

PlanService

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

Top

v1/project_service.proto

Activity

Activity types for webhook notifications.

AddWebhookRequest

Field	Type	Label	Description
project	string		The name of the project to add the webhook to. Format: projects/
webhook	Webhook		The webhook to add.

BatchDeleteProjectsRequest

Field	Type	Label	Description
names	string	repeated	The names of the projects to delete. Format: projects/
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.

BatchGetProjectsRequest

Field	Type	Label	Description
names	string	repeated	The names of projects to retrieve. Format: projects/

BatchGetProjectsResponse

Field	Type	Label	Description
projects	Project	repeated	The projects from the specified request.

CreateProjectRequest

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]-/. |

DeleteProjectRequest

Field	Type	Label	Description
name	string		The name of the project to delete. Format: projects/
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.

GetProjectRequest

Field	Type	Label	Description
name	string		The name of the project to retrieve. Format: projects/

Label

A label for categorizing and organizing issues.

Field	Type	Label	Description
value	string		The label value/name.
color	string		The color code for the label (e.g., hex color).
group	string		The group this label belongs to.

ListProjectsRequest

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

ListProjectsResponse

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.

Project

Field	Type	Label	Description
name	string		The name of the project. Format: projects/
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 Argus.
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 database rows to sample during CI data validation. 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.

Project.ExecutionRetryPolicy

Execution retry policy configuration.

Field	Type	Label	Description
maximum_retries	int32		The maximum number of retries for lock timeout errors.

Project.LabelsEntry

Field	Type	Label	Description
key	string
value	string

RemoveWebhookRequest

Field	Type	Label	Description
webhook	Webhook		The webhook to remove. Identified by its url.

SearchProjectsRequest

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

SearchProjectsResponse

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.

TestWebhookRequest

Field	Type	Label	Description
project	string		The name of the project which owns the webhook to test. Format: projects/
webhook	Webhook		The webhook to test. Identified by its url.

TestWebhookResponse

Field	Type	Label	Description
error	string		The result of the test, empty if the test is successful.

UndeleteProjectRequest

Field	Type	Label	Description
name	string		The name of the deleted project. Format: projects/

UpdateProjectRequest

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

UpdateWebhookRequest

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.

Webhook

Field	Type	Label	Description
name	string		name is the name of the webhook, generated by the server. format: projects/{project}/webhooks/
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.
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. Argus 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

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.
ISSUE_REJECTED	16	[Argus P0-1 M3] ISSUE_REJECTED represents an approver rejecting the issue. Surfaces on the standard webhook fan-out so second- line on-call sees red decisions in IM.

ProjectService

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. Permissions required: bb.projects.get
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

Top

v1/release_service.proto

CheckReleaseRequest

Field	Type	Label	Description
parent	string		Format: projects/
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/
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"

CheckReleaseResponse

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.

CheckReleaseResponse.CheckResult

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

CreateReleaseRequest

Field	Type	Label	Description
parent	string		Format: projects/
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".

DeleteReleaseRequest

Field	Type	Label	Description
name	string		The name of the release to delete. Format: projects/{project}/releases/

GetReleaseRequest

Field	Type	Label	Description
name	string		Format: projects/{project}/releases/

ListReleaseCategoriesRequest

Field	Type	Label	Description
parent	string		Format: projects/

ListReleaseCategoriesResponse

Field	Type	Label	Description
categories	string	repeated	The unique category values in the project.

ListReleasesRequest

Field	Type	Label	Description
parent	string		Format: projects/
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" |

ListReleasesResponse

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.

Release

Field	Type	Label	Description
name	string		Format: projects/{project}/releases/
category	string		Category extracted from release name (e.g., "webapp", "analytics"). Set by Argus 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.

Release.File

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

Release.VCSSource

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.

UndeleteReleaseRequest

Field	Type	Label	Description
name	string		The name of the deleted release. Format: projects/{project}/releases/

UpdateReleaseRequest

Field	Type	Label	Description
release	Release		The release to update.
update_mask	google.protobuf.FieldMask		The list of fields to be updated.

Release.Type

The type of schema change.

Name	Number	Description
TYPE_UNSPECIFIED	0	Unspecified type.
VERSIONED	1	Versioned schema migration.
DECLARATIVE	2	Declarative schema definition.

ReleaseService

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

Top

v1/review_config_service.proto

CreateReviewConfigRequest

Field	Type	Label	Description
review_config	ReviewConfig		The SQL review config to create.

DeleteReviewConfigRequest

Field	Type	Label	Description
name	string		The name of the SQL review config to delete. Format: reviewConfigs/

GetReviewConfigRequest

Field	Type	Label	Description
name	string		The name of the SQL review config to retrieve. Format: reviewConfigs/

ListReviewConfigsRequest

ListReviewConfigsResponse

Field	Type	Label	Description
review_configs	ReviewConfig	repeated	The SQL review configs from the specified request.

ReviewConfig

Field	Type	Label	Description
name	string		The name of the SQL review config. Format: reviewConfigs/
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.

SQLReviewRule

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.

SQLReviewRule.CommentConventionRulePayload

Field	Type	Label	Description
required	bool
max_length	int32

SQLReviewRule.NamingCaseRulePayload

Field	Type	Label	Description
upper	bool

SQLReviewRule.NamingRulePayload

Payload message types for SQL review rules

Field	Type	Label	Description
max_length	int32
format	string

SQLReviewRule.NumberRulePayload

Field	Type	Label	Description
number	int32

SQLReviewRule.StringArrayRulePayload

Field	Type	Label	Description
list	string	repeated

SQLReviewRule.StringRulePayload

Field	Type	Label	Description
value	string

UpdateReviewConfigRequest

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

SQLReviewRule.Level

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.

SQLReviewRule.Type

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_SELECT_FULL_TABLE_SCAN	32
STATEMENT_CREATE_SPECIFY_SCHEMA	33
STATEMENT_CHECK_SET_ROLE_VARIABLE	34
STATEMENT_DISALLOW_USING_FILESORT	35
STATEMENT_DISALLOW_USING_TEMPORARY	36
STATEMENT_WHERE_NO_EQUAL_NULL	37
STATEMENT_WHERE_DISALLOW_FUNCTIONS_AND_CALCULATIONS	38
STATEMENT_QUERY_MINIMUM_PLAN_LEVEL	39
STATEMENT_WHERE_MAXIMUM_LOGICAL_OPERATOR_COUNT	40
STATEMENT_MAXIMUM_LIMIT_VALUE	41
STATEMENT_MAXIMUM_JOIN_TABLE_COUNT	42
STATEMENT_MAXIMUM_STATEMENTS_IN_TRANSACTION	43
STATEMENT_JOIN_STRICT_COLUMN_ATTRS	44
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

ReviewConfigService

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

Top

v1/revision_service.proto

BatchCreateRevisionsRequest

Field	Type	Label	Description
parent	string		The parent resource shared by all revisions being created. Format: instances/{instance}/databases/
requests	CreateRevisionRequest	repeated	The request message specifying the revisions to create. A maximum of 100 revisions can be created in a batch.

BatchCreateRevisionsResponse

Field	Type	Label	Description
revisions	Revision	repeated	The created revisions.

CreateRevisionRequest

Field	Type	Label	Description
parent	string		Format: instances/{instance}/databases/
revision	Revision		The revision to create.

DeleteRevisionRequest

Field	Type	Label	Description
name	string		The name of the revision to delete. Format: instances/{instance}/databases/{database}/revisions/

GetRevisionRequest

Field	Type	Label	Description
name	string		The name of the revision. Format: instances/{instance}/databases/{database}/revisions/

ListRevisionsRequest

Field	Type	Label	Description
parent	string		The parent of the revisions. Format: instances/{instance}/databases/
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. |

ListRevisionsResponse

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.

Revision

Field	Type	Label	Description
name	string		Format: instances/{instance}/databases/{database}/revisions/
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_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/
type	Revision.Type		The type of the revision.

Revision.Type

The type of schema revision.

Name	Number	Description
TYPE_UNSPECIFIED	0	Unspecified type.
VERSIONED	1	Versioned schema migration.
DECLARATIVE	2	Declarative schema definition.

RevisionService

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

Top

v1/role_service.proto

CreateRoleRequest

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]/. |

DeleteRoleRequest

Field	Type	Label	Description
name	string		The name of the role to delete. Format: roles/

GetRoleRequest

Field	Type	Label	Description
name	string		The name of the role to retrieve. Format: roles/

ListRolesRequest

ListRolesResponse

Field	Type	Label	Description
roles	Role	repeated	The roles from the specified request.

Role

Role defines a set of permissions that can be assigned to users.

Field	Type	Label	Description
name	string		Resource name. Format: roles/
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.

UpdateRoleRequest

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.

Role.Type

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

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

Top

v1/service_account_service.proto

CreateServiceAccountRequest

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.

DeleteServiceAccountRequest

Request message for deleting a service account.

Field	Type	Label	Description
name	string		The name of the service account to delete. Format: serviceAccounts/

GetServiceAccountRequest

Request message for getting a service account.

Field	Type	Label	Description
name	string		The name of the service account to retrieve. Format: serviceAccounts/

ListServiceAccountsRequest

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

ListServiceAccountsResponse

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

ServiceAccount represents an API integration account.

Field	Type	Label	Description
name	string		The name of the service account. Format: serviceAccounts/
state	State		The state of the service account.
email	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.

UndeleteServiceAccountRequest

Request message for restoring a deleted service account.

Field	Type	Label	Description
name	string		The name of the deleted service account. Format: serviceAccounts/

UpdateServiceAccountRequest

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

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

Top

v1/sheet_service.proto

BatchCreateSheetsRequest

Field	Type	Label	Description
parent	string		The parent resource where all sheets will be created. Format: projects/
requests	CreateSheetRequest	repeated

BatchCreateSheetsResponse

Field	Type	Label	Description
sheets	Sheet	repeated

CreateSheetRequest

Field	Type	Label	Description
parent	string		The parent resource where this sheet will be created. Format: projects/
sheet	Sheet		The sheet to create.

GetSheetRequest

Field	Type	Label	Description
name	string		The name of the sheet to retrieve. Format: projects/{project}/sheets/
raw	bool		By default, the content of the sheet is cut off, set the raw to true to retrieve the full content.

Sheet

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

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

Top

v1/subscription_service.proto

CancelPurchaseRequest

CreatePurchaseRequest

Field	Type	Label	Description
plan	PlanType
interval	BillingInterval
seats	int32

GetPaymentInfoRequest

GetSubscriptionRequest

ListPurchasePlansRequest

ListPurchasePlansResponse

Field	Type	Label	Description
plans	PurchasePlan	repeated

PaymentInfo

Field	Type	Label	Description
total_price	string
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.

PlanConfig

PlanConfig represents the configuration for all plans loaded from plan.yaml

Field	Type	Label	Description
plans	PlanLimitConfig	repeated
instance_features	PlanFeature	repeated

PlanLimitConfig

PlanLimitConfig represents a single plan's configuration

Field	Type	Label	Description
type	PlanType
maximum_instance_count	int32
maximum_seat_count	int32
features	PlanFeature	repeated

PurchaseBillingMethod

Field	Type	Label	Description
interval	BillingInterval
discount	PurchaseDiscount

PurchaseDiscount

Field	Type	Label	Description
type	PurchaseDiscount.Type
value	int32

PurchasePlan

Field	Type	Label	Description
type	PlanType
self_service_purchase	bool
additionals	PurchasePlanAdditional	repeated
billing_methods	PurchaseBillingMethod	repeated

PurchasePlanAdditional

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.

PurchaseResponse

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.

Subscription

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.

UpdatePurchaseRequest

Field	Type	Label	Description
plan	PlanType
interval	BillingInterval
seats	int32
etag	string

UploadLicenseRequest

Field	Type	Label	Description
license	string

VerifyCheckoutSessionRequest

Field	Type	Label	Description
session_id	string

VerifyCheckoutSessionResponse

Field	Type	Label	Description
status	string		Stripe Checkout Session status: "complete", "expired", or "open".

BillingInterval

Name	Number	Description
BILLING_INTERVAL_UNSPECIFIED	0
MONTH	1
YEAR	2

PlanFeature

PlanFeature represents the available features in Argus

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

PlanType

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.

PurchaseDiscount.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
PERCENTAGE_OFF	1
FIXED_MONTH_OFF	2
FIXED_PRICE_OFF	3

PurchasePlanAdditional.Type

Name	Number	Description
TYPE_UNSPECIFIED	0
USER	1

SubscriptionService

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.
UploadLicense	UploadLicenseRequest	Subscription	Uploads an enterprise license (self-hosted only).
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.

Top

v1/workload_identity_service.proto

CreateWorkloadIdentityRequest

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.

DeleteWorkloadIdentityRequest

Request message for deleting a workload identity.

Field	Type	Label	Description
name	string		The name of the workload identity to delete. Format: workloadIdentities/

GetWorkloadIdentityRequest

Request message for getting a workload identity.

Field	Type	Label	Description
name	string		The name of the workload identity to retrieve. Format: workloadIdentities/

ListWorkloadIdentitiesRequest

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

ListWorkloadIdentitiesResponse

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.

UndeleteWorkloadIdentityRequest

Request message for restoring a deleted workload identity.

Field	Type	Label	Description
name	string		The name of the deleted workload identity. Format: workloadIdentities/

UpdateWorkloadIdentityRequest

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

WorkloadIdentity represents an external CI/CD workload identity.

Field	Type	Label	Description
name	string		The name of the workload identity. Format: workloadIdentities/
state	State		The state of the workload identity.
email	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

WorkloadIdentityConfig for API layer

Field	Type	Label	Description
provider_type	WorkloadIdentityConfig.ProviderType		Platform type (currently only GITHUB is supported)
issuer_url	string		OIDC Issuer URL (auto-filled based on provider_type, can be overridden)
allowed_audiences	string	repeated	Allowed audiences for token validation
subject_pattern	string		Subject pattern to match (e.g., "repo:owner/repo:ref:refs/heads/main")

WorkloadIdentityConfig.ProviderType

ProviderType identifies the CI/CD platform.

Name	Number	Description
PROVIDER_TYPE_UNSPECIFIED	0
GITHUB	1
GITLAB	2

WorkloadIdentityService

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

Top

v1/worksheet_service.proto

BatchUpdateWorksheetOrganizerRequest

Field	Type	Label	Description
requests	UpdateWorksheetOrganizerRequest	repeated

BatchUpdateWorksheetOrganizerResponse

Field	Type	Label	Description
worksheet_organizers	WorksheetOrganizer	repeated

CreateWorksheetRequest

Field	Type	Label	Description
parent	string		The parent resource where this worksheet will be created. Format: projects/
worksheet	Worksheet		The worksheet to create.

DeleteWorksheetRequest

Field	Type	Label	Description
name	string		The name of the worksheet to delete. Format: projects/{project}/worksheets/

GetWorksheetRequest

Field	Type	Label	Description
name	string		The name of the worksheet to retrieve. Format: projects/{project}/worksheets/

SearchWorksheetsRequest

Field	Type	Label	Description
parent	string		The parent resource of the worksheets. Format: projects/
filter	string		To filter the search result. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec

Supported filter: - creator: the worksheet creator in "users/{email}" format, support "==" and "!=" operator. - starred: should be "true" or "false", filter starred/unstarred sheets, support "==" operator. - visibility: check Visibility enum in the Worksheet message for values, support "==" and "in [xx]" operator.

For example: creator == "users/{email}" creator != "users/{email}" starred == true starred == false visibility in ["PRIVATE", "PROJECT_READ", "PROJECT_WRITE"] visibility == "PRIVATE" |

SearchWorksheetsResponse

Field	Type	Label	Description
worksheets	Worksheet	repeated	The worksheets that matched the search criteria.

UpdateWorksheetOrganizerRequest

Field	Type	Label	Description
organizer	WorksheetOrganizer		The organizer to update.

The organizer's worksheet field is used to identify the worksheet. Format: projects/{project}/worksheets/{worksheet} | | update_mask | google.protobuf.FieldMask | | The list of fields to be updated. Fields are specified relative to the worksheet organizer. Only support update the following fields for now: - starred | | allow_missing | bool | | If set to true, and the worksheet organizer is not found, a new worksheet organizer will be created. In this situation, update_mask is ignored. |

UpdateWorksheetRequest

Field	Type	Label	Description
worksheet	Worksheet		The worksheet to update.

The worksheet's name field is used to identify the worksheet to update. Format: projects/{project}/worksheets/{worksheet} | | update_mask | google.protobuf.FieldMask | | The list of fields to be updated. Fields are specified relative to the worksheet. (e.g., title, statement; not worksheet.title or worksheet.statement) Only support update the following fields for now: - title - statement - starred - visibility |

Worksheet

Field	Type	Label	Description
name	string		The name of the worksheet resource, generated by the server. Canonical parent is project. Format: projects/{project}/worksheets/
project	string		The project resource name. Format: projects/
database	string		The database resource name. Format: instances/{instance}/databases/{database} If the database parent doesn't exist, the database field is empty.
title	string		The title of the worksheet.
creator	string		The creator of the Worksheet. Format: users/
create_time	google.protobuf.Timestamp		The create time of the worksheet.
update_time	google.protobuf.Timestamp		The last update time of the worksheet.
content	bytes		The content of the worksheet. By default, it will be cut off in SearchWorksheet() method. If it doesn't match the content_size, you can use GetWorksheet() 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.
visibility	Worksheet.Visibility
starred	bool		starred indicates whether the worksheet is starred by the current authenticated user.
folders	string	repeated

WorksheetOrganizer

Field	Type	Label	Description
worksheet	string		The name of the worksheet. Format: projects/{project}/worksheets/
starred	bool		starred means if the worksheet is starred.
folders	string	repeated

Worksheet.Visibility

Name	Number	Description
VISIBILITY_UNSPECIFIED	0
PROJECT_READ	1	Read access in project scope, worksheet OWNER/DBA and project OWNER can read/write, other project members can read.
PROJECT_WRITE	2	Write access in project scope, worksheet OWNER/DBA and all members in the project can write the worksheet.
PRIVATE	3	Private, only worksheet OWNER can read/write.

WorksheetService

WorksheetService manages SQL worksheets for query development.

Method Name	Request Type	Response Type	Description
CreateWorksheet	CreateWorksheetRequest	Worksheet	Creates a personal worksheet used in SQL Editor. Any authenticated user can create their own worksheets. Permissions required: None (authenticated users only)
GetWorksheet	GetWorksheetRequest	Worksheet	Get a worksheet by name. The users can access this method if, - they are the creator of the worksheet; - they have bb.worksheets.get permission on the workspace; - the sheet is shared with them with PROJECT_READ and PROJECT_WRITE visibility, and they have bb.projects.get permission on the project. Permissions required: bb.worksheets.get (or creator, or project member for shared worksheets)
SearchWorksheets	SearchWorksheetsRequest	SearchWorksheetsResponse	Search for worksheets. This is used for finding my worksheets or worksheets shared by other people. The sheet accessibility is the same as GetWorksheet(). Permissions required: bb.worksheets.get (or creator, or project member for shared worksheets)
UpdateWorksheet	UpdateWorksheetRequest	Worksheet	Update a worksheet. The users can access this method if, - they are the creator of the worksheet; - they have bb.worksheets.manage permission on the workspace; - the sheet is shared with them with PROJECT_WRITE visibility, and they have bb.projects.get permission on the project. Permissions required: bb.worksheets.manage (or creator, or project member for PROJECT_WRITE worksheets)
UpdateWorksheetOrganizer	UpdateWorksheetOrganizerRequest	WorksheetOrganizer	Update the organizer of a worksheet. The access is the same as UpdateWorksheet method. Permissions required: bb.worksheets.get (or creator, or project member for shared worksheets)
BatchUpdateWorksheetOrganizer	BatchUpdateWorksheetOrganizerRequest	BatchUpdateWorksheetOrganizerResponse	Batch update the organizers of worksheets. The access is the same as UpdateWorksheet method. Permissions required: bb.worksheets.get (or creator, or project member for shared worksheets)
DeleteWorksheet	DeleteWorksheetRequest	.google.protobuf.Empty	Delete a worksheet. The access is the same as UpdateWorksheet method. Permissions required: bb.worksheets.manage (or creator, or project member for PROJECT_WRITE worksheets)

Top

v1/workspace_service.proto

GetWorkspaceRequest

Field	Type	Label	Description
name	string		The workspace name, format: workspaces/{workspace}. Use "workspaces/-" to get the current/default workspace.

ListWorkspacesRequest

ListWorkspacesResponse

Field	Type	Label	Description
workspaces	Workspace	repeated

UpdateWorkspaceRequest

Field	Type	Label	Description
workspace	Workspace
update_mask	google.protobuf.FieldMask

Workspace

Field	Type	Label	Description
name	string		Format: workspaces/
title	string
logo	string		The branding logo.

WorkspaceService

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
SetIamPolicy	SetIamPolicyRequest	IamPolicy	Sets IAM policy for the workspace. Permissions required: bb.workspaces.setIamPolicy

Scalar Value Types

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