rds.instances.create

Create a database instance

POST /rds/api/instancesIAM rds:CreateDBInstanceChanges state

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

  • regionIdOptional

    string

    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

  • identifierRequired

    string

    Name of the database, unique within the organization

    Constraints: 3-48 chars, /^[a-z][a-z0-9-]*[a-z0-9]$/

  • instanceClassRequired

    string

    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

  • engineVersionOptional

    string

    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)$/

  • topologyOptional

    enum

    single: one node (the default); cluster: three nodes with automatic failover

    One of: single, cluster

    Default: "single"

  • dbNameOptional

    string

    Name of the database created inside the server; appdb when omitted

    Constraints: 1-63 chars, /^[a-z][a-z0-9_]*$/

    Default: "appdb"

  • masterUsernameOptional

    string

    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"

  • allocatedStorageGibOptional

    number

    Size of each node's data volume in GiB; 20 when omitted

    Constraints: integer, 10-4000

    Default: 20

  • maxAllocatedStorageGibOptional

    number

    Autoscaling ceiling in GiB, not below allocatedStorageGib; null or omitted leaves automatic growth off

    Constraints: integer, 10-10000

    May be null.

  • backupRetentionDaysOptional

    number

    Days backups are kept for restores; 0 turns scheduled backups off; 7 when omitted

    Constraints: integer, 0-35

    Default: 7

  • tagsOptional

    map of string

    Tags (key → value) for the database; its nodes' volumes inherit them

    Constraints: key=value

  • kmsKeyIdOptional

    string

    KMS key that wraps every node volume's key (needs kms:Encrypt on it); omitted: the platform key

    Constraints: uuid

  • publiclyAccessibleOptional

    boolean

    Whether the database answers on the internet; off by default: reachable only from its VPC

    Default: false

  • deletionProtectionOptional

    boolean

    Refuse delete until it is switched off again; off by default

    Default: false

  • requireTlsOptional

    boolean

    Refuse clients that do not use TLS, on both ports; on by default

    Default: true

  • replicationModeOptional

    enum

    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, sync

  • zonePlacementOptional

    enum

    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, single

  • logicalReplicationOptional

    boolean

    wal_level = logical from the first start, for CDC and publications; off by default

    Default: false

  • availabilityZoneIdOptional

    string

    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]$/

  • vpcIdOptional

    string

    VPC the database joins; omitted: the organization's default VPC for the region

    Constraints: uuid

  • subnetIdOptional

    string

    Subnet of that VPC to place the database in; omitted: the VPC's whole range

    Constraints: uuid

  • capacityFallbackOptional

    object

    What a create may fall back to when the provider is out of stock

    Constraints: JSON

  • onStockOutOptional

    enum

    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, wait

  • capacityMaxWaitHoursOptional

    number

    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

  • idAlways

    string

    Database id (ewdb-…)
  • orgIdAlways

    string

    Organization that owns the database
  • identifierAlways

    string

    Name of the database, unique within the organization
  • engineAlways

    one of postgres, docdb

    Database engine; postgres for every managed PostgreSQL database
  • engineVersionAlways

    string

    PostgreSQL version the database is on, a pinned minor such as 17.11
  • instanceClassAlways

    string

    Instance type of every node, e.g. performance-2
  • regionIdAlways

    string

    Region the database is in, e.g. de1
  • availabilityZoneIdAlways

    string, may be null

    Zone asked for at create (e.g. de1b); null: the region's default zone, or spread over the zones for a cluster
  • vpcIdAlways

    string, may be null

    VPC the database joins; null: none
  • subnetIdAlways

    string, may be null

    Subnet of that VPC its addresses come from; null: the VPC's whole range
  • dbNameAlways

    string, may be null

    Database created inside the server at launch
  • masterUsernameAlways

    string

    Name of the master role, whose password is filed in Secrets
  • allocatedStorageGibAlways

    number

    Size of each node's data volume, GiB
  • maxAllocatedStorageGibAlways

    number, may be null

    Autoscaling ceiling, GiB; null: automatic growth is off
  • storageTypeAlways

    string

    Storage class label; informational
  • iopsAlways

    number, may be null

    Provisioned IOPS; not offered, so null
  • multiAzAlways

    boolean

    Not used: zonePlacement says how a cluster is spread over zones
  • publiclyAccessibleAlways

    boolean

    Whether the database answers on the internet; false: only from its VPC
  • topologyAlways

    one of single, cluster

    single: one node; cluster: three nodes with automatic failover
  • nodeCountAlways

    number

    Core nodes: 1 for single, 3 for a cluster (readers not counted)
  • masterSecretIdAlways

    string, may be null

    Secret holding the master password; null until it is filed
  • loadBalancerIdAlways

    string, may be null

    Load balancer in front of a cluster, on the platform's own fleet; null otherwise
  • endpointKindAlways

    one 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 node
  • hetznerLoadBalancerIdAlways

    number, may be null

    The provider's id of a cluster's load balancer; null when there is none
  • hetznerNetworkIdAlways

    number, may be null

    The provider's id of the private network a cluster's members talk over; null on a single node
  • hetznerFirewallIdAlways

    number, may be null

    The provider's id of the database's firewall; null before it exists
  • reconcileErrorAlways

    string, may be null

    Why the last provisioning or teardown step failed; null when nothing failed
  • capacityFallbackAlways

    object

    What the create could fall back to when its type was sold out
  • capacityFallback.​otherZonesAlways

    boolean

    A sold-out zone may be replaced by another zone of the region
  • capacityFallback.​equivalentTypesAlways

    boolean

    A sold-out instance type may be replaced by an equivalent one
  • onStockOutAlways

    one of fail, wait

    Sold out with no fallback: fail the create, or wait for stock
  • capacityWaitUntilAlways

    string, may be null

    While waiting for stock: when the create gives up; null otherwise
  • requestedInstanceClassAlways

    string, may be null

    The instance type asked for, when a stock fallback bought another; null otherwise
  • statusAlways

    one of available, creating, modifying, backing-up, deleting, failed, stopped, starting, stopping, rebooting, maintenance, waiting-for-capacity, retained

    State of the database
  • retainedUntilAlways

    string, may be null

    For a retained database: when its backups are removed; null otherwise
  • endpointAddressAlways

    string, may be null

    Address clients connect to; null until the database is reachable
  • endpointPortAlways

    number, may be null

    Direct PostgreSQL port of the endpoint (5432); the pooler is on 6432
  • privateEndpointAddressAlways

    string, may be null

    The database's address inside its VPC, named in its certificate; null: use endpointAddress
  • parameterGroupIdAlways

    string, may be null

    Not used; parameters holds your values
  • backupRetentionDaysAlways

    number

    Days backups are kept; 0: scheduled backups are off
  • backupsEnabledAlways

    boolean

    Whether scheduled backups are taken
  • storageEncryptedAlways

    boolean

    Whether every node's data volume is encrypted at rest
  • storageKmsKeyIdAlways

    string, may be null

    KMS key that wraps every node volume's key; null: the platform key
  • backupAgentSeenAtAlways

    string, may be null

    When a node last asked for backup work; null: never
  • backupPollerVersionAlways

    number, 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 reported
  • lastBackupAtAlways

    string, may be null

    When the newest backup finished; null: never
  • backupWindowAlways

    string, may be null

    When the daily backup runs, UTC HH:MM-HH:MM (only the start is used)
  • maintenanceWindowAlways

    string, may be null

    Maintenance window, UTC ddd:hh24:mi-ddd:hh24:mi
  • deletionProtectionAlways

    boolean

    While true, delete is refused
  • performanceInsightsEnabledAlways

    boolean

    Not used; query insights are always on
  • autoMinorVersionUpgradeAlways

    boolean

    Whether new minor versions are applied in the maintenance window
  • parametersAlways

    map

    Your PostgreSQL parameter values by name; parameters not named keep their default
  • caCertIdentifierAlways

    string, may be null

    Name of the CA that signs the server certificate
  • tlsSerialAlways

    string, may be null

    Serial of the server certificate; null: the database has no certificate
  • tlsNotAfterAlways

    string, may be null

    When the server certificate expires
  • tlsNamesInCertAlways

    boolean

    Whether the certificate names the database's DNS endpoint names
  • tlsRequiredAlways

    boolean

    Whether clients that do not use TLS are refused
  • replicationModeAlways

    one of async, sync, may be null

    sync: a commit waits for one standby; async: it does not; null on a single node
  • zonePlacementAlways

    one of spread, single, may be null

    spread: members over the zones; single: all in one zone; null on a single node
  • logicalReplicationAlways

    boolean

    Whether wal_level is logical, for CDC and publications
  • branchPoolOfAlways

    string, may be null

    Set on the machine that serves the branches of another database: that database; null otherwise
  • branchSettingsAlways

    unknown

    Branch settings as stored (branch-settings reads them); null: the defaults
  • launchedAtAlways

    string, may be null

    When the database first became available
  • tagsAlways

    string, may be null

    Kept for compatibility; the tags API holds the tags of the database
  • createdAtAlways

    string

    When the database was created
  • updatedAtAlways

    string

    When the database record last changed
  • encryptionAlways

    object

    What is encrypted at rest
  • encryption.​storageAlways

    one of luks2, none

    luks2: every node's data volume is encrypted with a per-volume key from KMS; none: created before disk encryption
  • encryption.​backupsAlways

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