# 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](manage-the-master-password.md). 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:Encrypt` on that key.
- For a cluster, an instance class with at least 8 GiB of memory.
- Room in the `rds.db-instances` quota of the region (DB instances per region; restores count).
- Any tag keys your organization requires.
- In the console, also `rds:DescribeDBInstances` to open **Postgres** (without it the console shows
  **Access denied** and names that action).

## Create the database

**Console**
1. Open **Postgres**, then choose **Create Postgres database**.
2. Under **Basics**, for **Name**, enter orders.
3. (Optional) For **Initial database** and **Master user**, enter names of your own.
4. Under **Size**, choose **Single node** or **Cluster (3 nodes)**.
5. For a cluster, select or clear **Synchronous replication** and **Spread over zones**.
6. For **Machine type**, choose a type. For a single node, or a cluster not spread over zones,
   choose its **Zone** too.
7. (Optional) Open **Capacity** to change what happens if the type is sold out; see
   [When the machine type is sold out](#when-the-machine-type-is-sold-out).
8. 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.
9. 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**.
10. (Optional) Open **Advanced** and select **Logical replication** for CDC and publications.
11. 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.

**CLI**
```sh
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 7
```

A cluster: add `--topology cluster` and a class with 8 GiB or more, such as `performance-4`.

**API**
```http
POST /rds/api/instances
{
  "identifier": "orders",
  "instanceClass": "performance-2",
  "topology": "single",
  "dbName": "orders",
  "masterUsername": "orders_admin",
  "allocatedStorageGib": 20,
  "maxAllocatedStorageGib": 100,
  "backupRetentionDays": 7,
  "publiclyAccessible": false
}
```

**Terraform**
```hcl
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:

```json
{ "capacityFallback": { "otherZones": true, "equivalentTypes": false }, "onStockOut": "wait", "capacityMaxWaitHours": 24 }
```

Tried in this order, before anything is built:

1. `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.
2. `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). `requestedInstanceClass` keeps what
   you asked for; `instanceClass` is what was bought and is billed.
3. `onStockOut: "wait"`: the database is `waiting-for-capacity`. Nothing is built or billed.
   Provisioning starts within a minute of the class coming back where it goes, or the database
   fails at `capacityMaxWaitHours` (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](/docs/ec2/guide/monitoring).

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

## Related

- [Instances, clusters and endpoints](instances-and-clusters.md)
- [Versions and maintenance](versions-and-maintenance.md)
- [Connect to a database](connect.md)
- `rds.instances.create` · `dcloud rds instances create` · `dcloud_db_instance`
