# Add or remove a reader

Add read capacity to a cluster with extra replicas that serve on the read ports and never become the leader.

A reader is one more machine of the cluster's machine type that streams from the leader and, once it
has caught up, serves on the read ports (`6433` pooled, `5433` direct), shared with the cluster's
standbys. It is never promoted, and it never counts towards a synchronous commit, so the cluster's
failover and its `sync` guarantee do not depend on it. Replace _ewdb-0123456789ab_ with your
database's id.

**Important:**
Each reader is another machine and data volume of the cluster's machine type, billed like the
cluster's other nodes.

## Prerequisites

- A cluster in status `available`. A single node has no readers.
- Permission for `rds:CreateDBReadReplica`, or `rds:DeleteDBReadReplica` to remove one. The
  console shows **Add reader** and the remove button only to someone who has them.
- Room in the `rds.read-replicas` quota: five readers per cluster on a standard account, one on a
  trial (see [Quotas](quotas.md)). Five is also the hard ceiling; the quota cannot be raised.
- Stock of the cluster's machine type in its region.
- In the console, also `rds:DescribeDBInstances` to open the database's page (without it the page is
  not found).

## Add a reader

**Console**
1. Open the database, then choose the **Nodes** tab.
2. Choose **Add reader**. There is no confirmation; the request is sent at once. The button is
   disabled once the cluster has five readers.

**CLI**
```sh
dcloud rds instances add-reader ewdb-0123456789ab
```

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/readers
```

The answer is `202` with the new node.

**Terraform**
```hcl
resource "dcloud_db_read_replica" "reporting" {
  db_instance_id = dcloud_db_instance.orders.id
}
```

The new node appears on **Nodes** with the role `reader` and is built like any other node; it takes
read traffic once it streams from the leader. How long that takes depends on how much data it has
to copy. On a cluster spread over zones, readers continue the round-robin of the members (the first
reader goes to `de1b`), so the read ports have a member in each zone.

The request is refused when:

| Answer | Message                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------------------- |
| `400`  | `Readers join a cluster. A single-node database has no Patroni to join; restore it into a cluster first.` |
| `409`  | `Cannot add a reader while the database is <status>`                                                      |
| `409`  | the machine type is not available in the region (the stock message)                                       |
| `409`  | `Quota exceeded: Read replicas per database (rds.read-replicas) — …`, with `code: "QuotaExceeded"`        |

## Remove a reader

**Console**
1. On the **Nodes** tab, choose the bin icon on the reader's row (**Remove reader** _name_).
2. Confirm `Remove reader <name>? Its machine and volume are deleted.`

**CLI**
```sh
dcloud rds instances remove-reader ewdb-0123456789ab node-id
```

Take the node id from `dcloud rds instances list-nodes`.

**API**
```http
DELETE /rds/api/instances/ewdb-0123456789ab/readers/3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f
```

The answer is `202` with the node's id and `status: "deleting"`.

**Terraform**
Remove the `dcloud_db_read_replica` resource and run `terraform apply`.

Its machine and then its data volume are deleted. Only readers can be removed: naming one of the
three core members is refused with `400` and `<name> is one of the cluster's three core members, not
a reader`.

## Result

**Activity** (phase `readers`) records `Reader <name> requested` when you add one and
`Reader <name> removed, with its volume` when it is gone. A reader that is being removed leaves the
read ports once its member drops out of the cluster, before its machine is deleted.

Readers must be removed before a major version upgrade: the upgrade is refused with `409` and
`Remove the readers before a major upgrade; add them again afterwards`.

## Related

- [Instances, clusters and endpoints](instances-and-clusters.md)
- `rds.instances.add-reader` · `dcloud rds instances add-reader` · `dcloud_db_read_replica`
