Create a database cluster | DigitalOcean API (unofficial showcase)

30 body fields

Database cluster configuration, with optional backup restoration details.

idstringoptional

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

namestringrequired

A unique, human-readable name referring to a database cluster.

enginestringrequired

A slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. Advanced Edition engines are currently in public preview.

Allowed:pgmysqlredisvalkeymongodbkafkaopensearchadvanced_pgadvanced_mysql

versionstringoptional

A string representing the version of the database engine in use for the cluster.

semantic_versionstringoptional

A string representing the semantic version of the database engine in use for the cluster.

num_nodesintegerrequired

The number of nodes in the database cluster.

sizestringrequired

The slug identifier representing the size of the nodes in the database cluster.

regionstringrequired

The slug identifier for the region where the database cluster is located.

statusstringoptional

A string representing the current status of the database cluster.

Allowed:creatingonlineresizingmigratingforking

created_atstringoptional

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

private_network_uuidstringoptional

A string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster when creating a new database cluster, it will be assigned to your account's default VPC for the region. Requires `vpc:read` scope.

tagsarray<string>optional

An array of tags (as strings) to apply to the database cluster. Requires `tag:create` scope.

db_namesarray<string>optional

An array of strings containing the names of databases created in the database cluster.

ui_connectionobjectoptional

The connection details for OpenSearch dashboard.

schema_registry_connectionobjectoptional

The connection details for Schema Registry.

connectionobjectoptional

private_connectionobjectoptional

standby_connectionobjectoptional

standby_private_connectionobjectoptional

usersarray<object>optional

maintenance_windowobjectoptional

project_idstringoptional

The ID of the project that the database cluster is assigned to. If excluded when creating a new database cluster, it will be assigned to your default project. Requires `project:assign_resource` scope.

rulesarray<object>optional

version_end_of_lifestringoptional

A timestamp referring to the date when the particular version will no longer be supported. If null, the version does not have an end of life timeline.

version_end_of_availabilitystringoptional

A timestamp referring to the date when the particular version will no longer be available for creating new clusters. If null, the version does not have an end of availability timeline.

storage_size_mibintegeroptional

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.

metrics_endpointsarray<object>optional

Public hostname and port of the cluster's metrics endpoint(s). Includes one record for the cluster's primary node and a second entry for the cluster's standby node(s).

autoscaleobjectoptional

Autoscaling configuration for the database cluster. Currently only supports storage autoscaling. If null, autoscaling is not configured for the cluster.

do_settingsobjectoptional

backup_restoreobjectoptional

Backup restoration settings. Supply `database_name` to identify the source cluster; `backup_created_at` identifies the backup timestamp.

6 status codes

201Returns a `database` object containing the created cluster's attributes, including its initial `creating` status and connection details.

databaseobjectrequired

401Returned when authentication credentials are invalid.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404Returned when the requested resource is not found.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429Returned when the API rate limit has been exceeded.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500Returned when a server error occurs.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

defaultReturned when an unexpected error occurs.

idstringrequired

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

messagestringrequired

A message providing additional information about the error, including details to help resolve it when possible.

request_idstringoptional

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned when authentication credentials are invalid. A 404 is returned when the requested resource is not found. A 429 is returned when the API rate limit has been exceeded, and a 500 indicates a server error. name, engine, num_nodes, size, and region are required; engine must be one of the listed values. Caching cluster creation is no longer supported, and backup_restore requires a database_name.

import { Client } from "@octridev/digitalocean";

const client = new Client({
  baseUrl: "https://api.digitalocean.com",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.databases.create({
  name: "Untitled",
  engine: "example",
  numNodes: 20,
  size: 20,
  region: "example",
});

{
  "database": {
    "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "name": "backend",
    "engine": "pg",
    "version": "14",
    "semantic_version": "14.5",
    "connection": {
      "uri": "postgres://doadmin:example_password@db.example.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "db.example.com",
      "port": 25060,
      "user": "doadmin",
      "password": "example_password",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:example_password@private-db.example.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-db.example.com",
      "port": 25060,
      "user": "doadmin",
      "password": "example_password",
      "ssl": true
    },
    "standby_connection": {
      "uri": "postgres://doadmin:example_password@replica-db.example.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "replica-db.example.com",
      "port": 25060,
      "user": "doadmin",
      "password": "example_password",
      "ssl": true
    },
    "standby_private_connection": {
      "uri": "postgres://doadmin:example_password@private-replica-db.example.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-replica-db.example.com",
      "port": 25060,
      "user": "doadmin",
      "password": "example_password",
      "ssl": true
    },
    "users": [
      {
        "name": "doadmin",
        "role": "primary",
        "password": "example_password"
      }
    ],
    "db_names": [
      "defaultdb"
    ],
    "num_nodes": 2,
    "region": "nyc3",
    "status": "creating",
    "created_at": "2019-01-11T18:37:36Z",
    "maintenance_window": {
      "day": "saturday",
      "hour": "08:45:12",
      "pending": true,
      "description": [
        "Update TimescaleDB to version 1.2.1",
        "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases"
      ]
    },
    "size": "db-s-2vcpu-4gb",
    "tags": [
      "production"
    ],
    "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7",
    "version_end_of_life": "2023-11-09T00:00:00Z",
    "version_end_of_availability": "2023-05-09T00:00:00Z",
    "storage_size_mib": 61440,
    "do_settings": {
      "service_cnames": [
        "db.example.com",
        "database.myapp.io"
      ]
    }
  }
}

Request

Response

Errors