ApsaraDB for ClickHouse lets you manage the ZooKeeper cluster bundled with your ClickHouse cluster. When the ZooKeeper Transaction ID (ZXID) usage is high, schedule a leader switchover to re-elect a ZooKeeper leader and reset the ZXID.
Only perform this operation when ZXID usage is high.
Prerequisites
Before you begin, ensure that:
The cluster status is Running
The cluster is not undergoing a restart
Potential impacts
During a ZooKeeper leader switchover, all connections between ClickHouse nodes and ZooKeeper are temporarily disconnected. The following table summarizes the impacts by area:
| Area | Impact | Severity |
|---|---|---|
| Queries | Not affected | — |
| Write operations (write suspension disabled) | Tables using ReplicatedMergeTree engines experience transient connection drops | Medium |
| Write operations (write suspension enabled) | All write operations fail for the duration of the switchover | High |
| DDL operations | Distributed DDL execution may be blocked | Medium |
| Metadata consistency | High-frequency writes during switchover may cause metadata inconsistency; affected tables enter a Read-only state | High |
Duration:
| Mode | Duration |
|---|---|
| Write suspension disabled | Approximately 1–2 minutes |
| Write suspension enabled | Approximately 2–10 minutes (no writes allowed) |
To avoid metadata inconsistency, reduce write frequency or stop write operations during the switchover.
Schedule a leader switchover
Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner, select the region where your cluster is deployed.
On the Clusters page, select Clusters of Community-compatible Edition and click the ID of your cluster.
On the Cluster Information page, find the ZooKeeper Configuration section under Configuration Information in the lower-left corner, then click Schedule Time.
In the Configure Primary/Secondary Switchover dialog, read the impact information and click OK.
Configure the following settings:
Configure Write Suspension:
Option Behavior Enable Write Suspension The cluster blocks all write operations during the switchover. Duration: 2–10 minutes. Disable Write Suspension The cluster performs the switchover without blocking writes. Duration: 1–2 minutes. Select Mode:
Option Behavior Scheduled Time Set a specific time for the switchover to begin. Execute Immediately Start the switchover right away.
Click OK.
After the switchover begins, the cluster status changes to Switching Primary/Secondary Node. When the status returns to Running, the switchover is complete.
Modify or cancel a scheduled switchover
You can only modify or cancel a switchover if the cluster is already in Scheduled Time mode.
Log on to the ApsaraDB for ClickHouse console.
In the upper-left corner, select the region where your cluster is deployed.
On the Clusters page, select Clusters of Community-compatible Edition and click the ID of your cluster.
On the Cluster Information page, find the ZooKeeper Configuration section under Configuration Information in the lower-left corner, then click Scheduled Time.
In the Configure Primary/Secondary Switchover dialog, select an action:
Action Description Modify Update all configurations for the scheduled switchover. Cancel Cancel the scheduled switchover.