---
title: "Create a Read-only Replica"
method: POST
path: "/v2/databases/{database_cluster_uuid}/replicas"
tags: ["DigitalOcean-public.v2-new_Databases"]
---

# Create a Read-only Replica

`POST /v2/databases/{database_cluster_uuid}/replicas`

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`.

## Path parameters

- `database_cluster_uuid` string, uuid, required

## Request body

- DatabaseReplica
  - `id` string, uuid — A unique ID that can be used to identify and reference a database replica.
  - `name` string, required — The name to give the read-only replicating
  - `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.
  - `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.
  - `status` 'creating' | 'online' | 'resizing' | 'migrating' | 'forking' — A string representing the current status of the database cluster.
  - `tags` string[] — 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_at` string, date-time — A time value given in ISO8601 combined date and time format that represents when the database cluster was created.
  - `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. <br><br>Requires `vpc:read` scope.
  - `connection` object
    - `uri` string — 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 — The name of the default database.
    - `host` string — The FQDN pointing to the database cluster's current primary node.
    - `port` integer — The port on which the database cluster is listening.
    - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
    - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
    - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
  - `private_connection` object
    - `uri` string — 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 — The name of the default database.
    - `host` string — The FQDN pointing to the database cluster's current primary node.
    - `port` integer — The port on which the database cluster is listening.
    - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
    - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
    - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
  - `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.

## Response `201`

A JSON object with a key of `replica`.

- object
  - `replica` DatabaseReplicaRead
    - `id` string, uuid — A unique ID that can be used to identify and reference a database replica.
    - `name` string, required — The name to give the read-only replicating
    - `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.
    - `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.
    - `status` 'creating' | 'online' | 'resizing' | 'migrating' | 'forking' — A string representing the current status of the database cluster.
    - `tags` string[] — A flat array of tag names as strings applied to the read-only replica.<br><br>Requires `tag:read` scope.
    - `created_at` string, date-time — A time value given in ISO8601 combined date and time format that represents when the database cluster was created.
    - `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. <br><br>Requires `vpc:read` scope.
    - `connection` object
      - `uri` string — 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 — The name of the default database.
      - `host` string — The FQDN pointing to the database cluster's current primary node.
      - `port` integer — The port on which the database cluster is listening.
      - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
      - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
      - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
    - `private_connection` object
      - `uri` string — 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 — The name of the default database.
      - `host` string — The FQDN pointing to the database cluster's current primary node.
      - `port` integer — The port on which the database cluster is listening.
      - `user` string — The default user for the database.<br><br>Requires `database:view_credentials` scope.
      - `password` string — The randomly generated password for the default user.<br><br>Requires `database:view_credentials` scope.
      - `ssl` boolean — A boolean value indicating if the connection should be made over SSL.
    - `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.

## Other responses

- `401` — Authentication failed due to invalid credentials.
- `404` — The resource was not found.
- `429` — The API rate limit has been exceeded.
- `500` — There was a server error.
- `default` — There was an unexpected error.

---

[API](https://skmtc.net/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.net/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/digitalocean/digitalocean-api/versions/cb3bf9b21459/schema)