Database Instance

View as Markdown

A DatabaseInstance represents a logical Postgres instance, comprised of both compute and storage.

DatabaseInstance object

A DatabaseInstance represents a logical Postgres instance, comprised of both compute and storage.

uidstringPublic PreviewOutput only: An immutable UUID identifier for the instance.

namestringPublic Preview: The name of the instance. This is the unique identifier for the instance.

creatorstringPublic PreviewOutput only: The email of the creator of the instance.

read_write_dnsstringPublic PreviewOutput only: The DNS endpoint to connect to the instance for read+write access.

creation_timestringPublic PreviewOutput only: The timestamp when the instance was created.

statestringPublic PreviewOutput only: The current state of the instance.
Values: STATE_UNSPECIFIED, STARTING, AVAILABLE, DELETING, STOPPED, UPDATING, FAILING_OVER

pg_versionstringPublic PreviewOutput only: The version of Postgres running on the instance.

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

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

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

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

node_countint32Public PreviewInput 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 field is input only, see effective_node_count for the output.

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

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

effective_enable_readable_secondariesbooleanPublic PreviewOutput 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_dnsstringPublic PreviewOutput only: 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_daysint32Public PreviewInput only: 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_daysint32Public PreviewOutput 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_refobjectPublic PreviewImmutable

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

uidstringPublic PreviewOutput only: Id of the ref database instance.

namestringPublic Preview: Name of the ref database instance.

lsnstringPublic PreviewInput only

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_lsnstringPublic PreviewOutput 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_timestringPublic Preview: 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 objectPublic PreviewOutput only

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

Show child attributesHide child attributes

uidstringPublic PreviewOutput only: Id of the ref database instance.

namestringPublic Preview: Name of the ref database instance.

lsnstringPublic PreviewInput only

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_lsnstringPublic PreviewOutput 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_timestringPublic Preview: 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_loginbooleanPublic PreviewInput only: Whether to enable PG native password login on the instance. Defaults to false.

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

usage_policy_idstringBetaInput only: The desired usage policy to associate with the instance.

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.

custom_tagsarray of objectBetaInput only

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

The DatabaseInstance object

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

Get Public Preview

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

Get a Database Instance.

API scopes: postgres

Parameters

namestringpath: Name of the cluster to get.

Response

Returns the DatabaseInstance object.

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

List Public Preview

GET /api/2.0/database/instances

List Database Instances.

API scopes: postgres

Parameters

page_tokenstringquery: Pagination token to go to the next page of Database Instances. Requests first page if absent.

page_sizeint32query: Upper bound for items returned. The maximum value is 100.

Response

Returns a list of DatabaseInstance objects.

View as Markdown

Response

{
  "database_instances": [
    {
      "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": {},
      "child_instance_refs": [
        {}
      ],
      "effective_enable_pg_native_login": true,
      "effective_usage_policy_id": "string",
      "effective_custom_tags": [
        {}
      ]
    }
  ],
  "next_page_token": "string"
}

Create Public Preview

POST /api/2.0/database/instances

Create a Database Instance.

API scopes: postgres

Request body

database_instanceobjectRequired

Instance to create.

Show child attributesHide child attributes

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

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

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

node_countint32Input 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 field is input only, see effective_node_count for the output.

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

retention_window_in_daysint32Input only: 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.

parent_instance_refobjectImmutable

Show child attributesHide child attributes

namestring: Name of the ref database instance.

lsnstringInput only

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.

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_loginbooleanInput only: Whether to enable PG native password login on the instance. Defaults to false.

usage_policy_idstringBetaInput only: The desired usage policy to associate with the instance.

custom_tagsarray of objectBetaInput only

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.

Response

Returns the DatabaseInstance object.

View as Markdown

Request

{
  "database_instance": {
    "name": "string",
    "capacity": "string",
    "stopped": true,
    "node_count": 0,
    "enable_readable_secondaries": true,
    "retention_window_in_days": 0,
    "parent_instance_ref": {},
    "enable_pg_native_login": true,
    "usage_policy_id": "string",
    "custom_tags": [
      {}
    ]
  }
}

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

Update Public Preview

PATCH /api/2.0/database/instances/{database_instance.name}

Update a Database Instance.

API scopes: postgres

Parameters

database_instanceobjectRequiredpath

Show child attributesHide child attributes

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

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

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

node_countint32Input 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 field is input only, see effective_node_count for the output.

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

retention_window_in_daysint32Input only: 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.

parent_instance_refobjectImmutable

Show child attributesHide child attributes

namestring: Name of the ref database instance.

lsnstringInput only

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.

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_loginbooleanInput only: Whether to enable PG native password login on the instance. Defaults to false.

usage_policy_idstringBetaInput only: The desired usage policy to associate with the instance.

custom_tagsarray of objectBetaInput only

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.

update_maskstringRequiredquery: The list of fields to update. If unspecified, all fields will be updated when possible. To wipe out custom_tags, specify custom_tags in the update_mask with an empty custom_tags map.

Response

Returns the DatabaseInstance object.

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

Delete Public Preview

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

Delete a Database Instance.

API scopes: postgres

Parameters

namestringpath: Name of the instance to delete.

forcebooleanquery: By default, an instance cannot be deleted if it has descendant instances created via PITR. If this flag is specified as true, all descendent instances will be deleted as well.

purgebooleanquery: Deprecated. Omitting the field or setting it to true will result in the field being hard deleted. Setting a value of false will throw a bad request.