All Products
Search

This Product

    ApsaraDB for ClickHouse:Upgrade via cloning

    Document Center

    ApsaraDB for ClickHouse:Upgrade via cloning

    Last Updated:Mar 09, 2026

    This topic describes how to upgrade the major engine version of an ApsaraDB for ClickHouse Community-compatible Edition cluster by cloning an instance.

    Prerequisites

    Your ApsaraDB for ClickHouse Community-compatible Edition cluster must be version 20.3, 20.8, 21.8, or 22.8.

    Precautions

    Important

    The features, syntax, and performance of write and query operations may differ between major engine versions. Before you upgrade a production environment, perform tests to ensure that these differences do not affect your business.

    • This method is not applicable to some early ApsaraDB for ClickHouse Community-compatible Edition clusters of version 20.3, 20.8, or 21.8. You can only upgrade the major engine version of these clusters by migrating data. For more information about how to check whether a cluster is an early cluster, see Check whether a cluster is an early cluster.

    • To upgrade the major version between a Community-compatible Edition cluster and an Enterprise Edition cluster, you can only migrate data.

    • Before you perform an official upgrade in a production environment, complete the test and verification process to determine the time required for the upgrade. Cloning is based on snapshots and completes in minutes. The data volume does not affect the time it takes to clone a snapshot. However, the cluster restarts multiple times during the upgrade. For some clusters, a single startup may take a long time because of many databases, tables, or partitions (parts).

    • If you enabled Tiered Storage of Hot and Cold Data for a cluster, the cloned instance contains only hot data. You cannot query cold data on the new cluster.

    • You cannot clone synchronization tables or external tables for services such as Kafka, MySQL, and RabbitMQ. These tables are deleted after the clone is complete.

    Upgrade process

    We recommend that you first clone the cluster to test and verify compatibility. After you verify that your business is compatible with the new version, perform a second clone to complete the upgrade.

    The process is as follows:

    1. Test and verification (This step is optional for non-production environments).

      1. Clone the cluster from a real-time backup and upgrade the major engine version during the process.

      2. You can authenticate the service.

      3. Authentication succeeded.

      4. Writes to the instance are stopped.

      5. Prepare for the official upgrade.

    2. Official upgrade.

      Important

      To ensure that the new cluster has all the data from the source cluster, stop all write operations to the source cluster before you perform the official clone.

      1. Create a plan for the official upgrade that includes a quick business verification method.

      2. Stop write operations to the source cluster.

      3. Clone the cluster from a real-time backup and upgrade the major engine version during the process.

      4. Perform a quick business verification.

      5. Authentication succeeded.

      6. Switch the read and write connection strings to the new cluster.

      7. Done.

    (Optional) Business verification methods

    • Retrieve the query_log from the source cluster and run it on the new cluster to verify query compatibility with the new version.

    • Perform a full regression test on your business features.

    Procedure

    1. Log on to the ApsaraDB for ClickHouse console with your Alibaba Cloud account.

    2. In the top navigation bar, select the region where the target cluster is located.

    3. In the navigation pane on the left, click Clusters.

    4. Find the target cluster and click the cluster ID to open the Cluster Information page.

    5. In the navigation pane on the left, click Backup and Restoration. On the Backup and Restoration page, click the Restore Instance button.

    6. On the clone instance purchase page, confirm the Target Instance Engine Version. Adjust the new instance configuration as needed and place the order.

    7. After you place the order, verify that the major engine version of the new cluster is the target version and that its status is Running. This indicates that the major engine version upgrade is complete.

    Check if an instance is an early instance

    1. Log on to the ApsaraDB for ClickHouse console with your Alibaba Cloud account.

    2. In the top navigation bar, select the region where the target cluster is located.

    3. In the navigation pane on the left, click Clusters.

    4. Find the target cluster and click the cluster ID to open the Cluster Information page.

    5. On the Cluster Information page, find the Configuration Information section and check the Minor Version. If the value is "-", the cluster is an early cluster.