将自建ClickHouse迁移至云数据库 ClickHouse 企业版

注意事项

步骤一：检查自建集群并开启使用系统表system

在数据迁移之前，需要根据自建集群是否已启用system.part_log和system.query_log，对config.xml文件进行修改配置，以实现增量迁移。

<part_log>
    <database>system</database>
    <table>part_log</table>
    <partition_by>event_date</partition_by>
    <order_by>event_time</order_by>
    <ttl>event_date + INTERVAL 15 DAY DELETE</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</part_log>

<query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>event_date</partition_by>
    <order_by>event_time</order_by>
    <ttl>event_date + INTERVAL 15 DAY DELETE</ttl>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</query_log>

步骤二：配置目标集群兼容自建集群版本

为确保目标集群与自建集群的行为尽可能兼容，需连接目标集群，修改compatibility参数，使目标集群与自建集群的版本号一致。

示例如下：

SELECT currentProfiles(); //获取用户使用的profile
SELECT
    profile_name,
    setting_name,
    value
FROM system.settings_profile_elements
WHERE (setting_name = 'compatibility') AND (profile_name = 'xxxx'); // 查询compatibility配置值
ALTER PROFILE XXXX SETTINGS compatibility = '23.8'; // 修改profile

步骤三：创建迁移任务

1. 登录云数据库ClickHouse控制台，在集群列表页面，选择企业版实例列表，并单击目标集群ID。

2. 在左侧导航栏，单击数据迁移及同步 > 从自建或云ClickHouse迁移。

3. 单击创建迁移任务。

4. 选择源及目标实例。

   配置项	说明	示例
   任务名称	迁移任务名称，只能由大小写英文字母和数字组成，且不允许重复，大小写不敏感。	MigrationTask1229
   源实例cluster名称	通过SELECT * FROM system.clusters; 获取自建实例cluster名称。	default
   VPC IP地址	集群每个shard的IP和PORT地址，使用英文逗号隔开。格式：IP:PORT,IP:PORT,.... 您可以使用以下SQL获取自建集群的IP和PORT： SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = '<cluster_name>' and replica_num = 1; 参数说明： cluster_name：目标集群的名字。 replica_num=1表示选择第一个副本集，也可以选择其他副本集或者自行挑选每个shard的一个副本组成。 重要 不能使用ClickHouse的VPC域名地址或者SLB地址。 如果IP和端口发生转换后映射到阿里云，则需要根据网络打通情况配置对应的IP和PORT。	192.168.0.5:9000,192.168.0.6:9000
   数据库账号	自建集群数据库账号。	test
   数据库密码	自建集群数据库账号密码。	test******
   源实例内核版本	单击获取版本。	22.8.5.29

5. 根据获取到的源实例版本信息，执行对应操作：

   • 源实例版本大于等于22.10：单击下一步。

   • 源实例版本小于22.10：根据提示填写目标实例信息，单击下一步。

   • 获取版本失败：源实例信息填写错误、网络未打通等情况会导致获取版本失败，请根据提示信息处理后，重新单击获取版本。

   说明

   由于低版本社区版与企业版之间存在参数不兼容的问题，当源实例版本低于22.10时，需要通过源端向目的端推送数据的方式进行同步。在这种情况下，需要将目的端的IP映射至自建网络。如果自建网络与企业版实例处于同一 VPC，或双方网络已通过VPC对等连接连通，则可直接使用原有IP地址进行连接。

6. 检查连通性和配置。

   1. 单击开始检查。

      点击查看检查项。

      • 连通性验证：自建实例和目标实例之间的网络完全打通，两端各个节点之间能够互相访问。

      • 账户权限验证：源端账户、密码输入正确，能够连接到源端实例。

      • 检查源实例系统表：自建实例必须有system.query_log、system.parts、system.part_log三个系统表。

      • 检查配置：自建实例和目标实例时区相同、目标实例的compatibility配置项与源端版本相同。

   2. 检查过程中可以单击右上角的实时查看检查进度。

   3. 检查完成后，请根据检查结果，完成后续操作。

      您可以选择结果级别与检查项，然后单击按钮，查看对应的检查结果，检查结果说明如下。

      • 成功：若所有检查项均通过，单击下一步继续操作。

      • 警告：非强制卡点项，需自行确认该警告项是否会对业务和迁移任务造成影响。您可选择忽略告警，或根据告警内容处理对应的告警项后，再次单击开始检查，重新检查连通性与配置。

      • 错误：强制卡点项，需根据错误内容处理对应的错误项后，再次单击开始检查，重新检查连通性与配置。

        检测报错信息以及解决方案，请参见常见问题。

7. 检查库表结构。

   检查连通性和配置成功后，进入检查库表结构步骤。此步骤分为选择需要迁移的库、选择需要迁移的表和检查库表结构三个子步骤。

   重要

   其中选择需要迁移的库和选择需要迁移的表两个步骤可以跳过。若您确认需要迁移源端的所有库表，则不需要进行这两个子步骤，可以直接跳到子步骤3（检查库表结构）。

   子步骤1：选择需要迁移的库（可跳过）

   1. 单击查询源端，后台会自动查询源端的库。

   2. 查询过程中，您可以点击查询结果，来查看实时查询结果。

   3. 当源端库查询完毕后，您可以根据业务需求选择需要迁移的库，选择完毕后，点击确认提交即可。

   子步骤2：选择需要迁移的表（可跳过）

   1. 选择完需要迁移的库后，会进入选择需要迁移的表的界面，单击查询源端，后台会自动查询您选择的库中的所有表。

   2. 查询过程中，您可以点击查询结果，来查看实时查询结果。

   3. 当源端表查询完毕后，您可以根据业务需求选择需要迁移的表，选择完毕后，点击确认提交即可。

   重要

   选择需要迁移的表时，系统默认全选，若您只需要迁移部分表，可以取消对应库的全选框，打开下拉框后即可选择您需要的表。

   子步骤3：检查库表结构

   1. 单击开始检查，后台会进行库结构检查、表结构检查、UDF检查，此步骤主要检查源端实例的库、表、UDF是否存在与目的端不兼容的情况。

   2. 检测过程中，您可以选择通过结果级别、检查项，并点击刷新按钮，来查看实时检查结果。

   3. 检测结果分为成功、警告、失败三类。

      • 检测成功：可直接单击下一步，进行后续迁移流程。

      • 检测过程出现告警

        您可以将结果级别设置为警告，并找到对应检查项查看对应的警告原因。

        重要

        结果级别为警告的检查项非强制卡点项，需要您自行确认该警告项是否会对您的业务和迁移任务造成影响，在您自行确认后，有以下两种选择：

        • 忽略告警，直接单击下一步，进行后续的迁移流程。

        • 根据告警内容处理对应的告警项后，单击开始检查，重新检查库表结构。检测告警信息以及解决方案，请参见本文检查库表结构中的报错信息及解决方案。

      • 检测失败

        您可以将结果级别设置为错误，并找到对应检查项查看对应的错误原因。

        重要

        结果级别为错误的检查项为强制卡点项，您需要根据错误内容处理对应的错误项后，单击开始检查，重新检查库表结构。检测报错信息以及解决方案，请参见本文检查库表结构中的报错信息及解决方案。

8. 库表结构迁移。

   1. 单击开始迁移。

   2. 迁移过程中可以单击右上角的实时查看迁移进度。

   3. 检查完成后，请根据检查结果，完成后续操作。

      检查结果说明请参见步骤5。

9. （可选）检查SQL兼容性。

   SQL兼容性检查通过在目标实例上对自建实例的SQL语句进行回放，来验证不同内核版本的语法兼容性，请您根据自身需求，决定是否需要执行此步骤。

   • 无需执行，则单击跳过。

   • 若需要执行，需选择请求重放时间后，再单击开始检查。检查通过后单击下一步，检查不通过时的处理方法请参见步骤5。

     重要

     • 实例库表无数据，仅提供验证语法兼容性的能力。如果需要有数据，可先执行下一步骤迁移部分数据。

     • 由于回放SQL的客户端版本和目标实例不匹配，可能存在误报。针对异常情况，您可以自行执行SQL验证。

10. 记录并清理 Kafka/RabbitMQ 引擎表。

    启动同步前，需要在自建集群中记录 Kafka/RabbitMQ 引擎表及其下游物化视图的定义，处理隐式表后删除这些表，以避免迁移异常。

    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. 如果物化视图目标表是隐式表，则 RENAME 物化视图目标表到一个新名字，避免后续删除物化视图时同步删除目标表导致数据丢失。

       -- 将隐式目标表 rename 到新名字，保护数据
       RENAME TABLE <DATABASE>.`.inner_id.<TABLE_UUID>` TO <DATABASE>.<new_target_table_name>;

    4. 删除 Kafka/RabbitMQ 引擎表及其下游物化视图。

       -- 先删除物化视图
       DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
       -- 再删除 Kafka/RabbitMQ 引擎表
       DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

    重要

    请务必保存好所有记录的建表语句（DDL）。后续需要在自建集群和目标集群上重建这些表。如果执行了 RENAME 操作，重建物化视图时需要指向已被 RENAME 的目标表。

11. 启动同步。

    1. 单击开始同步。

    2. 同步过程中可以单击右上角的实时查看同步进度。

       同步过程中，支持执行停止、重启与取消迁移操作控制迁移流程，点击查看操作含义及影响等信息。

       操作	功能含义	影响	使用场景
       停止	立刻停止迁移数据，迁移剩余的库表结构。	数据可能未完全迁移。 在您重新发起迁移之前，必须先清理目标集群中已迁移的数据，避免出现数据重复的情况。	全部数据迁移完成后，主动停止迁移任务。 期望迁移一部分数据后测试，但是不想停写自建集群。
       重启	在检查并清理其他库表、迁移数据、迁移剩余库表结构过程中出现异常，客户根据错误信息处理之后，将重试当前步骤，并正常执行后续步骤。	无	迁移过程出现异常，客户根据提示信息解决之后想要断点重试
       取消迁移	强制取消任务，跳过后续步骤。 重要 取消迁移后，该迁移任务将被锁定，即不允许修改迁移流程，您可通过上一步、下一步或刷新按钮查看迁移步骤执行结果。	迁移任务强制终止，目标实例库表结构和配置可能不完整，不可作为业务正常使用。 在您重新发起迁移之前，必须先清理目标集群中已迁移的数据，避免出现数据重复的情况。	迁移任务影响了自建集群，希望尽快结束迁移，开启写入。

    3. 在自建集群上，使用之前保存的 DDL 语句重建 Kafka/RabbitMQ 引擎表及其下游物化视图。重建后增量数据将恢复流入并自动同步到目标集群。

       重要

       如果之前对隐式目标表执行了 RENAME 操作，重建物化视图时需要使用 TO 子句指向已被 RENAME 的目标表，具体请参见CREATE MATERIALIZED VIEW。

       -- 在自建集群重建 Kafka/RabbitMQ 引擎表
       CREATE TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME> (...)
       ENGINE = Kafka/RabbitMQ
       SETTINGS ...;
       
       -- 重建物化视图（指向已 RENAME 的目标表）
       CREATE MATERIALIZED VIEW <DATABASE>.<MATERIALIZED_VIEW_NAME> TO <DATABASE>.<new_target_table_name>
       AS SELECT ... FROM <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

    4. 当执行到迁移数据时，切换到迁移数据页签，单击按钮查看迁移进度及预估剩余时间。

       点击查看如何评估迁移是否可以完成。

       迁移是否可以完成取决于迁移速度与自建集群写入速度的关系。

       • 迁移速度的测试实验数据如下：

         数据表的Part平均大小	源端实例规格	源端磁盘规格	目标端实例规格	目标端存储介质	集群节点数	单节点迁移速度	整体迁移速度
         402.54MB	8C32G	PL1	16CCU	OSS	16	47MB/s	752.34MB/s
         402.54MB	80C384G	PL3	48CCU	ESSD_L2	8	197.74MB/s	1581.95MB/s

       • 判断目标集群与自建集群的写入速度的关系：

         数据迁移的速度与part大小（在测试实验中，平均part大小在100MB~10GB的范围内，能够保持较快的迁移速度）、实例规格、磁盘规格、业务数据特性等要素相关，因此测试实验数据仅供参考。目标集群的真实写入速度需要您通过查看目标集群的磁盘吞吐来判断，如何查看磁盘吞吐，请参见查看集群监控信息。

         • 目标集群写入速度小于自建集群的写入速度：迁移失败率较高，建议您取消迁移任务，使用手动迁移进行数据迁移。

         • 目标集群写入速度大于自建集群的写入速度：可继续后续步骤，为提高迁移成功率，建议数据量 /（迁移速度-自建实例写入速度）所得的迁移所需时间小于等于 5天 。

       重要

       • 您需重点监控目标任务的迁移进度，根据预估剩余时间，主动停写自建集群并处理Kafka和RabbitMQ引擎表。

       • 目前迁移最长时间阈值统一设置为5天，当持续迁移时间满5天时，后台将自动取消迁移任务，若您的迁移任务需要更长的迁移时间，请提交工单联系技术支持调整阈值。

       评估何时停写自建集群并执行切流

       当迁移预估时间少于 10 分钟或者迁移进度达到 99% 时，执行以下操作完成切流：

       1. 停止业务写入。在自建集群上，删除之前重建的 Kafka/RabbitMQ 引擎表及其下游物化视图。

          -- 先删除物化视图
          DROP TABLE <DATABASE>.<MATERIALIZED_VIEW_NAME>;
          -- 再删除 Kafka/RabbitMQ 引擎表
          DROP TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

       2. 等待迁移进度达到 100%，迁移完全结束。

       3. 连接目标集群，使用之前保存的 DDL 语句重建 Kafka/RabbitMQ 引擎表及其下游物化视图。

          重要

          如果之前对隐式目标表执行了 RENAME 操作，重建物化视图时需要使用 TO 子句指向已被 RENAME 的目标表。参考 CREATE MATERIALIZED VIEW。

          -- 在目标集群重建 Kafka/RabbitMQ 引擎表
          CREATE TABLE <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME> (...)
          ENGINE = Kafka/RabbitMQ
          SETTINGS ...;
          
          -- 重建物化视图（指向已 RENAME 的目标表）
          CREATE MATERIALIZED VIEW <DATABASE>.<MATERIALIZED_VIEW_NAME> TO <DATABASE>.<new_target_table_name>
          AS SELECT ... FROM <DATABASE>.<KAFKA_OR_RABBITMQ_TABLE_NAME>;

       4. 验证目标集群数据管道正常工作，确认数据正常流入。

    5. 当迁移进度为100%，且确认源端实例已经进入停写状态后，需要您单击停止按钮结束迁移流程，执行后续流程。

       

    6. 同步完成后单击完成。

       重要

       当“启动同步”步骤完成后，该迁移任务将被锁定，即不允许修改迁移流程，您可通过上一步、下一步或刷新按钮查看迁移步骤执行结果。

步骤四：迁移非MergeTree类型表的业务数据

迁移任务中，非MergeTree类型的表仅支持迁移表结构（例如MySQL表）或者不支持迁移（例如Log表）。因此，迁移任务完成后，目标集群可能存在只有表结构，没有具体的业务数据的表，您需自主完成业务数据迁移，具体操作如下：

1. 登录自建集群，查看需要迁移数据的非MergeTree类型的表。

   SELECT
       `database` AS database_name,
       `name` AS table_name,
       `engine`
   FROM `system`.`tables`
   WHERE (`engine` NOT LIKE '%MergeTree%') AND (`engine` != 'Distributed') AND (`engine` != 'MaterializedView') AND (`engine` NOT IN ('Kafka', 'RabbitMQ')) AND (`database` NOT IN ('system', 'INFORMATION_SCHEMA', 'information_schema')) AND (`database` NOT IN (
       SELECT `name`
       FROM `system`.`databases`
       WHERE `engine` IN ('MySQL', 'MaterializedMySQL', 'MaterializeMySQL', 'Lazy', 'PostgreSQL', 'MaterializedPostgreSQL', 'SQLite')
   ))

2. 登录目标集群，通过remote函数执行数据迁移。