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

You can assign custom CNAME records to DigitalOcean Managed Valkey clusters using the DigitalOcean API when you create a cluster or when you update an existing cluster.

Custom CNAME records let clients connect using a domain name you control, such as db.example.com, instead of the cluster’s default *.db.ondigitalocean.com hostname. This is useful if you provide database access to end users and want to use your own branding.

Limits

• Custom CNAMEs are available for Standard Edition clusters only. Advanced Edition clusters do not support custom CNAMEs.

• Custom CNAMEs are available through the DigitalOcean API only. There is no Control Panel or doctl CLI support.

• You can set custom CNAMEs when creating a cluster or replica, or update them on an existing cluster using the update DO settings endpoint.

• Each cluster supports a maximum of 16 custom CNAMEs.

• Each CNAME must be a valid RFC 1123 hostname (for example, db.example.com).

• Each CNAME can be up to 253 characters long.

• Custom CNAMEs apply to the cluster’s public network connection only. They are not available for private network (VPC) connections.

Configure Custom CNAMEs at Cluster Creation

To assign custom CNAMEs when creating a database cluster, include the do_settings object with a service_cnames array in the request body of the create database cluster API call.

The following example creates a cluster with two custom CNAMEs:

{
  "name": "db-example",
  "engine": "<engine>",
  "version": "<version>",
  "region": "nyc3",
  "size": "db-s-1vcpu-1gb",
  "num_nodes": 1,
  "do_settings": {
    "service_cnames": [
      "db.example.com",
      "database.example.com"
    ]
  }
}

Send the request using curl:

curl -X POST "https://api.digitalocean.com/v2/databases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{
    "name": "db-example",
    "engine": "<engine>",
    "version": "<version>",
    "region": "nyc3",
    "size": "db-s-1vcpu-1gb",
    "num_nodes": 1,
    "do_settings": {
      "service_cnames": [
        "db.example.com",
        "database.example.com"
      ]
    }
  }'

Replace <engine> with the database engine (for example, pg, mysql, or valkey) and <version> with the engine version.

The response includes the do_settings object with the custom CNAMEs you configured.

Retrieve Custom CNAMEs on an Existing Cluster

To view the custom CNAMEs configured on a cluster, send a GET request to the retrieve DO settings endpoint:

curl -X GET "https://api.digitalocean.com/v2/databases/<your-cluster-uuid>/do_settings" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN"

The response includes the do_settings object with the cluster’s current service_cnames array.

Update Custom CNAMEs on an Existing Cluster

To change custom CNAMEs on an existing cluster, send a PUT request to the update DO settings endpoint:

curl -X PUT "https://api.digitalocean.com/v2/databases/<your-cluster-uuid>/do_settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{
    "do_settings": {
      "service_cnames": [
        "db.example.com",
        "database.example.com"
      ]
    }
  }'

To remove all custom CNAMEs, send an empty service_cnames array:

curl -X PUT "https://api.digitalocean.com/v2/databases/<your-cluster-uuid>/do_settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{
    "do_settings": {
      "service_cnames": []
    }
  }'

The API returns HTTP 204 with no response body when the update succeeds.

Set Up DNS Records

After you configure custom CNAMEs, create DNS records with your DNS provider to point each custom domain to the cluster’s default hostname. Create a CNAME record for each custom domain that resolves to the cluster’s *.db.ondigitalocean.com hostname.

For example, if your cluster’s default hostname is db-example-do-user-1234567-0.db.ondigitalocean.com, create a DNS record like:

db.example.com.    CNAME    db-example-do-user-1234567-0.db.ondigitalocean.com.