Branch

Branch object

namestringIDImmutable: Output only. The full resource path of the branch. Format: projects/{project_id}/branches/{branch_id}

uidstringOutput only: System-generated unique ID for the branch.

parentstringOutput only

The project containing this branch (API resource hierarchy). Format: projects/{project_id}

Note: This field indicates where the branch exists in the resource hierarchy. For point-in-time branching from another branch, see status.source_branch.

create_timestringOutput only: A timestamp indicating when the branch was created.

update_timestringOutput only: A timestamp indicating when the branch was last updated.

specobjectInput only

The spec contains the branch configuration.

Show child attributesHide child attributes

source_branchstringImmutable: The name of the source branch from which this branch was created (data lineage for point-in-time recovery). If not specified, defaults to the project's default branch. Format: projects/{project_id}/branches/{branch_id}

source_branch_lsnstringImmutable: The Log Sequence Number (LSN) on the source branch from which this branch was created.

source_branch_timestringImmutable: The point in time on the source branch from which this branch was created.

is_protectedboolean: When set to true, protects the branch from deletion and reset. Associated compute endpoints and the project cannot be deleted while the branch is protected.

expire_timestring: Absolute expiration timestamp. When set, the branch will expire at this time. Mutually exclusive with ttl and no_expiry.

ttlstring: Relative time-to-live duration. When set, the branch will expire at creation_time + ttl. Mutually exclusive with expire_time and no_expiry.

no_expiryboolean: Explicitly disable expiration. When set to true, the branch will not expire. If set to false, the request is invalid; provide either ttl or expire_time instead. Mutually exclusive with expire_time and ttl.

statusobjectOutput only

The current status of a Branch.

Show child attributesHide child attributes

source_branchstringOutput only: The name of the source branch from which this branch was created. Format: projects/{project_id}/branches/{branch_id}

source_branch_lsnstringOutput only: The Log Sequence Number (LSN) on the source branch from which this branch was created.

source_branch_timestringOutput only: The point in time on the source branch from which this branch was created.

defaultbooleanOutput only: Whether the branch is the project's default branch.

is_protectedbooleanOutput only: Whether the branch is protected.

current_statestringOutput only

The branch's state, indicating if it is initializing, ready for use, or archived.

Values:

STATE_UNSPECIFIED
INIT
IMPORTING
RESETTING
READY
ARCHIVED

pending_statestringOutput only

The pending state of the branch, if a state transition is in progress.

Values:

STATE_UNSPECIFIED
INIT
IMPORTING
RESETTING
READY
ARCHIVED

state_change_timestringOutput only: A timestamp indicating when the current_state began.

logical_size_bytesint64Output only: The logical size of the branch.

expire_timestringOutput only: Absolute expiration time for the branch. Empty if expiration is disabled.

branch_idstringOutput only: Part of the resource name.

branch_idstringOutput only: The part of the name, chosen by the user when the resource was created.

View as Markdown

The Branch object

{
  "name": "string",
  "uid": "string",
  "parent": "string",
  "create_time": "string",
  "update_time": "string",
  "spec": {
    "source_branch": "string",
    "source_branch_lsn": "string",
    "source_branch_time": "string",
    "is_protected": true,
    "expire_time": "string",
    "ttl": "string",
    "no_expiry": true
  },
  "status": {
    "source_branch": "string",
    "source_branch_lsn": "string",
    "source_branch_time": "string",
    "default": true,
    "is_protected": true,
    "current_state": "INIT",
    "pending_state": "INIT",
    "state_change_time": "string",
    "logical_size_bytes": 0,
    "expire_time": "string",
    "branch_id": "string"
  },
  "branch_id": "string"
}

Get a Branch GA

GET /api/2.0/postgres/{name=projects/*/branches/*}

Retrieves information about the specified database branch.

API scopes: postgres

Parameters

namestringRequiredpath: The full resource path of the branch to retrieve. Format: projects/{project_id}/branches/{branch_id}

Response

Returns the Branch object.

View as Markdown

Response

{
  "name": "string",
  "uid": "string",
  "parent": "string",
  "create_time": "string",
  "update_time": "string",
  "status": {
    "source_branch": "string",
    "source_branch_lsn": "string",
    "source_branch_time": "string",
    "default": true,
    "is_protected": true,
    "current_state": "INIT",
    "pending_state": "INIT",
    "state_change_time": "string",
    "logical_size_bytes": 0,
    "expire_time": "string",
    "branch_id": "string"
  },
  "branch_id": "string"
}

List Branches GA

GET /api/2.0/postgres/{parent=projects/*}/branches

Returns a paginated list of database branches in the project.

API scopes: postgres

Parameters

parentstringRequiredpath: The Project that owns this collection of branches. Format: projects/{project_id}

page_tokenstringquery: Page token from a previous response. If not provided, returns the first page.

page_sizeint32query: Upper bound for items returned. Cannot be negative.

Response

Returns a list of Branch objects.

View as Markdown

Response

{
  "branches": [
    {
      "name": "string",
      "uid": "string",
      "parent": "string",
      "create_time": "string",
      "update_time": "string",
      "status": {},
      "branch_id": "string"
    }
  ],
  "next_page_token": "string"
}

Create a Branch GA

POST /api/2.0/postgres/{parent=projects/*}/branches

Creates a new database branch in the project.

API scopes: postgres

Parameters

parentstringRequiredpath: The Project where this Branch will be created. Format: projects/{project_id}

branch_idstringRequiredquery: The ID to use for the Branch. This becomes the final component of the branch's resource name. The ID is required and must be 1-63 characters long, start with a lowercase letter, and contain only lowercase letters, numbers, and hyphens. For example, development becomes projects/my-app/branches/development.

replace_existingbooleanInput onlyquery: If true, update the branch if it already exists instead of returning an error.

Request body

The Branch to create.

namestringIDImmutable: Output only. The full resource path of the branch. Format: projects/{project_id}/branches/{branch_id}

specobjectInput only

The spec contains the branch configuration.

Show child attributesHide child attributes

source_branchstringImmutable: The name of the source branch from which this branch was created (data lineage for point-in-time recovery). If not specified, defaults to the project's default branch. Format: projects/{project_id}/branches/{branch_id}

source_branch_lsnstringImmutable: The Log Sequence Number (LSN) on the source branch from which this branch was created.

source_branch_timestringImmutable: The point in time on the source branch from which this branch was created.

is_protectedboolean: When set to true, protects the branch from deletion and reset. Associated compute endpoints and the project cannot be deleted while the branch is protected.

expire_timestring: Absolute expiration timestamp. When set, the branch will expire at this time. Mutually exclusive with ttl and no_expiry.

ttlstring: Relative time-to-live duration. When set, the branch will expire at creation_time + ttl. Mutually exclusive with expire_time and no_expiry.

no_expiryboolean: Explicitly disable expiration. When set to true, the branch will not expire. If set to false, the request is invalid; provide either ttl or expire_time instead. Mutually exclusive with expire_time and ttl.

Response

namestring: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean: If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobject

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes

error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values

UNKNOWN
INTERNAL_ERROR
TEMPORARILY_UNAVAILABLE
IO_ERROR
BAD_REQUEST
SERVICE_UNDER_MAINTENANCE
WORKSPACE_TEMPORARILY_UNAVAILABLE
DEADLINE_EXCEEDED
CANCELLED
RESOURCE_EXHAUSTED
ABORTED
NOT_FOUND
ALREADY_EXISTS
UNAUTHENTICATED
UNAVAILABLE
INVALID_PARAMETER_VALUE
ENDPOINT_NOT_FOUND
MALFORMED_REQUEST
INVALID_STATE
PERMISSION_DENIED
FEATURE_DISABLED
CUSTOMER_UNAUTHORIZED
REQUEST_LIMIT_EXCEEDED
RESOURCE_CONFLICT
UNPARSEABLE_HTTP_ERROR
NOT_IMPLEMENTED
DATA_LOSS
INVALID_STATE_TRANSITION
COULD_NOT_ACQUIRE_LOCK
RESOURCE_ALREADY_EXISTS
RESOURCE_DOES_NOT_EXIST
QUOTA_EXCEEDED
MAX_BLOCK_SIZE_EXCEEDED
MAX_READ_SIZE_EXCEEDED
PARTIAL_DELETE
MAX_LIST_SIZE_EXCEEDED
DRY_RUN_FAILED
RESOURCE_LIMIT_EXCEEDED
DIRECTORY_NOT_EMPTY
DIRECTORY_PROTECTED
MAX_NOTEBOOK_SIZE_EXCEEDED
MAX_CHILD_NODE_SIZE_EXCEEDED
SEARCH_QUERY_TOO_LONG
SEARCH_QUERY_TOO_SHORT
MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
PERMISSION_NOT_PROPAGATED
DEPLOYMENT_TIMEOUT
GIT_CONFLICT
GIT_UNKNOWN_REF
GIT_SENSITIVE_TOKEN_DETECTED
GIT_URL_NOT_ON_ALLOW_LIST
GIT_REMOTE_ERROR
PROJECTS_OPERATION_TIMEOUT
IPYNB_FILE_IN_REPO
INSECURE_PARTNER_RESPONSE
MALFORMED_PARTNER_RESPONSE
METASTORE_DOES_NOT_EXIST
DAC_DOES_NOT_EXIST
CATALOG_DOES_NOT_EXIST
SCHEMA_DOES_NOT_EXIST
TABLE_DOES_NOT_EXIST
SHARE_DOES_NOT_EXIST
RECIPIENT_DOES_NOT_EXIST
STORAGE_CREDENTIAL_DOES_NOT_EXIST
EXTERNAL_LOCATION_DOES_NOT_EXIST
PRINCIPAL_DOES_NOT_EXIST
PROVIDER_DOES_NOT_EXIST
METASTORE_ALREADY_EXISTS
DAC_ALREADY_EXISTS
CATALOG_ALREADY_EXISTS
SCHEMA_ALREADY_EXISTS
TABLE_ALREADY_EXISTS
SHARE_ALREADY_EXISTS
RECIPIENT_ALREADY_EXISTS
STORAGE_CREDENTIAL_ALREADY_EXISTS
EXTERNAL_LOCATION_ALREADY_EXISTS
PROVIDER_ALREADY_EXISTS
CATALOG_NOT_EMPTY
SCHEMA_NOT_EMPTY
METASTORE_NOT_EMPTY
PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

detailsarray of object

responseobject: The normal, successful response of the operation.

View as Markdown

Request

{
  "name": "string",
  "spec": {
    "source_branch": "string",
    "source_branch_lsn": "string",
    "source_branch_time": "string",
    "is_protected": true,
    "expire_time": "string",
    "ttl": "string",
    "no_expiry": true
  }
}

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "UNKNOWN",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}

Update a Branch GA

PATCH /api/2.0/postgres/{name=projects/*/branches/*}

Updates the specified database branch. You can set this branch as the project's default branch, or protect/unprotect it.

API scopes: postgres

Parameters

namestringRequiredIDImmutablepath: Output only. The full resource path of the branch. Format: projects/{project_id}/branches/{branch_id}

update_maskstringRequiredquery: The list of fields to update.

Request body

The Branch to update.

The branch's name field is used to identify the branch to update. Format: projects/{project_id}/branches/{branch_id}

specobjectInput only

The spec contains the branch configuration.

Show child attributesHide child attributes

source_branchstringImmutable: The name of the source branch from which this branch was created (data lineage for point-in-time recovery). If not specified, defaults to the project's default branch. Format: projects/{project_id}/branches/{branch_id}

source_branch_lsnstringImmutable: The Log Sequence Number (LSN) on the source branch from which this branch was created.

source_branch_timestringImmutable: The point in time on the source branch from which this branch was created.

is_protectedboolean: When set to true, protects the branch from deletion and reset. Associated compute endpoints and the project cannot be deleted while the branch is protected.

expire_timestring: Absolute expiration timestamp. When set, the branch will expire at this time. Mutually exclusive with ttl and no_expiry.

ttlstring: Relative time-to-live duration. When set, the branch will expire at creation_time + ttl. Mutually exclusive with expire_time and no_expiry.

no_expiryboolean: Explicitly disable expiration. When set to true, the branch will not expire. If set to false, the request is invalid; provide either ttl or expire_time instead. Mutually exclusive with expire_time and ttl.

Response

namestring: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean: If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobject

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes

error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values

UNKNOWN
INTERNAL_ERROR
TEMPORARILY_UNAVAILABLE
IO_ERROR
BAD_REQUEST
SERVICE_UNDER_MAINTENANCE
WORKSPACE_TEMPORARILY_UNAVAILABLE
DEADLINE_EXCEEDED
CANCELLED
RESOURCE_EXHAUSTED
ABORTED
NOT_FOUND
ALREADY_EXISTS
UNAUTHENTICATED
UNAVAILABLE
INVALID_PARAMETER_VALUE
ENDPOINT_NOT_FOUND
MALFORMED_REQUEST
INVALID_STATE
PERMISSION_DENIED
FEATURE_DISABLED
CUSTOMER_UNAUTHORIZED
REQUEST_LIMIT_EXCEEDED
RESOURCE_CONFLICT
UNPARSEABLE_HTTP_ERROR
NOT_IMPLEMENTED
DATA_LOSS
INVALID_STATE_TRANSITION
COULD_NOT_ACQUIRE_LOCK
RESOURCE_ALREADY_EXISTS
RESOURCE_DOES_NOT_EXIST
QUOTA_EXCEEDED
MAX_BLOCK_SIZE_EXCEEDED
MAX_READ_SIZE_EXCEEDED
PARTIAL_DELETE
MAX_LIST_SIZE_EXCEEDED
DRY_RUN_FAILED
RESOURCE_LIMIT_EXCEEDED
DIRECTORY_NOT_EMPTY
DIRECTORY_PROTECTED
MAX_NOTEBOOK_SIZE_EXCEEDED
MAX_CHILD_NODE_SIZE_EXCEEDED
SEARCH_QUERY_TOO_LONG
SEARCH_QUERY_TOO_SHORT
MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
PERMISSION_NOT_PROPAGATED
DEPLOYMENT_TIMEOUT
GIT_CONFLICT
GIT_UNKNOWN_REF
GIT_SENSITIVE_TOKEN_DETECTED
GIT_URL_NOT_ON_ALLOW_LIST
GIT_REMOTE_ERROR
PROJECTS_OPERATION_TIMEOUT
IPYNB_FILE_IN_REPO
INSECURE_PARTNER_RESPONSE
MALFORMED_PARTNER_RESPONSE
METASTORE_DOES_NOT_EXIST
DAC_DOES_NOT_EXIST
CATALOG_DOES_NOT_EXIST
SCHEMA_DOES_NOT_EXIST
TABLE_DOES_NOT_EXIST
SHARE_DOES_NOT_EXIST
RECIPIENT_DOES_NOT_EXIST
STORAGE_CREDENTIAL_DOES_NOT_EXIST
EXTERNAL_LOCATION_DOES_NOT_EXIST
PRINCIPAL_DOES_NOT_EXIST
PROVIDER_DOES_NOT_EXIST
METASTORE_ALREADY_EXISTS
DAC_ALREADY_EXISTS
CATALOG_ALREADY_EXISTS
SCHEMA_ALREADY_EXISTS
TABLE_ALREADY_EXISTS
SHARE_ALREADY_EXISTS
RECIPIENT_ALREADY_EXISTS
STORAGE_CREDENTIAL_ALREADY_EXISTS
EXTERNAL_LOCATION_ALREADY_EXISTS
PROVIDER_ALREADY_EXISTS
CATALOG_NOT_EMPTY
SCHEMA_NOT_EMPTY
METASTORE_NOT_EMPTY
PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

detailsarray of object

responseobject: The normal, successful response of the operation.

View as Markdown

Request

{
  "spec": {
    "source_branch": "string",
    "source_branch_lsn": "string",
    "source_branch_time": "string",
    "is_protected": true,
    "expire_time": "string",
    "ttl": "string",
    "no_expiry": true
  }
}

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "UNKNOWN",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}

Delete a Branch GA

DELETE /api/2.0/postgres/{name=projects/*/branches/*}

Deletes the specified database branch.

API scopes: postgres

Parameters

namestringRequiredpath: The full resource path of the branch to delete. Format: projects/{project_id}/branches/{branch_id}

Response

namestring: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean: If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobject

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes

error_codestring

Error codes returned by Databricks APIs to indicate specific failure conditions.

Values:

Show 81 possible values

UNKNOWN
INTERNAL_ERROR
TEMPORARILY_UNAVAILABLE
IO_ERROR
BAD_REQUEST
SERVICE_UNDER_MAINTENANCE
WORKSPACE_TEMPORARILY_UNAVAILABLE
DEADLINE_EXCEEDED
CANCELLED
RESOURCE_EXHAUSTED
ABORTED
NOT_FOUND
ALREADY_EXISTS
UNAUTHENTICATED
UNAVAILABLE
INVALID_PARAMETER_VALUE
ENDPOINT_NOT_FOUND
MALFORMED_REQUEST
INVALID_STATE
PERMISSION_DENIED
FEATURE_DISABLED
CUSTOMER_UNAUTHORIZED
REQUEST_LIMIT_EXCEEDED
RESOURCE_CONFLICT
UNPARSEABLE_HTTP_ERROR
NOT_IMPLEMENTED
DATA_LOSS
INVALID_STATE_TRANSITION
COULD_NOT_ACQUIRE_LOCK
RESOURCE_ALREADY_EXISTS
RESOURCE_DOES_NOT_EXIST
QUOTA_EXCEEDED
MAX_BLOCK_SIZE_EXCEEDED
MAX_READ_SIZE_EXCEEDED
PARTIAL_DELETE
MAX_LIST_SIZE_EXCEEDED
DRY_RUN_FAILED
RESOURCE_LIMIT_EXCEEDED
DIRECTORY_NOT_EMPTY
DIRECTORY_PROTECTED
MAX_NOTEBOOK_SIZE_EXCEEDED
MAX_CHILD_NODE_SIZE_EXCEEDED
SEARCH_QUERY_TOO_LONG
SEARCH_QUERY_TOO_SHORT
MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST
PERMISSION_NOT_PROPAGATED
DEPLOYMENT_TIMEOUT
GIT_CONFLICT
GIT_UNKNOWN_REF
GIT_SENSITIVE_TOKEN_DETECTED
GIT_URL_NOT_ON_ALLOW_LIST
GIT_REMOTE_ERROR
PROJECTS_OPERATION_TIMEOUT
IPYNB_FILE_IN_REPO
INSECURE_PARTNER_RESPONSE
MALFORMED_PARTNER_RESPONSE
METASTORE_DOES_NOT_EXIST
DAC_DOES_NOT_EXIST
CATALOG_DOES_NOT_EXIST
SCHEMA_DOES_NOT_EXIST
TABLE_DOES_NOT_EXIST
SHARE_DOES_NOT_EXIST
RECIPIENT_DOES_NOT_EXIST
STORAGE_CREDENTIAL_DOES_NOT_EXIST
EXTERNAL_LOCATION_DOES_NOT_EXIST
PRINCIPAL_DOES_NOT_EXIST
PROVIDER_DOES_NOT_EXIST
METASTORE_ALREADY_EXISTS
DAC_ALREADY_EXISTS
CATALOG_ALREADY_EXISTS
SCHEMA_ALREADY_EXISTS
TABLE_ALREADY_EXISTS
SHARE_ALREADY_EXISTS
RECIPIENT_ALREADY_EXISTS
STORAGE_CREDENTIAL_ALREADY_EXISTS
EXTERNAL_LOCATION_ALREADY_EXISTS
PROVIDER_ALREADY_EXISTS
CATALOG_NOT_EMPTY
SCHEMA_NOT_EMPTY
METASTORE_NOT_EMPTY
PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

detailsarray of object

responseobject: The normal, successful response of the operation.

View as Markdown

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "UNKNOWN",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}

Branch object​

Get a Branch GA​

Parameters​

Response​

List Branches GA​

Parameters​

Response​

Create a Branch GA​

Parameters​

Request body​

Response​

Update a Branch GA​

Parameters​

Request body​

Response​

Delete a Branch GA​

Parameters​

Response​

Branch object

Get a Branch GA

Parameters

Response

List Branches GA

Parameters

Response

Create a Branch GA

Parameters

Request body

Response

Update a Branch GA

Parameters

Request body

Response

Delete a Branch GA

Parameters

Response