PolarDB clusters automatically fail over from the primary node to a read-only node when the primary fails. For planned maintenance or high availability testing, you can also trigger a failover manually by designating a specific read-only node as the new primary.
Before you begin
Failover interrupts the database service. Interruption duration depends on whether hot standby is enabled for the read-only node that takes over:
| Hot standby | Interruption duration |
|---|---|
| Disabled | Approximately 20–30 seconds |
| Enabled | Within 5–10 seconds |
In extreme cases, interruption time may exceed the typical range but never exceeds 3 minutes.
To reduce interruption time, enable hot standby on your read-only nodes. See Configure hot replica nodes.
Make sure your application can automatically reconnect to the cluster after a failover.
How automatic failover works
PolarDB Cluster Edition uses an active-active high availability architecture. When the primary node fails, the system elects a new primary from the available read-only nodes.
Each node in a cluster has a failover priority. During an election, the system follows these steps:
Identify all available read-only nodes eligible for promotion.
Select the node with the highest failover priority. Nodes that share the same priority have equal probability of being elected.
Attempt to fail over to the selected node. If the attempt fails due to network issues, abnormal replication status, or other reasons, the system tries the next eligible node until the failover succeeds.
To view and configure the failover priority of each node, go to the Database Nodes page of the cluster and check the Basic Information section.
Perform a manual failover
Manual failover is useful when you need to test cluster high availability or promote a specific read-only node to primary.
Log on to the PolarDB console.
In the upper-left corner, select the region where the cluster is deployed.
Find the cluster and click its ID.
On the Basic Information page, go to the Database Nodes section and click the
icon in the upper-right corner to switch views.Click Fail Over.
In the dialog box, set the New Primary Node parameter and click OK.
Interruption duration follows the same rules as automatic failover. See Before you begin for details.
Prepare your application for failover
After a failover, persistent connections between your application and the cluster may not detect the changed connection state automatically. If no timeout is configured, your application waits indefinitely for the database to respond — typically leading to disconnection after hundreds of seconds, during which SQL statements fail.
Configure the following parameters to minimize recovery time:
| Parameter | Recommended value |
|---|---|
connectTimeout | 1–2 seconds (online transaction scenarios) |
socketTimeout | 10–15 seconds (internal network); 60–90 seconds (public network) |
These values are reference guidelines. Adjust based on your workload and usage patterns.
API reference
| Operation | Description |
|---|---|
| FailoverDBCluster | Performs a manual failover by designating a read-only node as the new primary node. |