Database

View as Markdown

Create Database Instances and manage their configurations, including integrations with Unity Catalog

Create Database TablePOST /api/2.0/database/tablesDelete Database TableDELETE /api/2.0/database/tables/{name}Find Database Instance By UidGET /api/2.0/database/instances:findByUidGenerate Database CredentialPOST /api/2.0/database/credentialsGet Database TableGET /api/2.0/database/tables/{name}

Create Database Table Public Preview

POST /api/2.0/database/tables

Create a Database Table. Useful for registering pre-existing PG tables in UC. See CreateSyncedDatabaseTable for creating synced tables in PG from a source table in UC.

API scopes: postgres

Request body

tableobjectRequired

Show child attributesHide child attributes

namestringRequired

Full three-part (catalog, schema, table) name of the table.

database_instance_namestring

Name of the target database instance. This is required when creating database tables in standard catalogs. This is optional when creating database tables in registered catalogs. If this field is specified when creating database tables in registered catalogs, the database instance name MUST match that of the registered catalog (or the request will be rejected).

logical_database_namestring

Target Postgres database object (logical database) name for this table.

When creating a table in a standard catalog, this field is required. In this scenario, specifying this field will allow targeting an arbitrary postgres database.

Registration of database tables via /database/tables is currently only supported in standard catalogs.

Response

namestringRequired

Full three-part (catalog, schema, table) name of the table.

database_instance_namestring

Name of the target database instance. This is required when creating database tables in standard catalogs. This is optional when creating database tables in registered catalogs. If this field is specified when creating database tables in registered catalogs, the database instance name MUST match that of the registered catalog (or the request will be rejected).

logical_database_namestring

Target Postgres database object (logical database) name for this table.

When creating a table in a standard catalog, this field is required. In this scenario, specifying this field will allow targeting an arbitrary postgres database.

Registration of database tables via /database/tables is currently only supported in standard catalogs.

View as Markdown

Request

{
  "table": {
    "name": "string",
    "database_instance_name": "string",
    "logical_database_name": "string"
  }
}

Response

{
  "name": "string",
  "database_instance_name": "string",
  "logical_database_name": "string"
}

Delete Database Table Public Preview

DELETE /api/2.0/database/tables/{name}

Delete a Database Table.

API scopes: postgres

Parameters

namestringRequiredpath

View as Markdown

Response

{}

Find Database Instance By Uid Public Preview

GET /api/2.0/database/instances:findByUid

Find a Database Instance by uid.

API scopes: postgres

Parameters

uidstringquery

UID of the cluster to get.

Response

uidstringOutput only

An immutable UUID identifier for the instance.

namestringRequired

The name of the instance. This is the unique identifier for the instance.

creatorstringOutput only

The email of the creator of the instance.

read_write_dnsstringOutput only

The DNS endpoint to connect to the instance for read+write access.

creation_timestringOutput only

The timestamp when the instance was created.

statestringOutput only

The current state of the instance.

Values: STATE_UNSPECIFIED, STARTING, AVAILABLE, DELETING, STOPPED, UPDATING, FAILING_OVER

pg_versionstringOutput only

The version of Postgres running on the instance.

capacitystring

The sku of the instance. Valid values are "CU_1", "CU_2", "CU_4", "CU_8".

effective_capacitystringOutput only

Deprecated. The sku of the instance; this field will always match the value of capacity. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

effective_stoppedbooleanOutput only

Whether the instance is stopped. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

effective_node_countint32Output only

The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

effective_enable_readable_secondariesbooleanOutput only

Whether secondaries serving read-only traffic are enabled. Defaults to false. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

read_only_dnsstringOutput only

The DNS endpoint to connect to the instance for read only access. This is only available if enable_readable_secondaries is true.

effective_retention_window_in_daysint32Output only

The retention window for the instance. This is the time window in days for which the historical data is retained. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

parent_instance_refobjectImmutable

The ref of the parent instance. This is only available if the instance is child instance. Input: For specifying the parent instance to create a child instance. Optional. Output: Only populated if provided as input to create a child instance.

Show child attributesHide child attributes

uidstringOutput only

Id of the ref database instance.

namestring

Name of the ref database instance.

effective_lsnstringOutput only

For a parent ref instance, this is the LSN on the parent instance from which the instance was created. For a child ref instance, this is the LSN on the instance from which the child instance was created. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

branch_timestring

Branch time of the ref database instance. For a parent ref instance, this is the point in time on the parent instance from which the instance was created. For a child ref instance, this is the point in time on the instance from which the child instance was created. Input: For specifying the point in time to create a child instance. Optional. Output: Only populated if provided as input to create a child instance.

child_instance_refsarray of objectOutput only

The refs of the child instances. This is only available if the instance is parent instance.

Show child attributesHide child attributes

uidstringOutput only

Id of the ref database instance.

namestring

Name of the ref database instance.

effective_lsnstringOutput only

For a parent ref instance, this is the LSN on the parent instance from which the instance was created. For a child ref instance, this is the LSN on the instance from which the child instance was created. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

branch_timestring

Branch time of the ref database instance. For a parent ref instance, this is the point in time on the parent instance from which the instance was created. For a child ref instance, this is the point in time on the instance from which the child instance was created. Input: For specifying the point in time to create a child instance. Optional. Output: Only populated if provided as input to create a child instance.

effective_enable_pg_native_loginbooleanOutput only

Whether the instance has PG native password login enabled. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

effective_usage_policy_idstringBetaOutput only

The policy that is applied to the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

effective_custom_tagsarray of objectBetaOutput only

The recorded custom tags associated with the instance. This is an output only field that contains the value computed from the input field combined with server side defaults. Use the field without the effective_ prefix to set the value.

Show child attributesHide child attributes

keystringBeta

The key of the custom tag.

valuestringBeta

The value of the custom tag.

View as Markdown

Response

{
  "uid": "string",
  "name": "string",
  "creator": "string",
  "read_write_dns": "string",
  "creation_time": "string",
  "state": "string",
  "pg_version": "string",
  "capacity": "string",
  "effective_capacity": "string",
  "effective_stopped": true,
  "effective_node_count": 0,
  "effective_enable_readable_secondaries": true,
  "read_only_dns": "string",
  "effective_retention_window_in_days": 0,
  "parent_instance_ref": {
    "uid": "string",
    "name": "string",
    "effective_lsn": "string",
    "branch_time": "string"
  },
  "child_instance_refs": [
    {
      "uid": "string",
      "name": "string",
      "effective_lsn": "string",
      "branch_time": "string"
    }
  ],
  "effective_enable_pg_native_login": true,
  "effective_usage_policy_id": "string",
  "effective_custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Generate Database Credential Public Preview

POST /api/2.0/database/credentials

Generates a credential that can be used to access database instances.

API scopes: postgres

Request body

request_idstring

instance_namesarray of string

Instances to request a credential for. At least one of instance_names or claims must be specified.

claimsarray of object

A set of UC permissions to add to the credential. We verify that the caller has the necessary permissions in UC and include a reference in the token. Postgres uses that token to give the connecting user additional grants to the Postgres resources that correspond to the UC resources. The UC resources need to be something that have a Postgres counterpart. For example, a synced table or a table in a UC database catalog.

Show child attributesHide child attributes

permission_setstring

Might add WRITE in the future

Values: PERMISSION_SET_UNSPECIFIED, READ_ONLY

resourcesarray of object

Show child attributesHide child attributes

unspecified_resource_namestring

table_namestring

Response

tokenstring

expiration_timestring

View as Markdown

Request

{
  "request_id": "string",
  "instance_names": [
    "string"
  ],
  "claims": [
    {
      "permission_set": "string",
      "resources": [
        {}
      ]
    }
  ]
}

Response

{
  "token": "string",
  "expiration_time": "string"
}

Get Database Table Public Preview

GET /api/2.0/database/tables/{name}

Get a Database Table.

API scopes: postgres

Parameters

namestringRequiredpath

Response

namestringRequired

Full three-part (catalog, schema, table) name of the table.

database_instance_namestring

Name of the target database instance. This is required when creating database tables in standard catalogs. This is optional when creating database tables in registered catalogs. If this field is specified when creating database tables in registered catalogs, the database instance name MUST match that of the registered catalog (or the request will be rejected).

logical_database_namestring

Target Postgres database object (logical database) name for this table.

When creating a table in a standard catalog, this field is required. In this scenario, specifying this field will allow targeting an arbitrary postgres database.

Registration of database tables via /database/tables is currently only supported in standard catalogs.

View as Markdown

Response

{
  "name": "string",
  "database_instance_name": "string",
  "logical_database_name": "string"
}