A switchover is a planned role change between a primary cluster and a replica cluster in a different location. It promotes the replica cluster to primary and demotes the current primary to a replica.
Both clusters must be able to reach each other before you switch over
Before the new primary starts accepting writes, it must copy the last changes from the current primary over the network. If the new primary can't reach the current primary's connection endpoint, the switchover can't finish, and neither cluster accepts writes until the connection is restored.
This requirement matters most when your clusters are in different locations, for example different regions, data centers, or virtual private clouds (VPCs).
Before you start a switchover
Complete these checks before you start a switchover:
Check that the cluster has a replica cluster to promote. The Replica Clusters section of the Overview tab lists the primary cluster and its replica clusters. If the primary cluster is the only entry, Switchover Primary doesn't appear.
Take a backup of the cluster. If the switchover fails and you can't recover the clusters, you can restore from this backup. For more information, see Backups.
Check that each cluster can reach the other. Traffic must flow in both directions between the two clusters' connection endpoints on port 5432. Each cluster must also be able to reach your backup object storage.
Check each cluster's network access type. Private access works only if the two locations are connected. For example, they can share a network or use VPC peering, a virtual private network (VPN), or a private interconnect. Public access works as long as your firewalls and allowed IP ranges permit traffic between the two locations. You can mix public and private access, but only if the clusters can still reach each other.
If you recently changed a cluster's network access type, wait. Changing between public and private gives the cluster a new connection address. Don't switch over until the new address is assigned and resolvable from the other location.
Check that both the primary cluster and the replica cluster are healthy, and that the replica cluster is actively replicating from the primary.
Switching over to a replica cluster
To switch over to a replica cluster:
From the project page, select Clusters > Postgres Clusters, and then select the cluster.
From the detailed view of the cluster, select Quick Actions > Switchover Primary.
If Switchover Primary is unavailable, the cluster can't be switched over at the moment.
In the Switchover dialog, in Promoting to Primary, select the replica cluster to promote. The current primary appears under Demoting to Replica.
To confirm, enter
promote <replica cluster name>in the field. For example,promote Replica Cluster B.Select Confirm Switchover.
After a few minutes, the Replica Clusters section of the Overview tab shows the promoted replica cluster with the Primary badge. The former primary shows the Replica badge.
Switching over using the CLI
You can also switch over using the edbctl command-line interface (CLI). Run:
edbctl cluster switchover-primary --id <cluster-id> --replica-id <replica-id>
Where <cluster-id> is the unique ID of the cluster and <replica-id> is the unique ID of the replica cluster to promote.
To find both IDs, in the HM console:
Go to the cluster's Properties tab.
Use the drop-down list to select the primary or replica cluster.
The ID appears in the ID field. For all options, see edbctl cluster switchover-primary.
If a switchover doesn't finish
If the clusters can't reach each other, you might see these symptoms:
- The new primary doesn't finish promoting.
- Both clusters reject writes with
cannot execute INSERT in a read-only transaction. The clusters don't accept new writes until the new primary and the old primary complete their handshake.
To recover:
- Restore connectivity between the two clusters. The switchover then finishes on its own.
- Don't delete or restart the cluster's pods. It doesn't help, and the pods aren't recreated until the switchover finishes.
- Don't retry the switchover.
- If you can't restore connectivity, contact EDB Support by creating a support ticket. Recovering without the old primary can lose the most recent transactions and requires rebuilding the other cluster.
- If you can't recover the clusters, restore from the backup you took before the switchover. For more information, see Restores.
Switchover versus forced failover
A switchover is a planned role change. It needs both the primary cluster and the replica cluster online, healthy, and able to reach each other.
A forced failover is for when the primary's location is lost or unreachable. It promotes the replica without waiting for the old primary, so any changes that hadn't reached the replica yet are lost. Use it only when you can't recover the primary in time.
Forced failover is available only in the CLI. To use it, add --force to the edbctl cluster switchover-primary command. A forced failover requires only that the replica cluster is healthy. It doesn't need connectivity between the clusters, and the replica cluster can end up inconsistent with the old primary.
For the failover procedure in a multi-data-center deployment, see Manual failover.