v8

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2025-10-165266542.4 MB

DigitalOcean-public.v2-new_Databases

Create a Read-only 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.

post/v2/databases/{database_cluster_uuid}/replicas

Path parameters

database_cluster_uuidstring uuid required

A unique identifier for a database cluster.

Request body

idstring uuid

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

namestring required

The name to give the read-only replicating

regionstring

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.

sizestring

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'creating' | 'online' | 'resizing' | 'migrating' | 'forking'

A string representing the current status of the database cluster.

tagsstring[]

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.

created_atstring date-time

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

private_network_uuidstring

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.

storage_size_mibinteger

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.

Example request

{
  "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
  "name": "read-nyc3-01",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb",
  "status": "creating",
  "tags": [
    "production"
  ],
  "created_at": "2019-01-11T18:37:36Z",
  "private_network_uuid": "9423cbad-9211-442f-820b-ef6915e99b5f",
  "connection": {
    "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
    "database": "defaultdb",
    "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
    "port": 25060,
    "user": "doadmin",
    "password": "wv78n3zpz42xezdk",
    "ssl": true
  },
  "private_connection": {
    "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
    "database": "defaultdb",
    "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
    "port": 25060,
    "user": "doadmin",
    "password": "wv78n3zpz42xezdk",
    "ssl": true
  },
  "storage_size_mib": 61440
}

Response

A JSON object with a key of replica.

Example response

{
  "replica": {
    "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "name": "read-nyc3-01",
    "region": "nyc3",
    "size": "db-s-2vcpu-4gb",
    "status": "creating",
    "tags": [
      "production"
    ],
    "created_at": "2019-01-11T18:37:36Z",
    "private_network_uuid": "9423cbad-9211-442f-820b-ef6915e99b5f",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "defaultdb",
      "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "defaultdb",
      "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "storage_size_mib": 61440
  }
}