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
idstring optional read-onlyExample:
9cc10173-e9ea-4176-9dbc-a4cee4c4ff30A unique ID that can be used to identify and reference a database cluster.
namestring requiredExample:
backendA unique, human-readable name referring to a database cluster.
enginestring requiredA 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.
versionstring optionalExample:
8A string representing the version of the database engine in use for the cluster.
semanticVersionstring optional read-onlyExample:
8.0.28A string representing the semantic version of the database engine in use for the cluster.
numNodesinteger requiredExample:
2The number of nodes in the database cluster.
sizestring requiredExample:
db-s-2vcpu-4gbThe slug identifier representing the size of the nodes in the database cluster.
regionstring requiredExample:
nyc3The slug identifier for the region where the database cluster is located.
statusstring optional read-onlyA string representing the current status of the database cluster.
createdAtstring optional read-onlyExample:
2019-01-11T18:37:36ZA time value given in ISO8601 combined date and time format that represents when the database cluster was created.
privateNetworkUuidstring optionalExample:
d455e75d-4858-4eec-8c95-da2f0a5f93a7A 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.
Requiresvpc:readscope.tagsarray of strings or null optionalExample:
["production"]An array of tags (as strings) to apply to the database cluster.
Requirestag:createscope.dbNamesarray of strings or null optional read-onlyExample:
["doadmin"]An array of strings containing the names of databases created in the database cluster.
uiConnectionobject optional read-onlyThe connection details for OpenSearch dashboard.
Show child properties
uristring optional read-onlyExample:
https://doadmin:[email protected]:25060This is provided as a convenience and should be able to be constructed by the other attributes.
hoststring optional read-onlyExample:
db.example.comThe FQDN pointing to the opensearch cluster's current primary node.
portinteger optional read-onlyExample:
25060The port on which the opensearch dashboard is listening.
userstring optional read-onlyExample:
doadminThe default user for the opensearch dashboard.
Requiresdatabase:view_credentialsscope.passwordstring optional read-onlyExample:
example_passwordThe randomly generated password for the default user.
Requiresdatabase:view_credentialsscope.sslboolean optional read-onlyExample:
trueA boolean value indicating if the connection should be made over SSL.
schemaRegistryConnectionobject optional read-onlyThe connection details for Schema Registry.
Show child properties
uristring optional read-onlyExample:
https://doadmin:[email protected]:25060This is provided as a convenience and should be able to be constructed by the other attributes.
hoststring optional read-onlyExample:
db.example.comThe FQDN pointing to the schema registry connection uri.
portinteger optional read-onlyExample:
20835The port on which the schema registry is listening.
userstring optional read-onlyExample:
doadminThe default user for the schema registry.
Requiresdatabase:view_credentialsscope.passwordstring optional read-onlyExample:
example_passwordThe randomly generated password for the schema registry.
Requiresdatabase:view_credentialsscope.sslboolean optional read-onlyExample:
trueA boolean value indicating if the connection should be made over SSL.
connectionobject optional read-onlyShow child properties
uristring optional read-onlyExample:
postgres://doadmin:[email protected]:25060/defaultdb?sslmode=requireA connection string in the format accepted by the
psqlcommand. This is provided as a convenience and should be able to be constructed by the other attributes.databasestring optional read-onlyExample:
defaultdbThe name of the default database.
hoststring optional read-onlyExample:
db.example.comThe FQDN pointing to the database cluster's current primary node.
portinteger optional read-onlyExample:
25060The port on which the database cluster is listening.
userstring optional read-onlyExample:
doadminThe default user for the database.
Requiresdatabase:view_credentialsscope.passwordstring optional read-onlyExample:
example_passwordThe randomly generated password for the default user.
Requiresdatabase:view_credentialsscope.sslboolean optional read-onlyExample:
trueA boolean value indicating if the connection should be made over SSL.
privateConnectionobject optional read-onlyShow child properties
uristring optional read-onlyExample:
postgres://doadmin:[email protected]:25060/defaultdb?sslmode=requireA connection string in the format accepted by the
psqlcommand. This is provided as a convenience and should be able to be constructed by the other attributes.databasestring optional read-onlyExample:
defaultdbThe name of the default database.
hoststring optional read-onlyExample:
db.example.comThe FQDN pointing to the database cluster's current primary node.
portinteger optional read-onlyExample:
25060The port on which the database cluster is listening.
userstring optional read-onlyExample:
doadminThe default user for the database.
Requiresdatabase:view_credentialsscope.passwordstring optional read-onlyExample:
example_passwordThe randomly generated password for the default user.
Requiresdatabase:view_credentialsscope.sslboolean optional read-onlyExample:
trueA boolean value indicating if the connection should be made over SSL.
standbyConnectionobject optional read-onlyShow child properties
uristring optional read-onlyExample:
postgres://doadmin:[email protected]:25060/defaultdb?sslmode=requireA connection string in the format accepted by the
psqlcommand. This is provided as a convenience and should be able to be constructed by the other attributes.databasestring optional read-onlyExample:
defaultdbThe name of the default database.
hoststring optional read-onlyExample:
db.example.comThe FQDN pointing to the database cluster's current primary node.
portinteger optional read-onlyExample:
25060The port on which the database cluster is listening.
userstring optional read-onlyExample:
doadminThe default user for the database.
Requiresdatabase:view_credentialsscope.passwordstring optional read-onlyExample:
example_passwordThe randomly generated password for the default user.
Requiresdatabase:view_credentialsscope.sslboolean optional read-onlyExample:
trueA boolean value indicating if the connection should be made over SSL.
standbyPrivateConnectionobject optional read-onlyShow child properties
uristring optional read-onlyExample:
postgres://doadmin:[email protected]:25060/defaultdb?sslmode=requireA connection string in the format accepted by the
psqlcommand. This is provided as a convenience and should be able to be constructed by the other attributes.databasestring optional read-onlyExample:
defaultdbThe name of the default database.
hoststring optional read-onlyExample:
db.example.comThe FQDN pointing to the database cluster's current primary node.
portinteger optional read-onlyExample:
25060The port on which the database cluster is listening.
userstring optional read-onlyExample:
doadminThe default user for the database.
Requiresdatabase:view_credentialsscope.passwordstring optional read-onlyExample:
example_passwordThe randomly generated password for the default user.
Requiresdatabase:view_credentialsscope.sslboolean optional read-onlyExample:
trueA boolean value indicating if the connection should be made over SSL.
usersarray of objects or null optional read-onlyShow child properties
namestring requiredExample:
app-01The name of a database user.
rolestring optional read-onlyA string representing the database user's role. The value will be either
"primary" or "normal".passwordstring optional read-onlyExample:
example_passwordA randomly generated password for the database user.
Requiresdatabase:view_credentialsscope.accessCertstring optional read-onlyExample:
-----BEGIN CERTIFICATE----- MIIEexampleCertificateNotForProductionUseOnly -----END CERTIFICATE-----Access certificate for TLS client authentication. (Kafka only)
accessKeystring optional read-onlyExample:
-----BEGIN PRIVATE KEY...Access key for TLS client authentication. (Kafka only)
mysqlSettingsobject optionalShow child properties
authPluginstring requiredA string specifying the authentication method to be used for connections
to the MySQL user account. The valid values aremysql_native_password
orcaching_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 iscaching_sha2_password.
settingsobject optionalShow child properties
pgAllowReplicationboolean optionalExample:
trueFor PostgreSQL clusters, set to
trueto grant the user replication
privileges. When omitted on create or update, the value defaults tofalseand replication privileges are not granted. This option is not
currently supported for other database engines.opensearchAclarray of objects optionalACLs (Access Control Lists) specifying permissions on index within a OpenSearch cluster.
Show child properties
indexstring optionalExample:
index-abc.*A regex for matching the indexes that this ACL should apply to.
permissionstring optionalPermission 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.
aclarray of objects optionalACLs (Access Control Lists) specifying permissions on topics within a Kafka cluster.
Show child properties
idstring optionalExample:
aaaAn identifier for the ACL. Will be computed after the ACL is created/updated.
topicstring requiredExample:
topic-abc.*A regex for matching the topic(s) that this ACL should apply to.
permissionstring requiredPermission 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).
mongoUserSettingsobject optionalMongoDB-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
databasesarray of strings optionalExample:
["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 rolereadOnlyassigned to theadmindatabase will have read access to all databases.rolestring optionalThe role to assign to the user with each role mapping to a MongoDB built-in role.
readOnlymaps to a read role.readWritemaps to a readWrite role.dbAdminmaps to a dbAdmin role.
maintenanceWindowobject or null optional read-onlyShow child properties
daystring requiredExample:
tuesdayThe day of the week on which to apply maintenance updates.
hourstring requiredExample:
14:00The hour in UTC at which maintenance updates will be applied in 24 hour format.
pendingboolean optional read-onlyExample:
trueA boolean value indicating whether any maintenance is scheduled to be performed in the next window.
descriptionarray of strings optional read-onlyExample:
["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.
projectIdstring optionalExample:
9cc10173-e9ea-4176-9dbc-a4cee4c4ff30The 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.
Requiresproject:assign_resourcescope.rulesarray of objects optionalShow child properties
uuidstring optionalExample:
79f26d28-ea8a-41f2-8ad8-8cfcdd020095A unique ID for the firewall rule itself.
clusterUuidstring optional read-onlyExample:
9cc10173-e9ea-4176-9dbc-a4cee4c4ff30A unique ID for the database cluster to which the rule is applied.
typestring requiredThe type of resource that the firewall rule allows to access the database cluster.
valuestring requiredExample:
ff2a6c52-5a44-4b63-b99c-0e98e7a63d61The 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.
createdAtstring optional read-onlyExample:
2019-01-11T18:37:36ZA time value given in ISO8601 combined date and time format that represents when the firewall rule was created.
descriptionstring optionalExample:
an IP address for local developmentA human-readable description of the rule.
versionEndOfLifestring optional read-onlyExample:
2023-11-09T00:00:00ZA 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.
versionEndOfAvailabilitystring optional read-onlyExample:
2023-05-09T00:00:00ZA 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.
storageSizeMibinteger optionalExample:
61440Additional 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.
metricsEndpointsarray of objects optional read-onlyPublic 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
hoststring optional read-onlyExample:
db.example.comA FQDN pointing to the database cluster's node(s).
portinteger optional read-onlyExample:
9273The port on which a service is listening.
autoscaleobject optionalAutoscaling configuration for the database cluster. Currently only supports storage autoscaling. If null, autoscaling is not configured for the cluster.
Show child properties
storageobject optionalConfiguration for database cluster storage autoscaling
doSettingsobject optionalDigitalOcean-specific settings for the database cluster.
Show child properties
serviceCnamesarray of strings optionalExample:
["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.
backupRestoreobject optionalShow child properties
databaseNamestring requiredExample:
backendThe name of an existing database cluster from which the backup will be restored.
backupCreatedAtstring optionalExample:
2019-01-31T19:25:22ZThe 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
Response Example
More Information
See /v2/databases in the API reference for additional detail on responses, headers, parameters, and more.