rds.instances.createCreate a database instance
Request syntax
POST /rds/api/instances
{
"regionId": "string",
"identifier": "string",
"instanceClass": "string",
"engineVersion": "string",
"topology": "enum",
"dbName": "string",
"masterUsername": "string",
"allocatedStorageGib": "number",
"maxAllocatedStorageGib": "number",
"backupRetentionDays": "number",
"tags": "map of string",
"kmsKeyId": "string",
"publiclyAccessible": "boolean",
"deletionProtection": "boolean",
"requireTls": "boolean",
"replicationMode": "enum",
"zonePlacement": "enum",
"logicalReplication": "boolean",
"availabilityZoneId": "string",
"vpcId": "string",
"subnetId": "string",
"capacityFallback": "object",
"onStockOut": "enum",
"capacityMaxWaitHours": "number"
}Request body
regionIdOptionalstring
Region to create in (default: the X-EWS-Region header, else de1). fi1 (Helsinki, Finland) needs the organization setting "allow EU outside Germany".
Constraints: 1-32 chars
identifierRequiredstring
Name of the database, unique within the organization
Constraints: 3-48 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/
instanceClassRequiredstring
Instance type of every node, from server-types (e.g. performance-2; the provider’s own names are still accepted, deprecated); a cluster needs one with at least 8 GiB of memory
Constraints: 1-32 chars
engineVersionOptionalstring
PostgreSQL major (e.g. 17, installed at its current pinned minor) or one of its pinned minors (e.g. 17.11); omitted: PostgreSQL 17
Constraints: max 16 chars, /^(18|17|16|15|18\.7|17\.12|17\.11|16\.16|15\.20)$/
topologyOptionalenum
single: one node (the default); cluster: three nodes with automatic failover
One of:
single,clusterDefault:
"single"dbNameOptionalstring
Name of the database created inside the server; appdb when omitted
Constraints: 1-63 chars, /^[a-z][a-z0-9_]*$/
Default:
"appdb"masterUsernameOptionalstring
Name of the master role, whose password is filed in Secrets; admin when omitted
Constraints: 1-63 chars, /^[a-z][a-z0-9_]*$/
Default:
"admin"allocatedStorageGibOptionalnumber
Size of each node's data volume in GiB; 20 when omitted
Constraints: integer, 10-4000
Default:
20maxAllocatedStorageGibOptionalnumber
Autoscaling ceiling in GiB, not below allocatedStorageGib; null or omitted leaves automatic growth off
Constraints: integer, 10-10000
May be null.
backupRetentionDaysOptionalnumber
Days backups are kept for restores; 0 turns scheduled backups off; 7 when omitted
Constraints: integer, 0-35
Default:
7tagsOptionalmap of string
Tags (key → value) for the database; its nodes' volumes inherit them
Constraints: key=value
kmsKeyIdOptionalstring
KMS key that wraps every node volume's key (needs kms:Encrypt on it); omitted: the platform key
Constraints: uuid
publiclyAccessibleOptionalboolean
Whether the database answers on the internet; off by default: reachable only from its VPC
Default:
falsedeletionProtectionOptionalboolean
Refuse delete until it is switched off again; off by default
Default:
falserequireTlsOptionalboolean
Refuse clients that do not use TLS, on both ports; on by default
Default:
truereplicationModeOptionalenum
Cluster only. sync (the default for a cluster): a commit waits for one standby, so a failover loses nothing acknowledged; async: lower commit latency
One of:
async,synczonePlacementOptionalenum
Cluster only, fixed after creation. spread (the default for a cluster): members round-robin over the region's zones; single: all in availabilityZoneId
One of:
spread,singlelogicalReplicationOptionalboolean
wal_level = logical from the first start, for CDC and publications; off by default
Default:
falseavailabilityZoneIdOptionalstring
Zone of a single node or of a single-placement cluster, e.g. de1b; omitted: the region's default zone
Constraints: /^[a-z]+[0-9]+[a-z]$/
vpcIdOptionalstring
VPC the database joins; omitted: the organization's default VPC for the region
Constraints: uuid
subnetIdOptionalstring
Subnet of that VPC to place the database in; omitted: the VPC's whole range
Constraints: uuid
capacityFallbackOptionalobject
What a create may fall back to when the provider is out of stock
Constraints: JSON
onStockOutOptionalenum
When the type is sold out where it goes and no fallback applies: fail at once (default), or wait as waiting-for-capacity (nothing built or billed) until it is back
One of:
fail,waitcapacityMaxWaitHoursOptionalnumber
With onStockOut wait: give up after this many hours (1–168, default 24)
Constraints: integer, 1-168
Response
201 with the new database (status `creating`): id, identifier, engineVersion, instanceClass, topology, nodeCount, regionId, allocatedStorageGib, masterSecretId, encryption, … . Provisioning continues in the background; follow it with `get` or `events`.
A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.
Fields of data
idAlwaysstring
Database id (ewdb-…)orgIdAlwaysstring
Organization that owns the databaseidentifierAlwaysstring
Name of the database, unique within the organizationengineAlwaysone of postgres, docdb
Database engine; postgres for every managed PostgreSQL databaseengineVersionAlwaysstring
PostgreSQL version the database is on, a pinned minor such as 17.11instanceClassAlwaysstring
Instance type of every node, e.g. performance-2regionIdAlwaysstring
Region the database is in, e.g. de1availabilityZoneIdAlwaysstring, may be null
Zone asked for at create (e.g. de1b); null: the region's default zone, or spread over the zones for a clustervpcIdAlwaysstring, may be null
VPC the database joins; null: nonesubnetIdAlwaysstring, may be null
Subnet of that VPC its addresses come from; null: the VPC's whole rangedbNameAlwaysstring, may be null
Database created inside the server at launchmasterUsernameAlwaysstring
Name of the master role, whose password is filed in SecretsallocatedStorageGibAlwaysnumber
Size of each node's data volume, GiBmaxAllocatedStorageGibAlwaysnumber, may be null
Autoscaling ceiling, GiB; null: automatic growth is offstorageTypeAlwaysstring
Storage class label; informationaliopsAlwaysnumber, may be null
Provisioned IOPS; not offered, so nullmultiAzAlwaysboolean
Not used: zonePlacement says how a cluster is spread over zonespubliclyAccessibleAlwaysboolean
Whether the database answers on the internet; false: only from its VPCtopologyAlwaysone of single, cluster
single: one node; cluster: three nodes with automatic failovernodeCountAlwaysnumber
Core nodes: 1 for single, 3 for a cluster (readers not counted)masterSecretIdAlwaysstring, may be null
Secret holding the master password; null until it is filedloadBalancerIdAlwaysstring, may be null
Load balancer in front of a cluster, on the platform's own fleet; null otherwiseendpointKindAlwaysone of hetzner-lb, fleet, may be null
What a cluster's endpoint is: fleet (the platform's own load balancer) or hetzner-lb (the provider's); null on a single nodehetznerLoadBalancerIdAlwaysnumber, may be null
The provider's id of a cluster's load balancer; null when there is nonehetznerNetworkIdAlwaysnumber, may be null
The provider's id of the private network a cluster's members talk over; null on a single nodehetznerFirewallIdAlwaysnumber, may be null
The provider's id of the database's firewall; null before it existsreconcileErrorAlwaysstring, may be null
Why the last provisioning or teardown step failed; null when nothing failedcapacityFallbackAlwaysobject
What the create could fall back to when its type was sold outcapacityFallback.otherZonesAlwaysboolean
A sold-out zone may be replaced by another zone of the regioncapacityFallback.equivalentTypesAlwaysboolean
A sold-out instance type may be replaced by an equivalent oneonStockOutAlwaysone of fail, wait
Sold out with no fallback: fail the create, or wait for stockcapacityWaitUntilAlwaysstring, may be null
While waiting for stock: when the create gives up; null otherwiserequestedInstanceClassAlwaysstring, may be null
The instance type asked for, when a stock fallback bought another; null otherwisestatusAlwaysone of available, creating, modifying, backing-up, deleting, failed, stopped, starting, stopping, rebooting, maintenance, waiting-for-capacity, retained
State of the databaseretainedUntilAlwaysstring, may be null
For a retained database: when its backups are removed; null otherwiseendpointAddressAlwaysstring, may be null
Address clients connect to; null until the database is reachableendpointPortAlwaysnumber, may be null
Direct PostgreSQL port of the endpoint (5432); the pooler is on 6432privateEndpointAddressAlwaysstring, may be null
The database's address inside its VPC, named in its certificate; null: use endpointAddressparameterGroupIdAlwaysstring, may be null
Not used; parameters holds your valuesbackupRetentionDaysAlwaysnumber
Days backups are kept; 0: scheduled backups are offbackupsEnabledAlwaysboolean
Whether scheduled backups are takenstorageEncryptedAlwaysboolean
Whether every node's data volume is encrypted at reststorageKmsKeyIdAlwaysstring, may be null
KMS key that wraps every node volume's key; null: the platform keybackupAgentSeenAtAlwaysstring, may be null
When a node last asked for backup work; null: neverbackupPollerVersionAlwaysnumber, may be null
Version of the backup service on the nodes; 3 and up keep a backup taken by hand until it is deleted; null: not reportedlastBackupAtAlwaysstring, may be null
When the newest backup finished; null: neverbackupWindowAlwaysstring, may be null
When the daily backup runs, UTC HH:MM-HH:MM (only the start is used)maintenanceWindowAlwaysstring, may be null
Maintenance window, UTC ddd:hh24:mi-ddd:hh24:mideletionProtectionAlwaysboolean
While true, delete is refusedperformanceInsightsEnabledAlwaysboolean
Not used; query insights are always onautoMinorVersionUpgradeAlwaysboolean
Whether new minor versions are applied in the maintenance windowparametersAlwaysmap
Your PostgreSQL parameter values by name; parameters not named keep their defaultcaCertIdentifierAlwaysstring, may be null
Name of the CA that signs the server certificatetlsSerialAlwaysstring, may be null
Serial of the server certificate; null: the database has no certificatetlsNotAfterAlwaysstring, may be null
When the server certificate expirestlsNamesInCertAlwaysboolean
Whether the certificate names the database's DNS endpoint namestlsRequiredAlwaysboolean
Whether clients that do not use TLS are refusedreplicationModeAlwaysone of async, sync, may be null
sync: a commit waits for one standby; async: it does not; null on a single nodezonePlacementAlwaysone of spread, single, may be null
spread: members over the zones; single: all in one zone; null on a single nodelogicalReplicationAlwaysboolean
Whether wal_level is logical, for CDC and publicationsbranchPoolOfAlwaysstring, may be null
Set on the machine that serves the branches of another database: that database; null otherwisebranchSettingsAlwaysunknown
Branch settings as stored (branch-settings reads them); null: the defaultslaunchedAtAlwaysstring, may be null
When the database first became availabletagsAlwaysstring, may be null
Kept for compatibility; the tags API holds the tags of the databasecreatedAtAlwaysstring
When the database was createdupdatedAtAlwaysstring
When the database record last changedencryptionAlwaysobject
What is encrypted at restencryption.storageAlwaysone of luks2, none
luks2: every node's data volume is encrypted with a per-volume key from KMS; none: created before disk encryptionencryption.backupsAlwaysone of aes-256-cbc, none
aes-256-cbc: backups are encrypted on the database machine before upload; none: created before backup encryption
Checked against the handlers: every route test validates their answers against this schema.
Errors
- 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
- 401No credentials, or an access key that is unknown, revoked or expired.
- 403The caller's policies do not allow rds:CreateDBInstance on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
- 404The resource does not exist in your organization.
Examples
The required parameters only, with example values. Replace id and the other placeholders with your own.
dcloud rds instances create --identifier example --instance-class examplecurl -X POST "https://console.platform-development.deutschecloud.app/rds/api/instances" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"identifier":"example","instanceClass":"example"}'Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_rds_instances_create.