# Choose synchronous or asynchronous replication

Decide whether a cluster's commits wait for a standby, so that a failover loses nothing acknowledged, or return as soon as the leader has them.

A cluster replicates **synchronously** unless you choose otherwise when you create it. Replace
_ewdb-0123456789ab_ with your database's id.

- `sync`: a commit returns once the leader and one of the two standbys have it on disk. A failover
  only promotes a standby that has every acknowledged commit, so nothing you were told is committed
  is lost. Each commit takes one network round trip to a standby longer.
- `async`: a commit returns once the leader has it. A failover can lose the writes that had not
  reached a standby yet (at most 1 MiB of WAL).

What each costs in throughput is in [Benchmarks](benchmarks.md).

## Prerequisites

- A cluster. On a single node the request is refused with `409` "A single-node database has no
  standby to replicate to.", and the console shows no **Replication** section.
- Permission for `rds:ModifyDBInstance`. Without it the switch is disabled: "Your policies do not
  grant rds:ModifyDBInstance."
- The database is **available**. Otherwise it is refused with `409` "This database is ….
  Replication can be changed once it is available."
- In the console, also `rds:DescribeDBInstances` to open the database's page (without it the page is
  not found).

## Change the mode

**Console**
1. Open the database, then choose the **Nodes** tab.
2. Under **Replication**, turn **Synchronous replication** on or off. The change is saved and
   applied at once; there is no confirmation. The badge beside the label shows **holding** (with
   the standby that acknowledges), **degraded**, **off** or **unknown**.

**CLI**
```sh
dcloud rds replication set ewdb-0123456789ab --replication-mode sync
```

**API**
```http
PATCH /rds/api/instances/ewdb-0123456789ab/replication
{ "replicationMode": "sync" }
```

**Terraform**
```hcl
resource "dcloud_db_instance" "orders" {
  identifier       = "orders"
  instance_class   = "performance-4"
  topology         = "cluster"
  replication_mode = "sync"
}
```

## Result

The change applies to the running cluster without a restart; the request waits up to 40 seconds for
the cluster to report the new state, and **Activity** records it (phase `replication`). If the
cluster did not take it yet, the console says "Saved, but the cluster did not take it yet; it is
applied within 30 minutes."

If neither standby is streaming, the leader keeps accepting writes without waiting, rather than
stopping. **Nodes** then shows the setting as **degraded**, and **Activity** and a mail to your
organization's owners and admins say "Synchronous replication is degraded" until a standby is
back. `rds.replication.get` returns `mode`, `state` (`ok`, `degraded`, `async`, `unknown`) and
`syncStandbys`.

A cluster created before synchronous replication became the default stays `async` until you
change it.

## Related

- [How Managed PostgreSQL behaves when things fail](failure-behaviour.md)
- `rds.replication.set` · `dcloud rds replication set` · `dcloud_db_instance`
