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 Preview: An immutable UUID identifier for the instance.

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

creatorstringPublic Preview: The email of the creator of the instance.

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

creation_timestringPublic Preview: The timestamp when the instance was created.

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

pg_versionstringPublic Preview: 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 Preview: 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 Preview: Whether to stop the instance. An input only param, see effective_stopped for the output.

effective_stoppedbooleanPublic Preview: 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 Preview: 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 Preview: 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 Preview: Whether to enable secondaries to serve read-only traffic. Defaults to false.

effective_enable_readable_secondariesbooleanPublic Preview: 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 Preview: 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 Preview: 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 Preview: 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 Preview

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 Preview: Id of the ref database instance.

namestringPublic Preview: Name of the ref database instance.

lsnstringPublic Preview

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

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

Show child attributesHide child attributes

uidstringPublic Preview: Id of the ref database instance.

namestringPublic Preview: Name of the ref database instance.

lsnstringPublic Preview

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

effective_enable_pg_native_loginbooleanPublic Preview: 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

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

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",
      "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": {},
      "child_instance_refs": [
        {}
      ],
      "enable_pg_native_login": true,
      "effective_enable_pg_native_login": true,
      "usage_policy_id": "string",
      "effective_usage_policy_id": "string",
      "custom_tags": [
        {}
      ],
      "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_instanceobject

Instance to create.

Show child attributesHide child attributes

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

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

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": {
    "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": {},
    "child_instance_refs": [
      {}
    ],
    "enable_pg_native_login": true,
    "effective_enable_pg_native_login": true,
    "usage_policy_id": "string",
    "effective_usage_policy_id": "string",
    "custom_tags": [
      {}
    ],
    "effective_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",
  "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"
    }
  ]
}

Update Public Preview

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

Update a Database Instance.

API scopes: postgres

Parameters

database_instanceobjectpath

Show child attributesHide child attributes

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

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

Show child attributesHide child attributes

keystringBeta: The key of the custom tag.

valuestringBeta: The value of the custom tag.

update_maskstringquery: 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",
  "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"
    }
  ]
}

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.