For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.databases.create_replica(
    database_cluster_uuid="9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    body={
        "name": "read-nyc3-01",
        "region": "nyc3",
        "size": "db-s-2vcpu-4gb",
        ...,
    },
)

Description

To create a read-only replica for a PostgreSQL or MySQL database cluster, send a POST request to /v2/databases/{database_cluster_uuid}/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.

Parameters

database_cluster_uuid string required

A unique identifier for a database cluster.

id string optional read-only

Example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30

A unique ID that can be used to identify and reference a database replica.

name string required

Example: read-nyc3-01

The name to give the read-only replicating

region string optional

Example: nyc3

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.

size string required

Example: db-s-2vcpu-4gb

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.

status string optional read-only

A string representing the current status of the database cluster.

One of: creating, online, resizing, migrating, forking

tags array of strings optional

Example: ['production']

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.

Requires tag:create scope.

created_at string optional read-only

Example: 2019-01-11T18:37:36Z

A time value given in ISO8601 combined date and time format that represents when the database cluster was created.

private_network_uuid string optional

Example: 9423cbad-9211-442f-820b-ef6915e99b5f

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.

connection object optional

Show child properties

uri string optional read-only

Example: postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require

A connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.

database string optional read-only

Example: defaultdb

The name of the default database.

host string optional read-only

Example: backend-do-user-19081923-0.db.ondigitalocean.com

The FQDN pointing to the database cluster's current primary node.

port integer optional read-only

Example: 25060

The port on which the database cluster is listening.

user string optional read-only

Example: doadmin

The default user for the database.

Requires database:view_credentials scope.

password string optional read-only

Example: wv78n3zpz42xezdk

The randomly generated password for the default user.

Requires database:view_credentials scope.

ssl boolean optional read-only

Example: True

A boolean value indicating if the connection should be made over SSL.

private_connection object optional

Show child properties

uri string optional read-only

Example: postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require

A connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.

database string optional read-only

Example: defaultdb

The name of the default database.

host string optional read-only

Example: backend-do-user-19081923-0.db.ondigitalocean.com

The FQDN pointing to the database cluster's current primary node.

port integer optional read-only

Example: 25060

The port on which the database cluster is listening.

user string optional read-only

Example: doadmin

The default user for the database.

Requires database:view_credentials scope.

password string optional read-only

Example: wv78n3zpz42xezdk

The randomly generated password for the default user.

Requires database:view_credentials scope.

ssl boolean optional read-only

Example: True

A boolean value indicating if the connection should be made over SSL.

storage_size_mib integer optional

Example: 61440

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.

do_settings object optional

Show child properties

service_cnames array of strings optional

Example: ['db.example.com', 'database.myapp.io']

An array of custom CNAMEs for the database cluster. Each CNAME must be a valid RFC 1123 hostname (e.g., "db.example.com"). Maximum of 16 CNAMEs allowed, each up to 253 characters.

Request Sample

import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

create_req = {
  "name": "read-nyc3-01",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb",
  "storage_size_mib": 61440,
  "do_settings": {
    "service_cnames": [
      "replica-db.example.com",
      "read-replica.myapp.io"
    ]
  }
}

create_resp = client.databases.create_replica(database_cluster_uuid="9cc10173", body=create_req)

Response Example

{
  "replica": {
    "name": "read-nyc3-01",
    "connection": {
      "uri": "",
      "database": "defaultdb",
      "host": "read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "region": "nyc3",
    "status": "online",
    "created_at": "2019-01-11T18:37:36Z",
    "do_settings": {
      "service_cnames": [
        "replica-db.example.com",
        "read-replica.myapp.io"
      ]
    }
  }
}

More Information

See /v2/databases/{database_cluster_uuid}/replicas in the API reference for additional detail on responses, headers, parameters, and more.