High availability_
Run up to five read replicas with asynchronous, synchronous, or quorum replication and automatic failover for your PostgreSQL database.
3 min read
A single database instance is a single point of failure. High availability (HA) adds streaming replicas next to your primary: they replicate continuously, serve read traffic through the connection pooler, and take over automatically when the primary becomes unhealthy.
High availability works on every PostgreSQL specification. How many replicas you can add depends on your plan: the Pro and Scale plans allow up to five, and the free plan allows none.
The connection pooler must be in transaction mode. Adding replicas is refused while the pooler is in session mode.
How it works
Replicas receive changes from the primary through PostgreSQL streaming replication (WAL shipping). Each replica is a full copy of the database on its own compute. When the primary fails, the most caught-up replica is promoted to primary and the hostname is repointed, your application keeps connecting to the same host and port.
Replication modes
| Mode | Behavior | Trade-off |
|---|---|---|
async | The primary commits without waiting for replicas | Fastest writes; a failover can lose the last moments of writes |
sync | The primary waits for one replica to confirm each commit | No data loss on single failure; slightly higher write latency |
quorum | The primary waits for a majority of the replica set, counting the primary itself | Scales the number of confirmations with the replica count |
async is the default. For production workloads that cannot lose acknowledged writes, use sync or quorum with at least one replica.
quorum needs (replicas + 1) / 2 confirmations, rounded down. At one and two replicas that is a single confirmation, the same as sync, so the two modes behave identically until you run three or more replicas.
Both sync and quorum wait for the replica to write the change to disk, not to apply it. A replica can still answer a read from before a write that the primary has already acknowledged.
If replicas fall behind or disappear, the primary lowers the number of confirmations it waits for rather than blocking writes, and raises it again once the replicas recover. The replication status reports the mode in effect alongside the one you configured.
Enable high availability
Set the replica count and replication mode on the database, from Settings > Replication in the Console or through the API:
Adding replicas provisions them online; the primary keeps serving traffic while each replica seeds from a snapshot and catches up. Setting replicas back to 0 disables HA and resets syncMode to async.
Check replication status
You can check each replica's role, health, and replication lag:
Automatic failover
Appwrite continuously health-checks the primary. When it becomes unresponsive, the platform promotes the replica with the least replication lag, repoints the database hostname, and rebuilds the old primary as a replica of the new one. Your application reconnects to the same hostname; a well-configured driver pool retries and recovers without intervention.
With async replication, writes that had not yet reached the promoted replica are lost in a failover. Use sync or quorum if that is unacceptable.
Manual failover
Trigger a failover yourself, for example to test your application's recovery behavior. Optionally pass targetReplicaId to promote a specific replica.
Reading from replicas
Replicas serve read traffic when read/write splitting is enabled on the connection pooler. A read that immediately follows a write can return stale data, and synchronous replication does not change that, because it waits for the replica to store the write rather than apply it. Route reads that must see the latest write to the primary.
Limits and billing
- Up to 5 replicas per database; the maximum depends on your plan.
- Each replica runs on the same specification as the primary and is billed as an add-on. See pricing.
- Replicas live in the same region as the primary.
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.