将自建ClickHouse数据迁移至云ClickHouse社区兼容版

迁移过程中

• 目标集群进行迁移的库表会暂停合并（Merge），但自建集群不会。

  说明

  迁移数据时间过长，将导致目标集群的元数据积累过多。建议迁移任务的持续时长不超过5天。

• 目标集群必须使用default集群。如果您自建集群的命名使用了其他名字，则会自动将分布式表中的cluster定义转化为default。

迁移内容

• 支持迁移的内容：

  • 库、数据字典、物化视图。

    • 只支持迁移SQL创建的数据字典，不支持通过XML创建的数据字典。

      确认方法：SELECT * FROM system.dictionaries WHERE (database = '') OR isNull(database);，如果SQL存在返回结果，代表有XML创建的数据字典。

    • 数据字典访问外部服务时，请确保外部服务可用且为集群开放白名单；数据字典的数据源为当前ClickHouse的内表数据时，如果定义中HOST参数配置的是IP地址，迁移后可能会因IP变更而导致访问失败，需重新确认当前ClickHouse的HOST并手动创建数据字典。

  • 表结构：除了Kafka和RabbitMQ引擎表以外的所有表结构。

  • 数据：增量迁移MergeTree族表的数据。

• 不支持迁移的内容：

  • Kafka和RabbitMQ引擎表的表以及数据。

  • 非MergeTree类型表（例如外表、Log表等）的数据。

  重要

  以上不支持的内容，在迁移过程中，您需根据操作步骤，手动处理。

• 迁移数据量：

  • 冷数据：冷存数据的迁移速度相对较慢，建议您尽量清理自建集群中的冷存数据，以确保其总量不超过1TB。否则，迁移时间过长可能会导致迁移失败。

  • 热数据：热数据如果超过10TB，迁移任务失败率比较高，不建议您使用此方案进行迁移。

  如果数据不满足上述条件，迁移方案可选择手动迁移。

步骤一：自建集群检查并开启使用系统表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>

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

步骤三：（可选）目标集群开启使用MaterializedMySQL引擎。

如果自建集群中有引擎为MaterializedMySQL的表，您需执行下述语句，开启MaterializedMySQL引擎的使用。

SET GLOBAL allow_experimental_database_materialized_mysql = 1;

步骤四：创建迁移任务

1. 登录云数据库ClickHouse控制台。

2. 在集群列表页面，选择社区版实例列表，单击目标集群ID。

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

4. 在迁移任务页面，单击创建迁移任务。

   1. 配置源实例与目标实例。

      配置以下信息，单击测试连接以进行下一步。

      说明

      测试连接成功后，进入下一个步骤。如果测试连接失败，请根据提示，重新配置源实例和目标实例。

      

      源集群配置项

      配置项	说明	示例
      源端接入方式	固定选择专线/VPN网关/智能网关/ECS自建ClickHouse。	专线/VPN网关/智能网关/ECS自建ClickHouse
      集群名称	源集群的名称。 仅由阿拉伯数字和小写英文字母组成。	source
      源实例cluster名称	您需通过SELECT * FROM system.clusters;获取源实例cluster名称。	default
      VPC IP地址	集群每个shard的IP和PORT（即shard的TCP地址），并使用英文逗号隔开。 重要 不能使用云ClickHouse的VPC域名地址或者SLB地址。 格式：IP:PORT,IP:PORT,...... 根据自建上云的使用场景不同，集群IP和PORT的获取方法不同。 阿里云ClickHouse实例的跨账户、跨地域迁移 您可以使用以下SQL获取自建集群的IP和PORT。 SELECT shard_num, replica_num, host_address as ip, port FROM system.clusters WHERE cluster = 'default' and replica_num = 1; 其中replica_num=1表示选择第一个副本集，您也可以选择其他副本集或者自行挑选每个shard的一个副本组成。 非阿里云ClickHouse实例迁移 如果IP不便映射到阿里云，您可以使用以下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一个副本组成。 如果IP和端口发生了转换后映射到阿里云，则需要根据网络打通情况配置对应的IP和PORT。	192.168.0.5:9000,192.168.0.6:9000
      数据库账号	源集群数据库账号。	test
      数据库密码	源集群数据库账号密码。	test******

      目标集群配置项

      配置项	说明	示例
      数据库账号	目标集群数据库账号。	test
      数据库密码	目标群数据库账号密码。	test******

   2. 确认迁移内容。

      仔细阅读页面中数据迁移的包含内容提示信息，单击下一步：预检测并启动同步。

   3. 后台迁移链路预检测并启动任务。

      后台会对目标集群和自建集群进行实例状态检测、存储空间检测和本地表和分布式表检测。

      • 检测成功：

        检测成功后的界面如下图所示。

        

        1. 仔细阅读页面迁移过程中对实例的影响提示内容。

        2. 单击完成。

           重要

           • 单击完成后，任务创建完成且启动，任务状态为运行中，您可在任务列表查看任务。

           • 完成任务创建后，您还需监控迁移任务，在迁移完成的最后阶段，主动停写自建集群，进行剩余库表结构迁移。如何监控迁移任务，请参见监控迁移任务并停写自建集群。

      • 检测失败：您需要按照提示信息进行操作，重新进行数据迁移。检测内容及要求如下。检测报错信息以及解决方案，请参见迁移检查中报错信息查询及解决方案。

        检测项目	检测要求
        实例状态检测	迁移发起时，自建集群和目标集群不能有正在运行的管控任务（包含扩容，升降配等）。如果当前自建集群和目标集群有管控任务正在运行，则不能发起迁移任务。
        存储空间检测	迁移进行前，进行存储空间校验。保证目标集群的存储空间大于等于自建集群的已使用空间的1.2倍。
        本地表和分布式表检测	如果自建集群存在本地表没有创建分布式表或者分布式表不唯一，则校验失败。请删除多余的分布式表或创建唯一分布式表。

步骤一：元数据（建表的DDL）的迁移

ClickHouse元数据的迁移，主要指进行建表DDL迁移。

如需安装clickhouse-client工具，请安装与目标实例云数据库ClickHouse版本一致的clickhouse-client工具。下载链接，请参见clickhouse-client。

1. 查看自建集群的database列表。

   clickhouse-client --host="<old host>" --port="<old port>" --user="<old user name>" --password="<old password>" --query="SHOW databases"  > database.list

   参数说明：

   参数	描述
   old host	自建集群的地址。
   old port	自建集群的端口。
   old user name	登录自建集群的账号，拥有DML读写和设置权限，允许DDL权限。
   old password	上述账号对应的密码。

   说明

   system是系统数据库，不需要迁移，可以直接过滤掉。

2. 查看自建集群的table列表。

   clickhouse-client --host="<old host>" --port="<old port>" --user="<old user name>" --password="<old password>" --query="SHOW tables from <database_name>"  > table.list

   参数说明：

   参数	描述
   database_name	数据库名称

   您也可以通过系统表直接查询所有database和table名称。

   SELECT DISTINCT database, name FROM system.tables WHERE database != 'system';

   说明

   查询到的表名中，如果有以.inner.开头的表，则它们是物化视图的内部表示，不需要迁移，可以直接过滤掉。

3. 导出自建集群中指定数据库下所有表的建表DDL。

   clickhouse-client --host="<old host>" --port="<old port>" --user="<old user name>" --password="<old password>" --query="SELECT concat(create_table_query, ';') FROM system.tables WHERE database='<database_name>' FORMAT TabSeparatedRaw" > tables.sql

4. 将建表DDL导入到目标实例云数据库ClickHouse。

   说明

   您需要在建表DDL导入之前，在云数据库ClickHouse中创建表所在数据库。

   clickhouse-client --host="<new host>" --port="<new port>" --user="<new user name>" --password="<new password>"  -d '<database_name>'  --multiquery < tables.sql

   参数说明：

   参数	描述
   new host	目标实例云数据库ClickHouse的地址。
   new port	目标实例云数据库ClickHouse的端口。
   new user name	登录目标实例云数据库ClickHouse的账号，拥有DML读写和设置权限，允许DDL权限。
   new password	上述账号对应的密码。

步骤二：数据迁移