# Resize a database

Grow storage, turn on storage autoscaling, or change the machine type of a database.

Replace _ewdb-0123456789ab_ with your database's id.

**Important:**
Storage only grows; it cannot be shrunk. A larger volume or machine costs more from the moment it
is in place.

## Prerequisites

- Permission for `rds:ModifyDBInstance`.
- For a machine type change, the database is **available**. Otherwise it is refused with `409`
  "Cannot change the machine type while the database is …".

## Grow storage or set the autoscaling ceiling

**CLI**
```sh
dcloud rds instances modify-storage ewdb-0123456789ab \
  --allocated-storage-gib 100 --max-allocated-storage-gib 500
```

**API**
```http
PATCH /rds/api/instances/ewdb-0123456789ab/storage
{ "allocatedStorageGib": 100, "maxAllocatedStorageGib": 500 }
```

**Terraform**
```hcl
resource "dcloud_db_instance" "orders" {
  identifier                = "orders"
  instance_class            = "performance-2"
  allocated_storage_gib     = 100
  max_allocated_storage_gib = 500
}
```

**Console:** not available. The console sets the ceiling at creation (**Grow automatically up to (GiB)**); changing storage later is in the CLI, API and Terraform.

Setting `maxAllocatedStorageGib` turns on autoscaling, and `null` turns it off: when a node reports
its data volume 80 % full, every node's volume grows by half again, up to the ceiling, without a
restart. Each node reports its disk usage every five minutes, and its filesystem follows a grown
volume at its next report. Each step is on **Activity** (phase `storage`).

A smaller `allocatedStorageGib` is refused with `400` "Storage can only grow. It is currently _n_
GiB.", and a ceiling below the size with `400` "The autoscaling ceiling cannot be below current
storage".

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| Size                | 10–4000 GiB at creation, up to 10 000 GiB on request; or automatically |
| Autoscaling ceiling | `maxAllocatedStorageGib`, 10–10 000 GiB, never below the current size  |
| Autoscaling trigger | 80 % full                                                              |
| Autoscaling step    | ×1.5, capped at the ceiling                                            |
| Shrinking           | not possible                                                           |
| Encryption at rest  | LUKS2 (AES-256-XTS) on every node's data volume, key per volume        |

When storage grows, the encrypted mapping grows with the volume, then the filesystem, without a
restart.

## Change the machine type

Any type from `rds.server-types.list` that is in stock; a cluster needs one with at least 8 GiB
of memory (`clusterCapable`). Otherwise the change is refused with `400` "… has too little memory
for a cluster member", `400` "… is not an offered machine type", `400` "The database already runs
…", or `409` when the type is out of stock.

**CLI**
```sh
dcloud rds instances modify-instance-class ewdb-0123456789ab --instance-class performance-8
```

**API**
```http
PATCH /rds/api/instances/ewdb-0123456789ab/instance-class
{ "instanceClass": "performance-8" }
```

**Terraform**
```hcl
resource "dcloud_db_instance" "orders" {
  identifier     = "orders"
  instance_class = "performance-8"
}
```

**Console:** not available. Changing the machine type is not in the console yet.

Each machine has to be off to change type:

- **Cluster:** one node at a time, replicas first, each streaming again before the next goes down,
  then a switchover to a node already on the new type, then the old leader. The database stays
  available; writes fail for the switchover (a few seconds).
- **Single node:** the database is unavailable for one power cycle onto the new type.

Memory-sized parameter defaults (`shared_buffers` and the others) move with the machine size; your
own values stay as you set them. See [Tune parameters](tune-parameters.md).

## Result

A machine type change answers `202`. The database is `modifying` meanwhile, and each step is on
**Activity** (phase `resize`), ending with "Machine type changed to … in _n_ min". If a step fails,
the database returns to `available`, the event "Changing the machine type stopped: …" says which
type each node runs, and asking again finishes the rest: nodes already on the new type are
skipped.

A storage change is applied to the volumes during the request; the database stays `available`.

## Related

- [Benchmarks](benchmarks.md): what each machine type delivers.
- `rds.instances.modify-storage` · `rds.instances.modify-instance-class` · `dcloud_db_instance`
