Create a database
Create a PostgreSQL database, single node or a three-node cluster, in a private network or reachable from the internet.
The master password is generated, filed in Secrets and never shown at creation; see Manage the master password. Replace orders with your database's name.
Important
The topology, zones, network, public reachability, encryption key and master username are fixed when the database is created. You pay for every node from the moment it is built.
Prerequisites
- Permission for
rds:CreateDBInstance. - To use your own encryption key,
kms:Encrypton that key. - For a cluster, an instance class with at least 8 GiB of memory.
- Room in the
rds.db-instancesquota of the region (DB instances per region; restores count). - Any tag keys your organization requires.
- In the console, also
rds:DescribeDBInstancesto open Postgres (without it the console shows Access denied and names that action).
Create the database
- Open Postgres, then choose Create Postgres database.
- Under Basics, for Name, enter orders.
- (Optional) For Initial database and Master user, enter names of your own.
- Under Size, choose Single node or Cluster (3 nodes).
- For a cluster, select or clear Synchronous replication and Spread over zones.
- For Machine type, choose a type. For a single node, or a cluster not spread over zones, choose its Zone too.
- (Optional) Open Capacity to change what happens if the type is sold out; see When the machine type is sold out.
- Under Storage, for Initial size (GiB), enter the size. (Optional) For Grow automatically up to (GiB), change the ceiling (100 by default) or empty it to keep growth off.
- Under Security, select Reachable from the internet only if clients outside the network must connect, keep Require TLS selected, and (optional) choose an Encryption key.
- (Optional) Open Advanced and select Logical replication for CDC and publications.
- Choose Create database.
The database page opens with the status creating. The form shows the monthly cost before you
create; the button stays disabled and names what is left to fix until every field is valid.
dcloud rds instances create --identifier orders --instance-class performance-2 \
--db-name orders --master-username orders_admin \
--allocated-storage-gib 20 --max-allocated-storage-gib 100 --backup-retention-days 7A cluster: add --topology cluster and a class with 8 GiB or more, such as performance-4.
POST /rds/api/instances
{
"identifier": "orders",
"instanceClass": "performance-2",
"topology": "single",
"dbName": "orders",
"masterUsername": "orders_admin",
"allocatedStorageGib": 20,
"maxAllocatedStorageGib": 100,
"backupRetentionDays": 7,
"publiclyAccessible": false
}resource "dcloud_db_instance" "orders" {
identifier = "orders"
instance_class = "performance-2"
engine_version = "17"
allocated_storage_gib = 20
max_allocated_storage_gib = 100
backup_retention_days = 7
deletion_protection = true
}The engine version, backup retention, deletion protection, network and tags are set through the CLI, API or Terraform at creation; the console sends none of them, so the database gets PostgreSQL 17, 7 days of backups, no deletion protection and the default network.
The create request
| Field | Rule | Default |
|---|---|---|
identifier |
3–48 characters, a-z, 0-9, -; starts with a letter, does not end with - |
required |
instanceClass |
one of GET /rds/api/server-types; an unknown one is refused. Stock is handled at build time (below) |
required |
engineVersion |
a major (15, 16, 17, 18) or an offered minor (18.7, 17.12, 17.11, 16.16, 15.20); anything else is refused |
17, newest minor |
topology |
single or cluster |
single |
dbName |
1–63 characters, a-z, 0-9, _; starts with a letter |
appdb |
masterUsername |
same rule as dbName |
admin |
allocatedStorageGib |
10–4000 | 20 |
maxAllocatedStorageGib |
10–10 000, never below allocatedStorageGib; null or omitted leaves automatic growth off |
none |
backupRetentionDays |
0–35 | 7 |
publiclyAccessible |
boolean | false |
deletionProtection |
boolean; while on, delete is refused | false |
requireTls |
boolean; refuse clients that do not use TLS | true |
kmsKeyId |
one of your KMS keys; wraps every node volume's key | the platform key |
replicationMode |
sync or async; cluster only, refused for a single node |
sync (cluster) |
zonePlacement |
spread or single; cluster only. spread puts members in de1a, de1b, de1a |
spread (cluster) |
availabilityZoneId |
a zone of the region (de1a, de1b): a single node's zone, or a single cluster's; a spread cluster accepts only the default zone |
the region's default zone (de1a) |
logicalReplication |
boolean; wal_level = logical from the start |
false |
vpcId |
a network in your organization, in the same region; the database gets a private address in it | the default network |
subnetId |
a subnet of that network | none |
regionId |
de1, or fi1 when your organization allows it |
the request's region |
tags |
key/value map; required keys of your organization must be present | none |
When the machine type is sold out
The provider sells from live stock per zone. The create form shows it under Machine type, for example "performance-4 is sold out in de1a, available in de1b", and offers the other zone. The create request itself does not check stock: the database is accepted and the check runs when it is built. What happens then if the type is sold out is set at creation:
{ "capacityFallback": { "otherZones": true, "equivalentTypes": false }, "onStockOut": "wait", "capacityMaxWaitHours": 24 }Tried in this order, before anything is built:
otherZones: a member whose zone is sold out goes in a zone that sells the type. A spread cluster may then have members sharing a zone; its events say so.equivalentTypes: an equivalent class (same CPU architecture, same class or better, at least the vCPUs and memory, at most 1.25× the price plus 5 cents).requestedInstanceClasskeeps what you asked for;instanceClassis what was bought and is billed.onStockOut: "wait": the database iswaiting-for-capacity. Nothing is built or billed. Provisioning starts within a minute of the class coming back where it goes, or the database fails atcapacityMaxWaitHours(1 to 168, default 24). Deleting it cancels.
Without any of these (the API default) the database goes to failed before anything is built.
The console sends equivalentTypes: true, otherZones: false, onStockOut: "wait" and 24 hours;
its Capacity section changes them. A fallback or a wait raises an Insufficient Capacity
event and counts in EWS/Capacity InsufficientCapacityErrors; see
Compute → Hear about stock-outs.
Create in Helsinki (fi1)
Databases are in Germany (de1) unless your organization decides otherwise. After an
administrator turns on Allow EU locations outside Germany (Settings → Data location), create
with "regionId": "fi1" (or the header X-EWS-Region: fi1, CLI --region fi1). Its machines,
disks and backups stay in Helsinki, Finland; the console marks the database
"outside Germany · Finland". Without the setting the create answers 403 before anything is
ordered: "Region fi1 (Helsinki, Finland) is outside Germany: an administrator has to allow EU
locations outside Germany first (Settings → Data location)".
fi1 has one zone, fi1a. A restore or a branch of a database in fi1 is placed in fi1 too, and needs
the setting to be on at that moment. Turning the setting off moves nothing: the database keeps
running and can be changed and deleted.
Result
The response (201) carries the database in status creating, or it moves to
waiting-for-capacity if it waits for stock. It turns available when its endpoint answers, with
the event "Database is available"; every step is on Activity. When the primary has finished
setting up, it starts the first full backup.
When the create is refused
| Answer | Message | Cause |
|---|---|---|
| 400 | Unknown server type: <class> |
the class is not in the catalog |
| 400 | <class> has <n> GiB; a cluster needs at least 8 GiB per node |
a cluster on a class under 8 GiB |
| 400 | replicationMode requires the cluster topology: a single node has no standby. |
replicationMode on a single node |
| 400 | The autoscaling ceiling cannot be below the initial size of <n> GiB. |
maxAllocatedStorageGib below allocatedStorageGib |
| 400 | Missing required tags: <keys> |
a tag key your organization requires is missing |
| 403 | Forbidden |
no rds:CreateDBInstance, or no kms:Encrypt on the key |
| 404 | Network not found |
vpcId is not a network of yours |
| 409 | A database named "<name>" already exists |
the identifier is taken in your organization |
| 409 | code QuotaExceeded |
the rds.db-instances quota of the region is used up |