---
title: dots.v2.databases.post()
description: Create a New Database Cluster
product: Reference
url: https://docs.digitalocean.com/reference/dots/reference/databases/databases-create-cluster/
last_updated: "2026-11-18"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](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).

# dots.v2.databases.post()

Generated on 18 Nov 2026 from DoTs version [`v1.25.0`](https://github.com/digitalocean/dots/releases/tag/v1.25.0)

## Usage

```typescript
client.v2.databases.post(body: DatabasesPostRequestBody, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | DatabasesPostResponse>
```

## Description

To create a database cluster, send a POST request to [`/v2/databases`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_create_cluster). To see a list of options for each engine, such as available regions, size slugs, and versions, send a GET request to the [`/v2/databases/options`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_list_options) endpoint. The available sizes for the `storage_size_mib` field depends on the cluster’s size. To see a list of available sizes, see [Managed Database Pricing](https://www.digitalocean.com/pricing/managed-databases?utm_source=docs-agent&utm_medium=md).

The create response returns a JSON object with a key called `database`. The value of this is an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster’s `status` attribute is `creating`. When the cluster is ready to receive traffic, this changes to `online`.

The embedded `connection` and `private_connection` objects contains the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster’s standby node(s).

DigitalOcean managed PostgreSQL and MySQL database clusters take automated daily backups. To create a new database cluster based on a backup of an existing cluster, send a POST request to [`/v2/databases`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_create_cluster). In addition to the standard database cluster attributes, the JSON body must include a key named `backup_restore` with the name of the original database cluster and the timestamp of the backup to be restored. Creating a database from a backup is the same as forking a database in the control panel.

PostgreSQL and MySQL Advanced Edition clusters can be provisioned by setting `engine` to `advanced_pg` or `advanced_mysql`. Advanced Edition clusters are currently in public preview and target highly available workloads. `advanced_pg` supports 1-, 2-, and 3-node deployments; `advanced_mysql` only supports 1- and 3-node deployments. See the [PostgreSQL Advanced Edition](https://docs.digitalocean.com/products/databases/postgresql/how-to/use-advanced-edition-clusters/index.html.md) and [MySQL Advanced Edition](https://docs.digitalocean.com/products/databases/mysql/how-to/use-advanced-edition-clusters/index.html.md) documentation for the feature differences vs. Standard Edition and current preview limitations.

Note: Caching cluster creates are no longer supported as of 2025-04-30T00:00:00Z. Backups are also not supported for Caching or Valkey clusters.

## Parameters

`id` string optional read-only

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

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

`name` string required

Example: `backend`

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

`engine` string required

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.

One of: `pg`, `mysql`, `redis`, `valkey`, `mongodb`, `kafka`, `opensearch`, `advanced_pg`, `advanced_mysql`

`version` string optional

Example: `8`

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

`semanticVersion` string optional read-only

Example: `8.0.28`

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

`numNodes` integer required

Example: `2`

The number of nodes in the database cluster.

`size` string required

Example: `db-s-2vcpu-4gb`

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

`region` string required

Example: `nyc3`

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

`status` string optional read-only

A string representing the current status of the database cluster.

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

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

`privateNetworkUuid` string optional

Example: `d455e75d-4858-4eec-8c95-da2f0a5f93a7`

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.

`tags` array of strings or null optional

Example: `["production"]`

An array of tags (as strings) to apply to the database cluster.

Requires `tag:create` scope.

`dbNames` array of strings or null optional read-only

Example: `["doadmin"]`

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

`uiConnection` object optional read-only

The connection details for OpenSearch dashboard.

## Show child properties

`uri` string optional read-only

Example: `https://doadmin:example_password@db.example.com:25060`

This is provided as a convenience and should be able to be constructed by the other attributes.

`host` string optional read-only

Example: `db.example.com`

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

`port` integer optional read-only

Example: `25060`

The port on which the opensearch dashboard is listening.

`user` string optional read-only

Example: `doadmin`

The default user for the opensearch dashboard.

Requires `database:view_credentials` scope.

`password` string optional read-only

Example: `example_password`

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.

`schemaRegistryConnection` object optional read-only

The connection details for Schema Registry.

## Show child properties

`uri` string optional read-only

Example: `https://doadmin:example_password@db.example.com:25060`

This is provided as a convenience and should be able to be constructed by the other attributes.

`host` string optional read-only

Example: `db.example.com`

The FQDN pointing to the schema registry connection uri.

`port` integer optional read-only

Example: `20835`

The port on which the schema registry is listening.

`user` string optional read-only

Example: `doadmin`

The default user for the schema registry.

Requires `database:view_credentials` scope.

`password` string optional read-only

Example: `example_password`

The randomly generated password for the schema registry.

Requires `database:view_credentials` scope.

`ssl` boolean optional read-only

Example: `true`

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

`connection` object optional read-only

## Show child properties

`uri` string optional read-only

Example: `postgres://doadmin:example_password@db.example.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: `db.example.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: `example_password`

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.

`privateConnection` object optional read-only

## Show child properties

`uri` string optional read-only

Example: `postgres://doadmin:example_password@db.example.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: `db.example.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: `example_password`

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.

`standbyConnection` object optional read-only

## Show child properties

`uri` string optional read-only

Example: `postgres://doadmin:example_password@db.example.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: `db.example.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: `example_password`

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.

`standbyPrivateConnection` object optional read-only

## Show child properties

`uri` string optional read-only

Example: `postgres://doadmin:example_password@db.example.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: `db.example.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: `example_password`

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.

`users` array of objects or null optional read-only

## Show child properties

`name` string required

Example: `app-01`

The name of a database user.

`role` string optional read-only

A string representing the database user's role. The value will be either
"primary" or "normal".

One of: `primary`, `normal`

`password` string optional read-only

Example: `example_password`

A randomly generated password for the database user.
Requires `database:view_credentials` scope.

`accessCert` string optional read-only

Example: `-----BEGIN CERTIFICATE----- MIIEexampleCertificateNotForProductionUseOnly -----END CERTIFICATE-----`

Access certificate for TLS client authentication. (Kafka only)

`accessKey` string optional read-only

Example: `-----BEGIN PRIVATE KEY...`

Access key for TLS client authentication. (Kafka only)

`mysqlSettings` object optional

### Show child properties

`authPlugin` string required

A string specifying the authentication method to be used for connections
to the MySQL user account. The valid values are `mysql_native_password`
or `caching_sha2_password`. If excluded when creating a new user, the
default for the version of MySQL in use will be used. As of MySQL 8.0, the
default is `caching_sha2_password`.

One of: `mysql_native_password`, `caching_sha2_password`

`settings` object optional

### Show child properties

`pgAllowReplication` boolean optional

Example: `true`

For PostgreSQL clusters, set to `true` to grant the user replication
privileges. When omitted on create or update, the value defaults to
`false` and replication privileges are not granted. This option is not
currently supported for other database engines.

`opensearchAcl` array of objects optional

ACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster.

#### Show child properties

`index` string optional

Example: `index-abc.*`

A regex for matching the indexes that this ACL should apply to.

`permission` string optional

Permission set applied to the ACL. 'read' allows user to read from the index. 'write' allows for user to write to the index. 'readwrite' allows for both 'read' and 'write' permission. 'deny'(default) restricts user from performing any operation over an index. 'admin' allows for 'readwrite' as well as any operations to administer the index.

One of: `deny`, `admin`, `read`, `readwrite`, `write`

`acl` array of objects optional

ACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster.

#### Show child properties

`id` string optional

Example: `aaa`

An identifier for the ACL. Will be computed after the ACL is created/updated.

`topic` string required

Example: `topic-abc.*`

A regex for matching the topic(s) that this ACL should apply to.

`permission` string required

Permission set applied to the ACL. 'consume' allows for messages to be consumed from the topic. 'produce' allows for messages to be published to the topic. 'produceconsume' allows for both 'consume' and 'produce' permission. 'admin' allows for 'produceconsume' as well as any operations to administer the topic (delete, update).

One of: `admin`, `consume`, `produce`, `produceconsume`

`mongoUserSettings` object optional

MongoDB-specific settings for the user. Configure these when creating a user. Updating MongoDB roles or database access after creation is not supported; recreate the user to change them. This option is not currently supported for other database engines.

#### Show child properties

`databases` array of strings optional

Example: `["my-db", "my-db-2"]`

A list of databases to which the user should have access. When the database is set to `admin`, the user will have access to all databases based on the user's role i.e. a user with the role `readOnly` assigned to the `admin` database will have read access to all databases.

`role` string optional

The role to assign to the user with each role mapping to a MongoDB built-in role. `readOnly` maps to a [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) role. `readWrite` maps to a [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) role. `dbAdmin` maps to a [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) role.

One of: `readOnly`, `readWrite`, `dbAdmin`

`maintenanceWindow` object or null optional read-only

## Show child properties

`day` string required

Example: `tuesday`

The day of the week on which to apply maintenance updates.

`hour` string required

Example: `14:00`

The hour in UTC at which maintenance updates will be applied in 24 hour format.

`pending` boolean optional read-only

Example: `true`

A boolean value indicating whether any maintenance is scheduled to be performed in the next window.

`description` array of strings optional read-only

Example: `["Update TimescaleDB to version 1.2.1", "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases"]`

A list of strings, each containing information about a pending maintenance update.

`projectId` string optional

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

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.

`rules` array of objects optional

## Show child properties

`uuid` string optional

Example: `79f26d28-ea8a-41f2-8ad8-8cfcdd020095`

A unique ID for the firewall rule itself.

`clusterUuid` string optional read-only

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

A unique ID for the database cluster to which the rule is applied.

`type` string required

The type of resource that the firewall rule allows to access the database cluster.

One of: `droplet`, `k8s`, `ip_addr`, `tag`, `app`

`value` string required

Example: `ff2a6c52-5a44-4b63-b99c-0e98e7a63d61`

The ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster.

`createdAt` 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 firewall rule was created.

`description` string optional

Example: `an IP address for local development`

A human-readable description of the rule.

`versionEndOfLife` string optional read-only

Example: `2023-11-09T00:00:00Z`

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.

`versionEndOfAvailability` string optional read-only

Example: `2023-05-09T00:00:00Z`

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.

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

`metricsEndpoints` array of objects optional read-only

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

## Show child properties

`host` string optional read-only

Example: `db.example.com`

A FQDN pointing to the database cluster's node(s).

`port` integer optional read-only

Example: `9273`

The port on which a service is listening.

`autoscale` object optional

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

## Show child properties

`storage` object optional

Configuration for database cluster storage autoscaling

Additional nested properties are not shown.

`doSettings` object optional

DigitalOcean-specific settings for the database cluster.

## Show child properties

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

`backupRestore` object optional

## Show child properties

`databaseName` string required

Example: `backend`

The name of an existing database cluster from which the backup will be restored.

`backupCreatedAt` string optional

Example: `2019-01-31T19:25:22Z`

The timestamp of an existing database cluster backup in ISO8601 combined date and time format. The most recent backup will be used if excluded.

## Request Sample

## Show Request Sample

```typescript
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.databases.post({
    name: "backend",
    engine: "pg",
    version: "14",
    region: "nyc3",
    size: "db-s-2vcpu-4gb",
    storageSizeMib: 61440,
    numNodes: 2,
    tags: [
        "production",
    ],
});
```

## Response Example

## Show Response Example

```json
{
  "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"
      ]
    }
  }
}
```

## More Information

See [`/v2/databases`](https://docs.digitalocean.com/reference/api/reference/databases/index.html.md#databases_create_cluster) in the API reference for additional detail on responses, headers, parameters, and more.