replicas

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

Overview

Name	replicas
Type	Resource
Id	digitalocean.databases.replicas

Fields

The following fields are returned by SELECT queries:

databases_get_replica

A JSON object with a key of replica.

Name	Datatype	Description
id	string (uuid)	A unique ID that can be used to identify and reference a database replica. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
name	string	The name to give the read-only replicating (example: read-nyc3-01)
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)
do_settings	object	DigitalOcean-specific settings for the database cluster.
private_connection	object
private_network_uuid	string	A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. Requires vpc:read scope. (example: 9423cbad-9211-442f-820b-ef6915e99b5f)
region	string	A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster. (example: nyc3)
size	string	A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating. (example: db-s-2vcpu-4gb)
status	string	A string representing the current status of the database cluster. (creating, online, resizing, migrating, forking) (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	A flat array of tag names as strings applied to the read-only replica. Requires tag:read scope.

databases_list_replicas

A JSON object with a key of replicas.

Name	Datatype	Description
id	string (uuid)	A unique ID that can be used to identify and reference a database replica. (example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30)
name	string	The name to give the read-only replicating (example: read-nyc3-01)
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)
do_settings	object	DigitalOcean-specific settings for the database cluster.
private_connection	object
private_network_uuid	string	A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. Requires vpc:read scope. (example: 9423cbad-9211-442f-820b-ef6915e99b5f)
region	string	A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster. (example: nyc3)
size	string	A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating. (example: db-s-2vcpu-4gb)
status	string	A string representing the current status of the database cluster. (creating, online, resizing, migrating, forking) (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	A flat array of tag names as strings applied to the read-only replica. Requires tag:read scope.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
databases_get_replica	select	database_cluster_uuid, replica_name		To show information about an existing database replica, send a GET request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME. Note: Read-only replicas are not supported for Caching or Valkey clusters. The response will be a JSON object with a replica key. This will be set to an object containing the standard database replica attributes.
databases_list_replicas	select	database_cluster_uuid		To list all of the read-only replicas associated with a database cluster, send a GET request to /v2/databases/$DATABASE_ID/replicas. Note: Read-only replicas are not supported for Caching or Valkey clusters. The result will be a JSON object with a replicas key. This will be set to an array of database replica objects, each of which will contain the standard database replica attributes.
databases_create_replica	insert	database_cluster_uuid, name, size		To create a read-only replica for a PostgreSQL or MySQL database cluster, send a POST request to /v2/databases/$DATABASE_ID/replicas specifying the name it should be given, the size of the node to be used, and the region where it will be located. Note: Read-only replicas are not supported for Caching or Valkey clusters. The response will be a JSON object with a key called replica. The value of this will be an object that contains the standard attributes associated with a database replica. The initial value of the read-only replica's status attribute will be forking. When the replica is ready to receive traffic, this will transition to active.
databases_destroy_replica	delete	database_cluster_uuid, replica_name		To destroy a specific read-only replica, send a DELETE request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME. Note: Read-only replicas are not supported for Caching or Valkey clusters. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
databases_promote_replica	exec	database_cluster_uuid, replica_name		To promote a specific read-only replica, send a PUT request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME/promote. Note: Read-only replicas are not supported for Caching or Valkey clusters. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

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)
replica_name	string	The name of the database replica. (example: read-nyc3-01)

SELECT examples

databases_get_replica

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

Note: Read-only replicas are not supported for Caching or Valkey clusters.

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

SELECT
id,
name,
connection,
created_at,
do_settings,
private_connection,
private_network_uuid,
region,
size,
status,
storage_size_mib,
tags
FROM digitalocean.databases.replicas
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' -- required
AND replica_name = '{{ replica_name }}' -- required
;

databases_list_replicas

To list all of the read-only replicas associated with a database cluster, send a GET request to /v2/databases/$DATABASE_ID/replicas.

Note: Read-only replicas are not supported for Caching or Valkey clusters.

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

SELECT
id,
name,
connection,
created_at,
do_settings,
private_connection,
private_network_uuid,
region,
size,
status,
storage_size_mib,
tags
FROM digitalocean.databases.replicas
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' -- required
;

INSERT examples

databases_create_replica

To create a read-only replica for a PostgreSQL or MySQL database cluster, send a POST request to /v2/databases/$DATABASE_ID/replicas specifying the name it should be given, the size of the node to be used, and the region where it will be located.

Note: Read-only replicas are not supported for Caching or Valkey clusters.

The response will be a JSON object with a key called replica. The value of this will be an object that contains the standard attributes associated with a database replica. The initial value of the read-only replica's status attribute will be forking. When the replica is ready to receive traffic, this will transition to active.

INSERT INTO digitalocean.databases.replicas (
name,
region,
size,
tags,
private_network_uuid,
storage_size_mib,
do_settings,
database_cluster_uuid
)
SELECT 
'{{ name }}' /* required */,
'{{ region }}',
'{{ size }}' /* required */,
'{{ tags }}',
'{{ private_network_uuid }}',
{{ storage_size_mib }},
'{{ do_settings }}',
'{{ database_cluster_uuid }}'
RETURNING
replica
;

Manifest

# Description fields are for documentation purposes
- name: replicas
props:
  - name: database_cluster_uuid
    value: "{{ database_cluster_uuid }}"
    description: Required parameter for the replicas resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name to give the read-only replicating
  - name: region
    value: "{{ region }}"
    description: |
      A slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster.
  - name: size
    value: "{{ size }}"
    description: |
      A slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating.
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      A flat array of tag names as strings to apply to the read-only replica after it is created. Tag names can either be existing or new tags. <br><br>Requires `tag:create` scope.
  - name: private_network_uuid
    value: "{{ private_network_uuid }}"
    description: |
      A string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region. <br><br>Requires `vpc:read` scope.
  - name: storage_size_mib
    value: {{ storage_size_mib }}
    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: do_settings
    description: |
      DigitalOcean-specific settings for the database cluster.
    value:
      service_cnames:
        - "{{ service_cnames }}"

DELETE examples

databases_destroy_replica

To destroy a specific read-only replica, send a DELETE request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME.

Note: Read-only replicas are not supported for Caching or Valkey clusters.

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.replicas
WHERE database_cluster_uuid = '{{ database_cluster_uuid }}' --required
AND replica_name = '{{ replica_name }}' --required
;

Lifecycle Methods

databases_promote_replica

To promote a specific read-only replica, send a PUT request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME/promote.

Note: Read-only replicas are not supported for Caching or Valkey clusters.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

EXEC digitalocean.databases.replicas.databases_promote_replica 
@database_cluster_uuid='{{ database_cluster_uuid }}' --required, 
@replica_name='{{ replica_name }}' --required
;