使用迁移工具快速迁移ClickHouse集群数据
本章节仅适用于MRS 3.2.0及之后版本。
操作场景
场景一：随着MRS ClickHouse业务数量的增长，原有集群的存储和计算资源已不满足业务需求，需要对集群进行拆分，将部分用户业务及数据库数据迁移到新建集群中。
场景二：MRS ClickHouse集群后端主机所在机房需要搬迁，需要将ClickHouse集群整体迁移到另外一个机房的新集群当中。
为了解决上述场景下对搬迁能力的要求，MRS提供了ClickHouse集群数据一键式工具搬迁能力，将源集群中的ClickHouse数据库、表对象DDL、业务数据迁移到新建集群中。
迁移方案原理介绍
- Replicated*MergeTree引擎的复制表迁移：
ClickHouse利用ZooKeeper将同一分片下不同副本的Replicated*MergeTree引擎表数据自动进行同步，本迁移方案利用该特性进行数据迁移。大致逻辑步骤如下：
首先，在目标集群的配置文件中添加源集群的ZooKeeper信息作为辅助ZooKeeper。其次，再在目标集群中创建和源集群相同ZooKeeper路径不同副本并且表结构和源集群一致的临时表。临时表创建完成源集群中的数据将会自动同步到临时表。最后，等待源集群数据同步到目标集群的临时表完成后，将目标集群中的临时表数据复制到正式表即可。图1 Replicated*MergeTree引擎表迁移架构图
- 分布式表迁移：
分布式表不涉及表数据，只涉及表的元数据信息，迁移过程中会将源集群ClickHouse分布式表的元数据信息导出，然后将元数据信息修改为目标集群的ZooKeeper路径和副本，根据修改后的元数据信息在目标集群新建表即可。
- 非复制表和物化视图迁移：
上述迁移的操作步骤通过迁移工具脚本做了封装处理，只需修改相关配置文件执行迁移脚本即可完成一键式迁移操作，具体可以参考操作步骤说明。
前提条件
- 待迁移的源ClickHouse集群状态正常，并且源集群和目的集群必须同为安全集群或者同为普通集群。如果集群模式都为普通模式，请联运维人员。
- 已创建待迁移数据的ClickHouse目标集群，该集群版本为MRS 3.1.3及以上版本。该ClickHouse集群的ClickHouserver实例数量需要大于等于源集群。
- 逻辑集群当前只支持副本数相同的集群间的数据搬迁。
迁移约束
- 该搬迁指导仅支持迁移表数据及表对象DDL元数据，用户业务ETL等SQL语句需要自行迁移。
- 为了保证迁移后源目标集群数据的一致性，迁移开始前需要短暂停止源集群的ClickHouse业务，具体停止时机请参考操作步骤说明。
- 搬迁过程中如果源集群表被删除，迁移程序无法自动处理该场景，需要手动进行处理。
迁移整体流程
阶段 |
流程说明 |
|---|---|
将源ClickHouse集群和目标ClickHouse集群的网络需要打通，保证两个集群ClickHouse实例节点网络可以互通。 |
|
通过在目标集群的ClickHouse配置文件中添加源集群的ZooKeeper信息，将源集群中的ZooKeeper作为迁移过程中的辅助ZooKeeper。 |
|
执行元数据迁移脚本，将源集群中的ClickHouse数据库和表的数据库名、表名、表结构等元数据信息迁移到目标集群。 |
|
执行数据迁移脚本，将源集群中的ClickHouse数据库和表的数据迁移至目标集群。 |
步骤1：源集群和目标集群网络打通
- 打通源集群和目标集群的网络。保证两个集群ClickHouse实例节点网络可以互通。
- 在目标集群的所有节点配置中添加源集群的hosts信息，同时在源集群的所有节点配置中添加目标集群的hosts信息。
- 登录源ClickHouse集群的FusionInsight Manager，选择“集群 > ClickHouse > 实例”，查看ClickHouseServer实例节点的业务IP地址。
- 使用ssh登录任意一个ClickHouseServer节点，执行以下命令查看源集群ClickHouse实例的hosts配置。
例如，如下示例显示命令查询示例集群查询结果，获取ClickHouse实例的主机配置信息。
- 登录目标ClickHouse集群的FusionInsight Manager，选择“集群 > ClickHouse > 实例”，查看目标集群ClickHouseServer实例节点的业务IP地址。
- 以root用户登录所有目标集群的ClickHouse实例节点，执行编辑命令修改节点的“/etc/hosts”配置。
vi /etc/hosts
将步骤2.b中获取的源集群ClickHouse实例的hosts信息，复制到该hosts文件中。
- 参考2.a到2.d将目标集群的节点IP信息添加到源集群节点hosts中。
- 源集群和目标集群之间配置系统互信。
步骤2：在目标集群配置文件中增加源集群的ZooKeeper信息
- 登录源集群的FusionInsight Manager，选择“集群 > 服务 > ZooKeeper > 实例”，查看源集群ZooKeeper实例quorumpeer的业务IP地址。
例如图3显示示例集群获取的ZooKeeper实例IP地址。
- 登录目标端FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“clickhouse-config-customize”配置项。
- 在“clickhouse-config-customize”配置项中，参考表2分别添加源集群的ZooKeeper实例信息。
表2 “clickhouse-config-customize”配置名称和值参考 名称
值
auxiliary_zookeepers.zookeeper2.node[1].host
1中获取的源集群第一个ZooKeeper实例quorumpeer的业务IP地址。注意：该参数当前仅支持配置ZooKeeper实例的IP地址，不支持配置主机名。
auxiliary_zookeepers.zookeeper2.node[1].port
2181
auxiliary_zookeepers.zookeeper2.node[2].host
1中获取的源集群第二个ZooKeeper实例quorumpeer的业务IP地址。注意：该参数当前仅支持配置ZooKeeper实例的IP地址，不支持配置主机名。
auxiliary_zookeepers.zookeeper2.node[2].port
2181
auxiliary_zookeepers.zookeeper2.node[3].host
1中获取的源集群第三个ZooKeeper实例quorumpeer的业务IP地址。注意：该参数当前仅支持配置ZooKeeper实例的IP地址，不支持配置主机名。
auxiliary_zookeepers.zookeeper2.node[3].port
2181
- 添加完配置后，单击“保存”，在弹出的对话框中单击“确定”完成配置保存。
- 保存成功后，以root用户登录任意一个目的集群的ClickHouseServer实例节点。执行以下命令查看ClickHouseServer实例信息。
ps -ef |grep clickhouse
根据查询的结果，获取“--config-file”参数值，即ClickHouseServer的配置文件config.xml目录。图4 获取ClickHouseServer配置文件目录
- 执行以下命令查看ClickHouse配置文件config.xml，可以看到<auxiliary_zookeepers>相关信息已添加成功。
- 在5中获取的配置文件目录下，执行以下命令获取源集群ZooKeeper的认证信息。
cat ENV_VARS | grep ZK
分别获取：ZK_SERVER_FQDN、ZK_USER_PRINCIPAL、ZK_USER_REALM三个参数的值。
- 登录目标端FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，在“ClickHouseServer（角色）”下选择“备份”，参考下表配置具体参数。
表3 配置源集群ZooKeeper认证信息 参数
值
AUXILIARY_ZK_SERVER_FQDN
在7中获取的ZK_SERVER_FQDN参数值。
AUXILIARY_ZK_SERVER_PRINCIPAL
在7中获取的ZK_USER_PRINCIPAL参数值。
AUXILIARY_ZK_SERVER_REALM
在7中获取的ZK_USER_REALM参数值。
METADATA_COLLECTION_TIMEOUT
配置为180。
含义为：元数据备份时等待其他节点完成的超时时间，单位为秒。
图6 配置源集群ZooKeeper认证信息
- 在“ClickHouseServer（角色）”下选择“存储”，修改参数max_partition_size_to_drop，max_table_size_to_drop值为0。
- 配置修改完成后，单击“保存”，在弹出的对话框中单击“确定”完成配置保存。
- 在ClickHouse服务页面，选择“实例”，勾选ClickHouseServer实例，选择“更多 > 重启实例”，重启ClickHouseServer实例。
步骤3：迁移源ClickHouse集群下数据库和表的元数据信息到目标集群
- 分别登录源和目标集群的FusionInsight Manager，创建迁移需要的用户名和密码，具体步骤如下。
- 登录Manager，选择“系统 > 权限 > 角色”，在“角色”界面单击“添加角色”按钮，进入添加角色页面。
- 在添加角色界面输入“角色名称”，例如ckrole，在配置资源权限处单击集群名称，进入服务列表页面，单击ClickHouse服务，进入ClickHouse权限资源页面。
- 勾选“ClickHouse管理员权限”，单击“确定”操作结束。
- 选择“系统 > 权限 > 用户”，单击“添加用户”，进入添加用户页面。
- “用户类型”选择“人机”，在“密码”和“确认密码”参数设置该用户对应的密码。
- 用户名：添加的用户名不能包含字符“-”，否则会导致认证失败。
- 密码：设置的密码不能携带“$”、“.”、“#”特殊字符，否则会导致认证失败。
- 在“角色”处单击“添加”，在弹框中选择1.b的角色名，单击“确定”添加到角色，单击“确定”完成操作。
- 创建完用户后，单击右上角的用户名，注销当前用户登录。使用新创建的用户名登录，根据提示修改当前用户密码。
- 下载和并使用omm安装ClickHouse客户端到目标集群。
- 使用omm用户登录到客户端节点，进入到“客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-metadata-migration”目录下配置迁移信息，执行以下命令，参考表4修改“example_config.yaml”配置文件。
cd 客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-metadata-migration
vi example_config.yaml
修改完配置后，请务必将所有#号的注释信息删除，只保留有效的配置信息，否则后续迁移脚本执行可能会报错。
表4 元数据example_config.yaml参数说明 配置项
配置子项
配置说明
source_cluster
host
源集群的任意一个ClickHouseServer节点的IP地址即可。
cluster_name
源集群ClickHouse的cluster名，可以参考从零开始使用ClickHouse使用客户端登录，执行以下命令获取，如果没有修改过，默认为：default_cluster。
select cluster,shard_num,replica_num,host_name from system.clusters;
https_port
可以登录源集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“https_port”参数获取。
zookeeper_root_path
可以登录源集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“clickhouse.zookeeper.root.path”参数获取。
system
系统参数。当前可不用配置，保持示例配置即可。
databases
可选配置。
- 如果指定该参数，则表示迁移源ClickHouse集群指定数据库的数据，可指定多个。配置参考如下：
databases: - "database" - "database_1"表示迁移源集群的database和database_1数据库。
- 如果不指定该参数，则表示迁移源ClickHouse集群所有数据库的表数据。databases参数配置保留为空即可，参考如下：
databases:
表示迁移源ClickHouse集群的所有数据库的表信息。
tables
可选配置。参数格式为：数据库名.表名。表名前的数据库名必须在databases参数列表中。
- 如果指定该参数，则表示迁移源ClickHouse集群数据库下的指定表数据，可指定多个。配置参考如下：
tables: - "database.table_1" - "database_1.table_2"表示迁移源集群的database数据库下的table_1数据和database_1数据库下的table_2数据。
- 如果不指定该参数，如果指定了databases参数则表示迁移databases数据库下的所有表数据，没有指定databases参数则表示迁移源ClickHouse集群所有数据库下的所有表数据。参考如下：
tables:
destination_cluster
host
目标集群的任意一个ClickHouseServer节点的IP地址即可。
cluster_name
目标集群ClickHouse的cluster名，可以参考从零开始使用ClickHouse使用客户端登录，执行以下命令获取，如果没有修改过，默认为：default_cluster。
select cluster,shard_num,replica_num,host_name from system.clusters;
user
1中创建的目标集群ClickHouse登录的用户名。
https_port
可以登录目标集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“https_port”参数获取。
zookeeper_root_path
可以登录目标集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“clickhouse.zookeeper.root.path”参数获取。
system
系统参数。当前可不用配置，保持示例配置即可。
- 如果指定该参数，则表示迁移源ClickHouse集群指定数据库的数据，可指定多个。配置参考如下：
- 执行以下命令，开始进行数据迁移，等待脚本执行完成。
./clickhouse_migrate_metadata.sh -f yaml_file
输入源集群、目的集群的用户名和密码
步骤4：迁移源ClickHouse集群下数据库和表数据到目标集群
- 使用omm用户登录到目标集群ClickHouse客户端节点的“客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-data-migration”目录下。
cd 客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-data-migration
- 执行以下命令，参考表5修改“example_config.yaml”配置文件。
vi example_config.yaml
修改完配置后，请务必将所有#号的注释信息删除，只保留有效的配置信息，否则后续迁移脚本执行可能会报错。表5 example_config.yaml参数说明 配置项
配置子项
配置说明
source_cluster
host
源集群的任意一个ClickHouseServer节点的IP地址即可。
cluster_name
源集群ClickHouse的cluster名，可以参考从零开始使用ClickHouse使用客户端登录，执行以下命令获取，如果没有修改过，默认为：default_cluster。
select cluster,shard_num,replica_num,host_name from system.clusters;
user
1中创建的源集群ClickHouse登录的用户名。
https_port
可以登录源集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“https_port”参数获取。
tcp_port
可以登录源集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，安全集群搜索“tcp_port_secure”参数获取，普通集群搜索“tcp_port”参数获取。
zookeeper_root_path
可以登录源集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“clickhouse.zookeeper.root.path”参数获取。
system
系统参数。当前可不用配置，保持示例配置即可。
databases
可选配置。
- 如果指定该参数，则表示迁移源ClickHouse集群指定数据库的数据，可指定多个。配置参考如下：
databases: - "database" - "database_1"表示迁移源集群的database和database_1数据库。
- 如果不指定该参数，则表示迁移源ClickHouse集群所有数据库的表数据。databases参数配置保留为空即可，参考如下：
databases:
表示迁移源ClickHouse集群的所有数据库的表信息。
tables
可选配置。参数格式为：数据库名.表名。表名前的数据库名必须在databases参数列表中。
- 如果指定该参数，则表示迁移源ClickHouse集群数据库下的指定表数据，可指定多个。配置参考如下：
tables: - "database.table_1" - "database_1.table_2"表示迁移源集群的database数据库下的table_1数据和database_1数据库下的table_2数据。
- 如果不指定该参数，如果指定了databases参数则表示迁移databases数据库下的所有表数据，没有指定databases参数则表示迁移源ClickHouse集群所有数据库下的所有表数据。参考如下：
tables:
destination_cluster
host
目标集群的任意一个ClickHouseServer节点的IP地址即可。
cluster_name
目标集群ClickHouse的cluster名，可以参考从零开始使用ClickHouse使用客户端登录，执行以下命令获取，如果没有修改过，默认为：default_cluster。
select cluster,shard_num,replica_num,host_name from system.clusters;
user
1中创建的目标集群ClickHouse登录的用户名。
https_port
可以登录目标集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“https_port”参数获取。
tcp_port
。可以登录目标集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，安全集群搜索“tcp_port_secure”参数获取，普通集群搜索“tcp_port”参数获取。
zookeeper_root_path
可以登录目标集群的FusionInsight Manager，选择“集群 > 服务 > ClickHouse > 配置 > 全部配置”，搜索“clickhouse.zookeeper.root.path”参数获取。
system
系统参数。当前可不用配置，保持示例配置即可。
auxiliary_zookeepers
name
在3中配置的源ClickHouse的ZooKeeper名。例如当前为zookeeper2。
hosts
源ClickHouse集群的ZooKeeper的实例IP地址。可以登录源集群的FusionInsight Manager，选择“集群 > 服务 > ZooKeeper > 实例”，查看源集群ZooKeeper实例quorumpeer的业务IP地址。
格式参考为：hosts: - "192.168.1.2" - "192.168.1.3" - "192.168.1.4"port
2181
execution_procedure
-
默认为空，表示执行一次脚本，将业务数据同步。参数还支持firststep和secondstep。
- firststep：表示只执行完成临时复制表的创建，通过辅助Zookeeper能够将原集群的数据实时同步到临时表。
- secondstep：表示将临时复制表里面的数据attach到目的集群的本地表中。
注意：
参数值为secondstep时，脚本执行前，需要运维人员和用户确认ClickHouse相关业务必须已经停止。
onereplica_use_auxiliaryzookeeper
-
- 参数值为1，表示只为shard里面的一个副本创建临时表。
- 参数值为0，表示为shard里面的两个副本创建临时表。
- 如果指定该参数，则表示迁移源ClickHouse集群指定数据库的数据，可指定多个。配置参考如下：
- 停止当前源集群的ClickHouse业务。
- 执行以下命令，开始进行数据迁移，等待脚本执行完成。
./clickhouse_migrate_data.sh -f yaml_file
输入源集群、目的集群的用户名和密码
- 脚本执行完成后，根据迁移结果日志确认源集群和目标集群迁移的数据是否一致，具体操作如下：
登录到目标集群ClickHouse客户端节点的“客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-data-migration/comparison_result”目录下。
对比如下迁移后的结果文件信息，确认迁移后源集群和目标集群数据的一致性：
- source_cluster_table_info：源集群迁出数据的统计
- destination_cluster_table_info：目标集群迁入的数据统计
- compare_result_file.txt：迁移前后数据一致性对比结果
对于迁移前后数据不一致的表，需要清空目的集群中该表的数据，并针对该表重新单独进行数据迁移或人工完成数据迁移。
另外，也可以分别登录到源和目标集群的ClickHouse数据库，手工查询表数据数量，分区个数等是否一致。
- 登录目标集群的FusionInsight Manager，将2在“clickhouse-config-customize”添加的ZooKeeper信息删除。
完成后单击“保存”，在弹出的对话框中单击“确定”完成配置保存。
- 数据迁移完成后，将业务指向迁移后的目标ClickHouse集群，完成业务切流。
- 分别进入到目标集群ClickHouse节点的“客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-data-migration”和“客户端安装目录/ClickHouse/clickhouse_migration_tool/clickhouse-metadata-migration”目录下。
vi example_config.yaml
将配置文件中password参数密码信息清除，防止密码泄露。
