dots.v2.databases.post()

Generated on 13 Nov 2026 from DoTs version v1.24.0

Usage

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

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. 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 and MySQL Advanced Edition 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:[email protected]: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:[email protected]: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:[email protected]: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:[email protected]: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:[email protected]: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:[email protected]: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 role. readWrite maps to a readWrite role. dbAdmin maps to a 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
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
{
  "database": {
    "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "name": "backend",
    "engine": "pg",
    "version": "14",
    "semantic_version": "14.5",
    "connection": {
      "uri": "postgres://doadmin:[email protected]:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "db.example.com",
      "port": 25060,
      "user": "doadmin",
      "password": "example_password",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:[email protected]:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-db.example.com",
      "port": 25060,
      "user": "doadmin",
      "password": "example_password",
      "ssl": true
    },
    "standby_connection": {
      "uri": "postgres://doadmin:[email protected]: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:[email protected]: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 in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.