clusters

Creates, updates, deletes, gets or lists a clusters resource.

Overview

Name	`clusters`
Type	Resource
Id	`digitalocean.databases.clusters`

Fields

The following fields are returned by SELECT queries:

databases_get_cluster
databases_list_clusters

A JSON object with a key of database.

Name	Datatype	Description
`id`	`string (uuid)`	A unique ID that can be used to identify and reference a database cluster. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
`name`	`string`	A unique, human-readable name referring to a database cluster. (example: backend)
`project_id`	`string (uuid)`	The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:read` scope. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
`connection`	`object`
`created_at`	`string (date-time)`	A time value given in ISO8601 combined date and time format that represents when the database cluster was created. (example: 2019-01-11T18:37:36Z)
`db_names`	`array`	An array of strings containing the names of databases created in the database cluster.
`engine`	`string`	A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, and "valkey" for Valkey. (example: mysql)
`maintenance_window`	`object`
`metrics_endpoints`	`array`	Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s).
`num_nodes`	`integer`	The number of nodes in the database cluster.
`private_connection`	`object`
`private_network_uuid`	`string`	A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. (pattern: ^$\|[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}, example: d455e75d-4858-4eec-8c95-da2f0a5f93a7)
`region`	`string`	The slug identifier for the region where the database cluster is located. (example: nyc3)
`rules`	`array`
`schema_registry_connection`	`object`	The connection details for Schema Registry.
`semantic_version`	`string`	A string representing the semantic version of the database engine in use for the cluster. (example: 8.0.28)
`size`	`string`	The slug identifier representing the size of the nodes in the database cluster. (example: db-s-2vcpu-4gb)
`standby_connection`	`object`
`standby_private_connection`	`object`
`status`	`string`	A string representing the current status of the database cluster. (example: creating)
`storage_size_mib`	`integer`	Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage.
`tags`	`array`	An array of tags that have been applied to the database cluster. Requires `tag:read` scope.
`ui_connection`	`object`	The connection details for OpenSearch dashboard.
`users`	`array`
`version`	`string`	A string representing the version of the database engine in use for the cluster. (example: 8)
`version_end_of_availability`	`string`	A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. (example: 2023-05-09T00:00:00Z)
`version_end_of_life`	`string`	A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. (example: 2023-11-09T00:00:00Z)

A JSON object with a key of databases.

Name	Datatype	Description
`id`	`string (uuid)`	A unique ID that can be used to identify and reference a database cluster. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
`name`	`string`	A unique, human-readable name referring to a database cluster. (example: backend)
`project_id`	`string (uuid)`	The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:read` scope. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
`connection`	`object`
`created_at`	`string (date-time)`	A time value given in ISO8601 combined date and time format that represents when the database cluster was created. (example: 2019-01-11T18:37:36Z)
`db_names`	`array`	An array of strings containing the names of databases created in the database cluster.
`engine`	`string`	A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, and "valkey" for Valkey. (example: mysql)
`maintenance_window`	`object`
`metrics_endpoints`	`array`	Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s).
`num_nodes`	`integer`	The number of nodes in the database cluster.
`private_connection`	`object`
`private_network_uuid`	`string`	A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope. (pattern: ^$\|[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}, example: d455e75d-4858-4eec-8c95-da2f0a5f93a7)
`region`	`string`	The slug identifier for the region where the database cluster is located. (example: nyc3)
`rules`	`array`
`schema_registry_connection`	`object`	The connection details for Schema Registry.
`semantic_version`	`string`	A string representing the semantic version of the database engine in use for the cluster. (example: 8.0.28)
`size`	`string`	The slug identifier representing the size of the nodes in the database cluster. (example: db-s-2vcpu-4gb)
`standby_connection`	`object`
`standby_private_connection`	`object`
`status`	`string`	A string representing the current status of the database cluster. (example: creating)
`storage_size_mib`	`integer`	Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage.
`tags`	`array`	An array of tags that have been applied to the database cluster. Requires `tag:read` scope.
`ui_connection`	`object`	The connection details for OpenSearch dashboard.
`users`	`array`
`version`	`string`	A string representing the version of the database engine in use for the cluster. (example: 8)
`version_end_of_availability`	`string`	A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline. (example: 2023-05-09T00:00:00Z)
`version_end_of_life`	`string`	A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline. (example: 2023-11-09T00:00:00Z)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`databases_get_cluster`	`select`	`database_cluster_uuid`		To show information about an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID`. The response will be a JSON object with a database key. This will be set to an object containing the standard database cluster attributes. The embedded `connection` and `private_connection` objects will contain the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster's standby node(s). The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster.
`databases_list_clusters`	`select`		`tag_name`	To list all of the database clusters available on your account, send a GET request to `/v2/databases`. To limit the results to database clusters with a specific tag, include the `tag_name` query parameter set to the name of the tag. For example, `/v2/databases?tag_name=$TAG_NAME`. The result will be a JSON object with a `databases` key. This will be set to an array of database objects, each of which will contain the standard database attributes. The embedded `connection` and `private_connection` objects will contain the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects will contain the information needed to connect to the cluster's standby node(s). The embedded `maintenance_window` object will contain information about any scheduled maintenance for the database cluster.
`databases_create_cluster`	`insert`	`data__name`, `data__engine`, `data__num_nodes`, `data__size`, `data__region`		To create a database cluster, send a POST request to `/v2/databases`. To see a list of options for each engine, such as available regions, size slugs, and versions, send a GET request to the `/v2/databases/options` endpoint. The available sizes for the `storage_size_mib` field depends on the cluster's size. To see a list of available sizes, see Managed Database Pricing. The create response returns a JSON object with a key called `database`. The value of this is an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster's `status` attribute is `creating`. When the cluster is ready to receive traffic, this changes to `online`. The embedded `connection` and `private_connection` objects contains the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster's standby node(s). DigitalOcean managed PostgreSQL and MySQL database clusters take automated daily backups. To create a new database cluster based on a backup of an existing cluster, send a POST request to `/v2/databases`. In addition to the standard database cluster attributes, the JSON body must include a key named `backup_restore` with the name of the original database cluster and the timestamp of the backup to be restored. Creating a database from a backup is the same as forking a database in the control panel. Note: Caching cluster creates are no longer supported as of 2025-04-30T00:00:00Z. Backups are also not supported for Caching or Valkey clusters.
`databases_destroy_cluster`	`delete`	`database_cluster_uuid`		To destroy a specific database, send a DELETE request to `/v2/databases/$DATABASE_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
`databases_update_region`	`exec`	`database_cluster_uuid`, `region`		To migrate a database cluster to a new region, send a `PUT` request to `/v2/databases/$DATABASE_ID/migrate`. The body of the request must specify a `region` attribute. A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its `status` attribute will now be set to `migrating`. This will transition back to `online` when the migration has completed.
`databases_update_cluster_size`	`exec`	`database_cluster_uuid`, `size`, `num_nodes`		To resize a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/resize`. The body of the request must specify both the size and num_nodes attributes. A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its status attribute will now be set to resizing. This will transition back to online when the resize operation has completed.
`databases_update_maintenance_window`	`exec`	`database_cluster_uuid`, `day`, `hour`		To configure the window when automatic maintenance should be performed for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/maintenance`. A successful request will receive a 204 No Content status code with no body in response.
`databases_install_update`	`exec`	`database_cluster_uuid`		To start the installation of updates for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/install_update`. A successful request will receive a 204 No Content status code with no body in response.
`databases_update_major_version`	`exec`	`database_cluster_uuid`		To upgrade the major version of a database, send a PUT request to `/v2/databases/$DATABASE_ID/upgrade`, specifying the target version. A successful request will receive a 204 No Content status code with no body in response.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`database_cluster_uuid`	`string (uuid)`	A unique identifier for a database cluster. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
`tag_name`	`string`	Limits the results to database clusters with a specific tag. Requires `tag:read` scope. (example: production)

`SELECT` examples

databases_get_cluster
databases_list_clusters

To show information about an existing database cluster, send a GET request to /v2/databases/$DATABASE_ID.

The response will be a JSON object with a database key. This will be set to an object containing the standard database cluster attributes.

The embedded connection and private_connection objects will contain the information needed to access the database cluster. For multi-node clusters, the standby_connection and standby_private_connection objects contain the information needed to connect to the cluster's standby node(s).

The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster.

SELECT
id,
name,
project_id,
connection,
created_at,
db_names,
engine,
maintenance_window,
metrics_endpoints,
num_nodes,
private_connection,
private_network_uuid,
region,
rules,
schema_registry_connection,
semantic_version,
size,
standby_connection,
standby_private_connection,
status,
storage_size_mib,
tags,
ui_connection,
users,
version,
version_end_of_availability,
version_end_of_life
FROM digitalocean.databases.clusters
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' -- required;

To list all of the database clusters available on your account, send a GET request to /v2/databases. To limit the results to database clusters with a specific tag, include the tag_name query parameter set to the name of the tag. For example, /v2/databases?tag_name=$TAG_NAME.

The result will be a JSON object with a databases key. This will be set to an array of database objects, each of which will contain the standard database attributes.

The embedded connection and private_connection objects will contain the information needed to access the database cluster. For multi-node clusters, the standby_connection and standby_private_connection objects will contain the information needed to connect to the cluster's standby node(s).

The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster.

SELECT
id,
name,
project_id,
connection,
created_at,
db_names,
engine,
maintenance_window,
metrics_endpoints,
num_nodes,
private_connection,
private_network_uuid,
region,
rules,
schema_registry_connection,
semantic_version,
size,
standby_connection,
standby_private_connection,
status,
storage_size_mib,
tags,
ui_connection,
users,
version,
version_end_of_availability,
version_end_of_life
FROM digitalocean.databases.clusters
WHERE tag_name = '{{ tag_name }}';

`INSERT` examples

databases_create_cluster
Manifest

To create a database cluster, send a POST request to /v2/databases. To see a list of options for each engine, such as available regions, size slugs, and versions, send a GET request to the /v2/databases/options endpoint. The available sizes for the storage_size_mib field depends on the cluster's size. To see a list of available sizes, see Managed Database Pricing.

The create response returns a JSON object with a key called database. The value of this is an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster's status attribute is creating. When the cluster is ready to receive traffic, this changes to online.

The embedded connection and private_connection objects contains the information needed to access the database cluster. For multi-node clusters, the standby_connection and standby_private_connection objects contain the information needed to connect to the cluster's standby node(s).

DigitalOcean managed PostgreSQL and MySQL database clusters take automated daily backups. To create a new database cluster based on a backup of an existing cluster, send a POST request to /v2/databases. In addition to the standard database cluster attributes, the JSON body must include a key named backup_restore with the name of the original database cluster and the timestamp of the backup to be restored. Creating a database from a backup is the same as forking a database in the control panel.
Note: Caching cluster creates are no longer supported as of 2025-04-30T00:00:00Z. Backups are also not supported for Caching or Valkey clusters.

INSERT INTO digitalocean.databases.clusters (
data__name,
data__engine,
data__version,
data__num_nodes,
data__size,
data__region,
data__private_network_uuid,
data__tags,
data__project_id,
data__rules,
data__storage_size_mib,
data__autoscale,
data__backup_restore
)
SELECT 
'{{ name }}' --required,
'{{ engine }}' --required,
'{{ version }}',
{{ num_nodes }} --required,
'{{ size }}' --required,
'{{ region }}' --required,
'{{ private_network_uuid }}',
'{{ tags }}',
'{{ project_id }}',
'{{ rules }}',
{{ storage_size_mib }},
'{{ autoscale }}',
'{{ backup_restore }}'
RETURNING
database
;

# Description fields are for documentation purposes
- name: clusters
  props:
    - name: name
      value: string
      description: >
        A unique, human-readable name referring to a database cluster.
        
    - name: engine
      value: string
      description: >
        A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, and "valkey" for Valkey.
        
      valid_values: ['pg', 'mysql', 'redis', 'valkey', 'mongodb', 'kafka', 'opensearch']
    - name: version
      value: string
      description: >
        A string representing the version of the database engine in use for the cluster.
        
    - name: num_nodes
      value: integer
      description: >
        The number of nodes in the database cluster.
        
    - name: size
      value: string
      description: >
        The slug identifier representing the size of the nodes in the database cluster.
        
    - name: region
      value: string
      description: >
        The slug identifier for the region where the database cluster is located.
        
    - name: private_network_uuid
      value: string
      description: >
        A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. <br><br>Requires `vpc:read` scope.
        
    - name: tags
      value: array
      description: >
        An array of tags (as strings) to apply to the database cluster. <br><br>Requires `tag:create` scope.
        
    - name: project_id
      value: string
      description: >
        The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project.<br><br>Requires `project:update` scope.
        
    - name: rules
      value: array
    - name: storage_size_mib
      value: integer
      description: >
        Additional storage added to the cluster, in MiB. If null, no additional storage is added to the cluster, beyond what is provided as a base amount from the 'size' and any previously added additional storage.
        
    - name: autoscale
      value: object
      description: >
        Contains all autoscaling configuration for a database cluster
        
    - name: backup_restore
      value: object

`DELETE` examples

databases_destroy_cluster

To destroy a specific database, send a DELETE request to /v2/databases/$DATABASE_ID.
A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

DELETE FROM digitalocean.databases.clusters
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' --required;

Lifecycle Methods

databases_update_region
databases_update_cluster_size
databases_update_maintenance_window
databases_install_update
databases_update_major_version

To migrate a database cluster to a new region, send a PUT request to
/v2/databases/$DATABASE_ID/migrate. The body of the request must specify a
region attribute.

A successful request will receive a 202 Accepted status code with no body in
response. Querying the database cluster will show that its status attribute
will now be set to migrating. This will transition back to online when the
migration has completed.

EXEC digitalocean.databases.clusters.databases_update_region 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required 
@@json=
'{
"region": "{{ region }}"
}';

To resize a database cluster, send a PUT request to /v2/databases/$DATABASE_ID/resize. The body of the request must specify both the size and num_nodes attributes.
A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its status attribute will now be set to resizing. This will transition back to online when the resize operation has completed.

EXEC digitalocean.databases.clusters.databases_update_cluster_size 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required 
@@json=
'{
"size": "{{ size }}", 
"num_nodes": {{ num_nodes }}, 
"storage_size_mib": {{ storage_size_mib }}
}';

To configure the window when automatic maintenance should be performed for a database cluster, send a PUT request to /v2/databases/$DATABASE_ID/maintenance.
A successful request will receive a 204 No Content status code with no body in response.

EXEC digitalocean.databases.clusters.databases_update_maintenance_window 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required 
@@json=
'{
"day": "{{ day }}", 
"hour": "{{ hour }}"
}';

To start the installation of updates for a database cluster, send a PUT request to /v2/databases/$DATABASE_ID/install_update.
A successful request will receive a 204 No Content status code with no body in response.

EXEC digitalocean.databases.clusters.databases_install_update 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required;

To upgrade the major version of a database, send a PUT request to /v2/databases/$DATABASE_ID/upgrade, specifying the target version.
A successful request will receive a 204 No Content status code with no body in response.

EXEC digitalocean.databases.clusters.databases_update_major_version 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required 
@@json=
'{
"version": "{{ version }}"
}';

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

DELETE examples​

Lifecycle Methods​