一键升级内核大版本

前提条件

集群状态为运行中。

注意事项

• 一键升级内核大版本流程启动后，无法取消。

  说明

  一键升级内核大版本后不支持版本回退，如果您需要在版本升级后，仍然具有能回退到原来版本的能力，可尝试通过克隆的方式进行升级，具体操作，请参见通过克隆升级内核大版本。

• 一键升级内核大版本始终只有一个集群，且升级后无法回退到原版本。

• 为确保升级过程顺利进行，建议您在进行升级前停止业务侧的写入操作。因为在升级过程中，集群会主动停止写入，但若业务未提前停止写入，则可能导致同步等待时间过长，甚至无法在短时间内完成同步，从而影响升级的时效性。

• 为了降低升级对您业务的影响，强烈建议您在升级前，进行以下内容的验证。

  • 兼容性以及性能验证：写入和查询的功能、语法、性能的差异验证。

  • 升级时长验证：版本升级过程会多次重启实例，部分实例由于库表数量、分区（Parts）数量过多等因素单次启动过程需要较长时间。

    重要

    如果集群数据大量存在冷存存储，并且使用的是克隆验证，由于克隆不会克隆冷存数据，所以一键升级所需的时间相较于克隆验证所需的时间更长。

  如何验证，请参见验证版本兼容性。

集群影响

版本升级期间集群会进行多次重启，不可读也不可写，建议在业务低峰期进行操作。

验证版本兼容性

由于一键升级内核大版本始终只有一个集群，且升级后无法回退到原版本，强烈建议您先进行升级测试，确认新版本集群完全兼容原版本集群的功能以及升级时长后再进行升级。验证步骤如下：

1. 进入目标实例的集群信息页面。在左侧导航栏，单击备份恢复。完成备份后，单击恢复实例。

2. 选择从实时副本克隆，并将目标引擎版本设置为您要升级到的版本。

3. 创建克隆集群。

4. 执行兼容性验证。

   1. 验证您的业务查询与新版本的兼容性。更多信息，请参见SQL兼容性验证。

   2. 对您的业务功能进行回归测试。

操作步骤

1. 使用阿里云账号登录云数据库ClickHouse控制台。

2. 在页面左上角，选择目标集群所在的地域。

3. 在左侧导航栏，单击社区版实例列表。

4. 找到目标集群，单击集群ID，进入集群信息页面。

5. 在集群属性区域，单击版本右侧的大版本升级。

6. 根据页面提示，配置如下参数，点击确定按钮。

   配置项	说明	示例
   将实例内核版本升级至	目标集群版本，版本升级后无法回退。 当前仅支持的版本有25.3。	23.8（LTS版本）
   版本升级执行时间	升级集群版本的执行时间。 重要 选择指定时间升级和可维护时间段升级后，集群的状态会由运行中变为版本升级中，在指定时间或者运维窗口到来前，集群可正常对外提供读写服务，但是不能执行升降配、扩缩容、迁移等运维操作。 指定时间：选择未来某一指定时间点做大版本升级。 可维护时间段升级：默认选取当前集群的运维窗口时间。 立即升级：立即执行升级操作。	2024-05-29 14:46
   是否执行克隆验证	勾选已执行克隆验证或跳过克隆验证（不推荐）	已执行克隆验证

前提条件

集群状态为运行中。

注意事项

• 一键升级内核大版本始终只有一个集群，且升级后无法回退到原版本。

  说明

  一键升级内核大版本后不支持版本回退，如果您需要在版本升级后，仍然具有能回退到原来版本的能力，可尝试通过迁移的方式进行升级，具体操作，请参见迁移升级。

• 集群升级时，集群库表需要注意的内容如下：

  • MergeTree类型引擎表，升级时，会将原有历史数据迁移写入新的集群中并自动完成重分布。

  • 非MergeTree类型（如外表，Log表等），升级时，仅进行表结构迁移，不进行数据迁移。

  • 物化视图，在集群升级时，仅进行结构迁移，不进行数据迁移。

  • Kafka/RabbitMQ引擎表在集群升级时，不支持迁移，升级前需删除此类表。

  • 升级后内部节点IP会发生变化，如果依赖节点IP数据写入和访问，需重新获取集群的VPC网段IP，具体操作，请参见获取集群的VPC网段IP。

• 为了降低升级对您业务的影响，强烈建议您在升级前，进行以下内容的验证。

  • 兼容性以及性能验证：写入和查询的功能、语法、性能的差异验证。

  • 升级时长验证：版本升级过程会多次重启实例，部分实例由于库表数量、分区（Parts）数量过多等因素单次启动过程需要较长时间。

  如何验证，请参见验证版本兼容性。

集群影响

社区兼容版集群在升级过程中，除迁移剩余的最后的10分钟不可写外，全程可读可写。如何查看迁移剩余的时间，请参见查看升级进度。

验证版本兼容性

由于一键升级内核大版本始终只有一个集群，且升级后无法回退到原版本，强烈建议您先进行升级测试，确认新版本集群完全兼容原版本集群的功能以及升级时长后再进行升级。验证步骤如下：

1. 购买新集群进行迁移验证。请参见通过迁移升级内核大版本。

2. 在新集群中，进行SQL兼容性验证。如何验证，可参见SQL兼容性验证。

3. 回归业务功能进行验证。

步骤一：记录并清理 Kafka/RabbitMQ 引擎表

Kafka/RabbitMQ 引擎表无法通过控制台升级功能直接迁移。升级前，您必须记录这些表的 DDL 语句并将其从集群中删除，以避免干扰升级任务。

1. 登录集群并执行以下语句查询所有 Kafka 和 RabbitMQ 引擎表及其下游依赖。

   /*
   create_table_query：表定义语句
   dependencies_database：依赖该表的数据库
   dependencies_table：依赖该表的表名
   通过 dependencies_database 和 dependencies_table 可以确定依赖 Kafka/RabbitMQ 表的物化视图
   */
   SELECT * FROM system.tables WHERE engine IN ('RabbitMQ', 'Kafka');

2. 查看物化视图定义，检查其目标表是否为隐式表。

   /*
   查看物化视图定义。
   如果物化视图的目标表为隐式表，需特别注意：
   删除物化视图时会同时删除隐式表，导致数据丢失。
   示例：如果 CREATE MATERIALIZED VIEW [db.]table_name [TO[db.]name] 未指定 TO 子句，
   系统会自动创建隐式表，格式可能为 '.inner_id.<TABLE_UUID>' 或 '.inner.<TABLE>'
   */
   SELECT * FROM system.tables WHERE database='<DATABASE>' AND name = '<MATERIALIZED_VIEW_NAME>';

3. 如果物化视图创建时未使用 TO 子句，系统会自动生成以 .inner 或 .inner_id 为前缀的隐式目标表。升级时这些隐式表会迁移到新集群节点，但由于内部命名机制，直接重建原物化视图可能导致命名冲突。因此，您必须先将隐式目标表重命名为常规表名。

   -- 将隐式目标表重命名为常规表名（在所有节点上执行）
   RENAME TABLE <database>.`.inner_id.<uuid>` TO <database>.<new_target_table_name> ON CLUSTER default;

4. 删除物化视图和 Kafka/RabbitMQ 引擎表。

   重要

   必须先删除引用 Kafka/RabbitMQ 表的物化视图，然后再删除 Kafka/RabbitMQ 引擎表。否则升级操作会失败。

   -- 先删除物化视图
   DROP TABLE <database>.<materialized_view_name> ON CLUSTER default;
   
   -- 再删除 Kafka/RabbitMQ 引擎表
   DROP TABLE <database>.<kafka_or_rabbitmq_table_name> ON CLUSTER default;

步骤二：升级集群

1. 使用阿里云账号登录云数据库ClickHouse控制台。

2. 在页面左上角，选择目标集群所在的地域。

3. 在左侧导航栏，单击社区版实例列表。

4. 找到目标集群，单击集群ID，进入集群信息页面。

5. 在集群属性区域，单击版本右侧的大版本升级。

6. 根据页面提示，配置如下参数，点击确定按钮。

   配置项	说明	示例
   将实例内核版本升级至	目标集群版本，版本升级后无法回退。 当前仅支持的版本有23.8。	23.8（LTS版本）
   停写时间	为了确保升级后数据与升级前的数据保持一致，在升级的最后10分钟内，集群会进行主动停止写入操作。停写时间的设置规则如下： 为了保证升级的成功率，建议您停写时间至少设置30分钟。 升级必须在5天内结束，因此，集群停写时间的结束日期必须小于或等于当前日期+5天。 为了降低停写对您业务的影响，建议您设置的停写时间范围处于您的业务低峰期。	2025-03-20 10:08-2025-03-25 10:08
   是否执行实例迁移验证	勾选已执行实例迁移验证或跳过实例迁移验证（不推荐）	已执行实例迁移验证

7. 后续操作。

   • 如果源集群包含 Kafka 或 RabbitMQ 引擎表，请在升级过程中的适当时间执行步骤三至步骤五。详情请参见以下章节。

   • 查看升级进度，请参见查看升级进度。

   • 时间已超过您设定的停写时间，而集群状态仍显示为版本升级中时，您需修改升级停写时间以完成迁移。

   • 升级已对您的业务造成影响，期望快速停止升级操作时，您可以取消升级。

步骤三：数据迁移阶段重建 Kafka/RabbitMQ 引擎表

当升级任务进入数据迁移阶段（表结构迁移完成后），使用之前保存的 DDL 语句重建 Kafka/RabbitMQ 引擎表及其下游物化视图。重建后，增量数据恢复流动并自动同步到新集群节点。

-- Rebuild Kafka/RabbitMQ engine tables
CREATE TABLE <database>.<kafka_or_rabbitmq_table_name> (...)
ENGINE = Kafka/RabbitMQ
SETTINGS ...;

-- Rebuild materialized view (using TO clause pointing to the renamed target table)
CREATE MATERIALIZED VIEW <database>.<materialized_view_name> TO <database>.<new_target_table_name>
AS SELECT ... FROM <database>.<kafka_or_rabbitmq_table_name>;

步骤四：停写前删除 Kafka/RabbitMQ 引擎表

在配置的停写窗口到来之前，删除集群上的 Kafka/RabbitMQ 引擎表及其下游物化视图，以停止增量数据写入并确保最终数据同步的一致性。

-- Delete materialized views first
DROP TABLE <database>.<materialized_view_name> ON CLUSTER default;

-- Then delete Kafka/RabbitMQ engine tables
DROP TABLE <database>.<kafka_or_rabbitmq_table_name> ON CLUSTER default;

步骤五：升级完成后重建 Kafka/RabbitMQ 引擎表

升级任务完成后，使用之前保存的 DDL 语句在已升级的集群上重建 Kafka/RabbitMQ 引擎表及其下游物化视图，以恢复增量数据消费管道。

-- Rebuild Kafka/RabbitMQ engine tables
CREATE TABLE <database>.<kafka_or_rabbitmq_table_name> (...)
ENGINE = Kafka/RabbitMQ
SETTINGS ...;

-- Rebuild materialized view (using TO clause pointing to the renamed target table)
CREATE MATERIALIZED VIEW <database>.<materialized_view_name> TO <database>.<new_target_table_name>
AS SELECT ... FROM <database>.<kafka_or_rabbitmq_table_name>;

查看升级进度

1. 使用阿里云账号登录云数据库ClickHouse控制台。

2. 在页面左上角，选择目标集群所在的地域。

3. 在左侧导航栏，单击社区版实例列表。

4. 找到目标集群，单击集群ID，进入集群信息页面。

5. 在集群状态区域，单击状态右侧的查看版本升级进度。

   在弹出的修改停写窗口对话框中，查看升级进度。例如MergeTree表结构迁移的进度、数据迁移的进度、数据迁移预计的剩余时间、以及其他结构迁移进度。

修改升级停写时间

当您发现时间已超过您设定的停写时间，而集群状态仍显示为版本升级中时，这表明在升级过程中，集群数据迁移尚未完成。您需要调整停写时间，以确保集群升级的顺利完成。

1. 使用阿里云账号登录云数据库ClickHouse控制台。

2. 在页面左上角，选择目标集群所在的地域。

3. 在左侧导航栏，单击社区版实例列表。

4. 找到目标集群，单击集群ID，进入集群信息页面。

5. 在集群状态区域，单击状态右侧的查看版本升级进度。

6. 在弹出的修改停写窗口对话框中，修改停写时间后，单击确认。

   说明

   停写时间设置规则，与升级集群中的停写时间的设置一致。

取消升级

当您发现升级已对您的业务造成影响，期望快速停止升级操作时，您可以通过取消升级来终止该操作。

1. 使用阿里云账号登录云数据库ClickHouse控制台。

2. 在页面左上角，选择目标集群所在的地域。

3. 在左侧导航栏，单击社区版实例列表。

4. 找到目标集群，单击集群ID，进入集群信息页面。

5. 在集群状态区域，单击状态右侧的查看版本升级进度。

6. 在弹出的修改停写窗口对话框中，单击取消升级。

   说明

   单击取消升级后，升级任务不会立即终止，大约5分钟后才会真正停止。