ApsaraDB for ClickHouse:ZooKeeper management

Prerequisites

• The cluster status is Running.

• A cluster restart has not been performed.

• For instances purchased after March 13, 2025, with a version of 23.8 or later, the instances use ClickHouse Keeper, which uses 64-bit ZXID. In this case, ZXID overflow is not a concern and leader switching is not required.

  Important

  A newly purchased instance refers to an instance purchased from the console. It does not include instances created through backup restoration, cloning, or upgrade of existing instances.

Cluster impact

• Queries: Not affected.

• Write operations:

  • Write operations to tables that use a ReplicatedMergeTree engine may be briefly interrupted.

  • If write suspension is enabled, the instance blocks all write operations after the switchover begins. All writes to the instance fail during this period.

• DDL operations: The switchover may block distributed DDL execution.

• Duration:

  • Without write suspension: Approximately 1 to 2 minutes.

  • With write suspension: Approximately 2 to 10 minutes (write operations are blocked for the entire duration).

• Potential metadata inconsistency.

  A ZooKeeper leader switchover disconnects all ClickHouse nodes from ZooKeeper. High-frequency writes during this process can cause metadata inconsistency and force some tables into a Read-only state.

  To prevent metadata inconsistency, reduce the write frequency or stop write operations during the switchover period.

Leader switchover

1. Log on to the ApsaraDB for ClickHouse console.

2. In the upper-left corner of the page, select the region of your target cluster.

3. On the Clusters page, select Clusters of Community-compatible Edition, and then click the ID of the target cluster.

4. On the Cluster Information page, in the Zookeeper Configurations section under Configuration Information, click Scheduled Time.

5. In the Configure Primary/Secondary Switchover dialog box, review the impacts of this operation, and then click OK.

6. In the Configure Primary/Secondary Switchover dialog box, configure Configure Write Suspension and Select Mode.

   • Configure Write Suspension:

     • Enable Write Suspension: The instance blocks all write operations during the switchover. The process takes 2 to 10 minutes.

     • Disable Write Suspension: The instance performs the leader switchover without blocking write operations.

   • Select Mode:

     • Scheduled Time: In the Scheduled Time field, set a time for the leader switchover. The switchover starts at the scheduled time.

     • Execute Immediately: The cluster starts the leader switchover immediately.

7. Click OK.

   Note

   After the leader switchover starts, the cluster status changes to Switching Primary/Secondary Node. The operation is complete when the status returns to Running.

Modify or cancel the schedule

1. Log on to the ApsaraDB for ClickHouse console.

2. In the upper-left corner of the page, select the region of your target cluster.

3. On the Clusters page, select Clusters of Community-compatible Edition, and then click the ID of the target cluster.

4. On the Cluster Information page, in the Zookeeper Configurations section under Configuration Information, click Scheduled Time.

5. In the Configure Primary/Secondary Switchover dialog box, select Modify or Cancel.

   • Modify: You can modify all leader switchover settings.

   • Cancel: Cancels the scheduled leader switchover.