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

tableobject

Show child attributesHide child attributes

namestring

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

namestring

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

namestringpath

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

uidstring

An immutable UUID identifier for the instance.

namestring

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

creatorstring

The email of the creator of the instance.

read_write_dnsstring

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

creation_timestring

The timestamp when the instance was created.

statestring

The current state of the instance.

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

pg_versionstring

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_capacitystring

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.

stoppedboolean

Whether to stop the instance. An input only param, see effective_stopped for the output.

effective_stoppedboolean

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.

node_countint32

The number of nodes in the instance, composed of 1 primary and 0 or more secondaries. Defaults to 1 primary and 0 secondaries. This field is input only, see effective_node_count for the output.

effective_node_countint32

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.

enable_readable_secondariesboolean

Whether to enable secondaries to serve read-only traffic. Defaults to false.

effective_enable_readable_secondariesboolean

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_dnsstring

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

retention_window_in_daysint32

The retention window for the instance. This is the time window in days for which the historical data is retained. The default value is 7 days. Valid values are 2 to 35 days.

effective_retention_window_in_daysint32

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_refobject

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

uidstring

Id of the ref database instance.

namestring

Name of the ref database instance.

lsnstring

User-specified WAL LSN of the ref database instance.

Input: For specifying the WAL LSN to create a child instance. Optional. Output: Only populated if provided as input to create a child instance.

effective_lsnstring

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 object

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

Show child attributesHide child attributes

uidstring

Id of the ref database instance.

namestring

Name of the ref database instance.

lsnstring

User-specified WAL LSN of the ref database instance.

Input: For specifying the WAL LSN to create a child instance. Optional. Output: Only populated if provided as input to create a child instance.

effective_lsnstring

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.

enable_pg_native_loginboolean

Whether to enable PG native password login on the instance. Defaults to false.

effective_enable_pg_native_loginboolean

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.

usage_policy_idstringBeta

The desired usage policy to associate with the instance.

effective_usage_policy_idstringBeta

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.

custom_tagsarray of objectBeta

Custom tags associated with the instance. This field is only included on create and update responses.

Show child attributesHide child attributes

keystringBeta

The key of the custom tag.

valuestringBeta

The value of the custom tag.

effective_custom_tagsarray of objectBeta

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",
  "stopped": true,
  "effective_stopped": true,
  "node_count": 0,
  "effective_node_count": 0,
  "enable_readable_secondaries": true,
  "effective_enable_readable_secondaries": true,
  "read_only_dns": "string",
  "retention_window_in_days": 0,
  "effective_retention_window_in_days": 0,
  "parent_instance_ref": {
    "uid": "string",
    "name": "string",
    "lsn": "string",
    "effective_lsn": "string",
    "branch_time": "string"
  },
  "child_instance_refs": [
    {
      "uid": "string",
      "name": "string",
      "lsn": "string",
      "effective_lsn": "string",
      "branch_time": "string"
    }
  ],
  "enable_pg_native_login": true,
  "effective_enable_pg_native_login": true,
  "usage_policy_id": "string",
  "effective_usage_policy_id": "string",
  "custom_tags": [
    {
      "key": "string",
      "value": "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

Values: PERMISSION_SET_UNSPECIFIED, READ_ONLY

resourcesarray of object

Show child attributesHide child attributes

unspecified_resource_namestringRequired

table_namestringRequired

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

namestringpath

Response

namestring

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