Skip to main content

Database

View as Markdown

Database object​

Database represents a Postgres database within a Branch.

namestringIDImmutable

The resource name of the database. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

parentstringOutput only

The branch containing this database. Format: projects/{project_id}/branches/{branch_id}

create_timestringOutput only

A timestamp indicating when the database was created.

update_timestringOutput only

A timestamp indicating when the database was last updated.

specobject

The desired state of the Database.

Read the resource's current values from status, rather than spec. spec tracks field ownership for infrastructure-as-code tools and may omit unmanaged fields.

Show child attributesHide child attributes
rolestring

The name of the role that owns the database. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

The role must be in the same branch as the database. To change the owner, pass valid existing Role name when updating the Database

Required when creating the Database.

postgres_databasestring

The name of the Postgres database.

This expects a valid Postgres identifier as specified in the link below. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS Required when creating the Database.

To rename, pass a valid postgres identifier when updating the Database.

statusobjectOutput only

The observed state of the Database.

Show child attributesHide child attributes
rolestring

The name of the role that owns the database. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

postgres_databasestring

The name of the Postgres database.

database_idstringOutput only

Part of the resource name.

database_idstringOutput only

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

Get a Database GA​

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

Retrieves information about the specified Postgres database.

API scopes: postgres

Parameters​

namestringRequiredpath

The name of the Database to retrieve. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

Response​

Returns the Database object.

List postgres databases in a branch GA​

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

Returns a list of Postgres databases in the branch.

API scopes: postgres

Parameters​

parentstringRequiredpath

The Branch that owns this collection of databases. Format: projects/{project_id}/branches/{branch_id}

page_tokenstringquery

Pagination token to go to the next page of Databases. Requests first page if absent.

page_sizeint32query

Upper bound for items returned.

Response​

Returns a list of Database objects.

Create a Database GA​

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

Create a Database.

Creates a database in the specified branch. A branch can have multiple databases.

API scopes: postgres

Parameters​

parentstringRequiredpath

The Branch where this Database will be created. Format: projects/{project_id}/branches/{branch_id}

database_idstringquery

The ID used to identify and manage the Database resource through the API. The Postgres database name is specified in spec.postgres_database.

This value should be 3-63 characters, start with a lowercase letter, end with a lowercase letter or digit, and contain only lowercase letters, digits, and hyphens.

If database_id is not specified in the request, it is generated automatically.

Example: orders

replace_existingbooleanInput onlyquery

If true, update the database if it already exists instead of returning an error. This requires database_id to be set. Without database_id, the request follows the normal create path and fails if the database name already exists.

Request body​

The desired specification of a Database.

namestringIDImmutable

The resource name of the database. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

specobject

The desired state of the Database.

Read the resource's current values from status, rather than spec. spec tracks field ownership for infrastructure-as-code tools and may omit unmanaged fields.

Show child attributesHide child attributes
rolestringRequired

The name of the role that owns the database. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

The role must be in the same branch as the database. To change the owner, pass valid existing Role name when updating the Database

Required when creating the Database.

postgres_databasestring

The name of the Postgres database.

This expects a valid Postgres identifier as specified in the link below. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS Required when creating the Database.

To rename, pass a valid postgres identifier when updating the Database.

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.

Update a Database GA​

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

Updates the specified Postgres database. Only the fields named in update_mask change.

API scopes: postgres

Parameters​

namestringRequiredIDImmutablepath

The resource name of the database. Format: projects/{project_id}/branches/{branch_id}/databases/{database_id}

update_maskstringRequiredquery

The list of fields to update. The updatable fields are spec.role and spec.postgres_database.

Request body​

The Database to update.

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

specobject

The desired state of the Database.

Read the resource's current values from status, rather than spec. spec tracks field ownership for infrastructure-as-code tools and may omit unmanaged fields.

Show child attributesHide child attributes
rolestringRequired

The name of the role that owns the database. Format: projects/{project_id}/branches/{branch_id}/roles/{role_id}

The role must be in the same branch as the database. To change the owner, pass valid existing Role name when updating the Database

Required when creating the Database.

postgres_databasestring

The name of the Postgres database.

This expects a valid Postgres identifier as specified in the link below. https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS Required when creating the Database.

To rename, pass a valid postgres identifier when updating the Database.

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.

Delete a Database GA​

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

Deletes the specified Postgres database.

API scopes: postgres

Parameters​

namestringRequiredIDImmutablepath

The resource name of the postgres database. Format: projects/{project_id}/branches/{branch_id}/databases/{database_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.