跨集群数据迁移工具
StarRocks 跨集群数据迁移工具由 StarRocks 社区提供。您可以使用此工具轻松地将数据从源集群迁移到目标集群。
注意
- StarRocks 跨集群数据迁移工具仅支持将数据从 Shared-Nothing 集群迁移到另一个 Shared-Nothing 集群或 Shared-Data 集群。
- 目标集群的 StarRocks 版本必须是 v3.1.8、v3.2.3 或更高版本。
准备工作
必须在目标集群上执行以下准备工作才能进行数据迁移。
打开端口
如果您启用了防火墙，则必须打开这些端口
| 组件 | 端口 | 默认 |
|---|---|---|
| FE | query_port | 9030 |
| FE | http_port | 8030 |
| FE | rpc_port | 9020 |
| BE | be_http_port | 8040 |
| BE | be_port | 9060 |
启用复制的旧版兼容性
StarRocks 在旧版本和新版本之间的行为可能有所不同，这会导致跨集群数据迁移期间出现问题。因此，您必须在数据迁移之前为目标集群启用旧版兼容性，并在数据迁移完成后禁用它。
-
您可以使用以下语句检查是否启用了复制的旧版兼容性
ADMIN SHOW FRONTEND CONFIG LIKE 'enable_legacy_compatibility_for_replication';如果返回
true，则表示已启用复制的旧版兼容性。 -
动态启用复制的旧版兼容性
ADMIN SET FRONTEND CONFIG("enable_legacy_compatibility_for_replication"="true"); -
为防止在集群重启的情况下数据迁移过程中自动禁用复制的旧版兼容性，您还需要在 FE 配置文件 fe.conf 中添加以下配置项
enable_legacy_compatibility_for_replication = true
数据迁移完成后，您需要从配置文件中删除配置 enable_legacy_compatibility_for_replication = true，并使用以下语句动态禁用复制的旧版兼容性
ADMIN SET FRONTEND CONFIG("enable_legacy_compatibility_for_replication"="false");
配置数据迁移（可选）
您可以使用以下 FE 和 BE 参数配置数据迁移操作。在大多数情况下，默认配置可以满足您的需求。如果您想使用默认配置，可以跳过此步骤。
注意
请注意，增加以下配置项的值可以加速迁移，但也会增加源集群的负载压力。
FE 参数
以下 FE 参数是动态配置项。有关如何修改它们，请参阅配置 FE 动态参数。
| 参数 | 默认 | 单位 | 描述 |
|---|---|---|---|
| replication_max_parallel_table_count | 100 | - | 允许的最大并发数据同步任务数。StarRocks 为每个表创建一个同步任务。 |
| replication_max_parallel_replica_count | 10240 | - | 允许并发同步的最大 tablet 副本数。 |
| replication_max_parallel_data_size_mb | 1048576 | MB | 允许并发同步的最大数据大小。 |
| replication_transaction_timeout_sec | 86400 | 秒 | 同步任务的超时时间。 |
BE 参数
以下 BE 参数是动态配置项。有关如何修改它，请参阅配置 BE 动态参数。
| 参数 | 默认 | 单位 | 描述 |
|---|---|---|---|
| replication_threads | 0 | - | 用于执行同步任务的线程数。0 表示将线程数设置为 BE 所在机器上的 CPU 核心数的 4 倍。 |
步骤 1：安装工具
建议在目标集群所在的服务器上安装迁移工具。
-
启动终端，下载该工具的二进制包。
wget https://releases.starrocks.io/starrocks/starrocks-cluster-sync.tar.gz -
解压包。
tar -xvzf starrocks-cluster-sync.tar.gz
步骤 2：配置工具
迁移相关配置
导航到解压后的文件夹，修改配置文件 conf/sync.properties。
cd starrocks-cluster-sync
vi conf/sync.properties
文件内容如下
# If true, all tables will be synchronized only once, and the program will exit automatically after completion.
one_time_run_mode=false
source_fe_host=
source_fe_query_port=9030
source_cluster_user=root
source_cluster_password=
source_cluster_password_secret_key=
source_cluster_token=
target_fe_host=
target_fe_query_port=9030
target_cluster_user=root
target_cluster_password=
target_cluster_password_secret_key=
# Comma-separated list of database names or table names like <db_name> or <db_name.table_name>
# example: db1,db2.tbl2,db3
# Effective order: 1. include 2. exclude
include_data_list=
exclude_data_list=
# If there are no special requirements, please maintain the default values for the following configurations.
target_cluster_storage_volume=
target_cluster_replication_num=-1
target_cluster_max_disk_used_percent=80
# To maintain consistency with the source cluster, use null.
target_cluster_enable_persistent_index=
max_replication_data_size_per_job_in_gb=1024
meta_job_interval_seconds=180
meta_job_threads=4
ddl_job_interval_seconds=10
ddl_job_batch_size=10
# table config
ddl_job_allow_drop_target_only=false
ddl_job_allow_drop_schema_change_table=true
ddl_job_allow_drop_inconsistent_partition=true
ddl_job_allow_drop_inconsistent_time_partition = true
ddl_job_allow_drop_partition_target_only=true
# index config
enable_bitmap_index_sync=false
ddl_job_allow_drop_inconsistent_bitmap_index=true
ddl_job_allow_drop_bitmap_index_target_only=true
# MV config
enable_materialized_view_sync=false
ddl_job_allow_drop_inconsistent_materialized_view=true
ddl_job_allow_drop_materialized_view_target_only=false
# View config
enable_view_sync=false
ddl_job_allow_drop_inconsistent_view=true
ddl_job_allow_drop_view_target_only=false
replication_job_interval_seconds=10
replication_job_batch_size=10
report_interval_seconds=300
enable_table_property_sync=false
参数描述如下
| 参数 | 描述 |
|---|---|
| one_time_run_mode | 是否启用一次性同步模式。启用一次性同步模式后，迁移工具仅执行完全同步，而不执行增量同步。 |
| source_fe_host | 源集群的 FE 的 IP 地址或 FQDN（完全限定域名）。 |
| source_fe_query_port | 源集群的 FE 的查询端口 (query_port)。 |
| source_cluster_user | 用于登录源集群的用户名。必须授予该用户 SYSTEM 级别的 OPERATE 权限。 |
| source_cluster_password | 用于登录源集群的用户密码。 |
| source_cluster_password_secret_key | 用于加密源集群登录用户密码的密钥。默认值是一个空字符串，表示登录密码未加密。如果要加密 source_cluster_password，可以使用 SQL 语句 SELECT TO_BASE64(AES_ENCRYPT('<source_cluster_password>','<source_cluster_password_ secret_key>')) 获取加密的 source_cluster_password 字符串。 |
| source_cluster_token | 源集群的 Token。有关如何获取集群 Token 的信息，请参阅下面的获取集群 Token。 |
| target_fe_host | 目标集群的 FE 的 IP 地址或 FQDN（完全限定域名）。 |
| target_fe_query_port | 目标集群的 FE 的查询端口 (query_port)。 |
| target_cluster_user | 用于登录目标集群的用户名。必须授予该用户 SYSTEM 级别的 OPERATE 权限。 |
| target_cluster_password | 用于登录目标集群的用户密码。 |
| target_cluster_password_secret_key | 用于加密目标集群登录用户密码的密钥。默认值是一个空字符串，表示登录密码未加密。如果要加密 target_cluster_password，可以使用 SQL 语句 SELECT TO_BASE64(AES_ENCRYPT('<target_cluster_password>','<target_cluster_password_ secret_key>')) 获取加密的 target_cluster_password 字符串。 |
| include_data_list | 需要迁移的数据库和表，多个对象用逗号 (,) 分隔。例如：db1, db2.tbl2, db3。此项优先于 exclude_data_list 生效。如果要迁移集群中的所有数据库和表，则无需配置此项。 |
| exclude_data_list | 不需要迁移的数据库和表，多个对象用逗号 (,) 分隔。例如：db1, db2.tbl2, db3。include_data_list 优先于此项生效。如果要迁移集群中的所有数据库和表，则无需配置此项。 |
| target_cluster_storage_volume | 当目标集群是 Shared-Data 集群时，用于存储目标集群中表的存储卷。如果要使用默认存储卷，则无需指定此项。 |
| target_cluster_replication_num | 在目标集群中创建表时指定的副本数。如果要使用与源集群相同的副本数，则无需指定此项。 |
| target_cluster_max_disk_used_percent | 当目标集群是 Shared-Nothing 时，目标集群的 BE 节点的磁盘使用率百分比阈值。当目标集群中任何 BE 的磁盘使用率超过此阈值时，迁移将终止。默认值为 80，表示 80%。 |
| meta_job_interval_seconds | 迁移工具从源集群和目标集群检索元数据的间隔（以秒为单位）。您可以为此项使用默认值。 |
| meta_job_threads | 迁移工具用于从源集群和目标集群获取元数据的线程数。您可以为此项使用默认值。 |
| ddl_job_interval_seconds | 迁移工具在目标集群上执行 DDL 语句的间隔（以秒为单位）。您可以为此项使用默认值。 |
| ddl_job_batch_size | 在目标集群上执行 DDL 语句的批处理大小。您可以为此项使用默认值。 |
| ddl_job_allow_drop_target_only | 是否允许迁移工具删除仅存在于目标集群中而不存在于源集群中的数据库或表。默认值为 false，表示不会删除它们。您可以为此项使用默认值。 |
| ddl_job_allow_drop_schema_change_table | 是否允许迁移工具删除源集群和目标集群之间架构不一致的表。默认值为 true，表示将删除它们。您可以为此项使用默认值。迁移工具将在迁移期间自动同步已删除的表。 |
| ddl_job_allow_drop_inconsistent_partition | 是否允许迁移工具删除源集群和目标集群之间数据分布不一致的分区。默认值为 true，表示将删除它们。您可以为此项使用默认值。迁移工具将在迁移期间自动同步已删除的分区。 |
| ddl_job_allow_drop_partition_target_only | 是否允许迁移工具删除在源集群中删除的分区，以保持源集群和目标集群之间的分区一致。默认值为 true，表示将删除它们。您可以为此项使用默认值。 |
| replication_job_interval_seconds | 迁移工具触发数据同步任务的间隔（以秒为单位）。您可以为此项使用默认值。 |
| replication_job_batch_size | 迁移工具触发数据同步任务的批处理大小。您可以为此项使用默认值。 |
| max_replication_data_size_per_job_in_gb | 迁移工具触发数据同步任务的数据大小阈值。单位：GB。如果要迁移的分区的大小超过此值，将触发多个数据同步任务。默认值为 1024。您可以为此项使用默认值。 |
| report_interval_seconds | 迁移工具打印进度信息的时间间隔。单位：秒。默认值：300。您可以为此项使用默认值。 |
| target_cluster_enable_persistent_index | 是否在目标集群中启用持久化索引。如果未指定此项，则目标集群与源集群一致。 |
| ddl_job_allow_drop_inconsistent_time_partition | 是否允许迁移工具删除源集群和目标集群之间时间不一致的分区。默认值为 true，表示将删除它们。您可以为此项使用默认值。迁移工具将在迁移期间自动同步已删除的分区。 |
| enable_bitmap_index_sync | 是否启用 Bitmap 索引的同步。 |
| ddl_job_allow_drop_inconsistent_bitmap_index | 是否允许迁移工具删除源集群和目标集群之间不一致的 Bitmap 索引。默认值为 true，表示将删除它们。您可以为此项使用默认值。迁移工具将在迁移期间自动同步已删除的索引。 |
| ddl_job_allow_drop_bitmap_index_target_only | 是否允许迁移工具删除在源集群中删除的 Bitmap 索引，以保持源集群和目标集群之间的索引一致。默认值为 true，表示将删除它们。您可以为此项使用默认值。 |
| enable_materialized_view_sync | 是否启用物化视图的同步。 |
| ddl_job_allow_drop_inconsistent_materialized_view | 是否允许迁移工具删除源集群和目标集群之间不一致的物化视图。默认值为 true，表示将删除它们。您可以为此项使用默认值。迁移工具将在迁移期间自动同步已删除的物化视图。 |
| ddl_job_allow_drop_materialized_view_target_only | 是否允许迁移工具删除在源集群中删除的物化视图，以保持源集群和目标集群之间的物化视图一致。默认值为 true，表示将删除它们。您可以为此项使用默认值。 |
| enable_view_sync | 是否启用视图的同步。 |
| ddl_job_allow_drop_inconsistent_view | 是否允许迁移工具删除源集群和目标集群之间不一致的视图。默认值为 true，表示将删除它们。您可以为此项使用默认值。迁移工具将在迁移期间自动同步已删除的视图。 |
| ddl_job_allow_drop_view_target_only | 是否允许迁移工具删除在源集群中删除的视图，以保持源集群和目标集群之间的视图一致。默认值为 true，表示将删除它们。您可以为此项使用默认值。 |
| enable_table_property_sync | 是否启用表属性的同步。 |
获取集群 Token
集群 Token 可在 FE 元数据中找到。登录到 FE 节点所在的服务器并运行以下命令
cat fe/meta/image/VERSION | grep token
输出
token=wwwwwwww-xxxx-yyyy-zzzz-uuuuuuuuuu
网络相关配置（可选）
在数据迁移期间，迁移工具需要访问源集群和目标集群的所有 FE 节点，并且目标集群需要访问源集群的所有 BE 和 CN 节点。
您可以通过在相应的集群上执行以下语句来获取这些节点的网络地址
-- Obtain the network addresses of FE nodes in a cluster.
SHOW FRONTENDS;
-- Obtain the network addresses of BE nodes in a cluster.
SHOW BACKENDS;
-- Obtain the network addresses of CN nodes in a cluster.
SHOW COMPUTE NODES;
如果这些节点使用集群外部无法访问的私有地址，例如 Kubernetes 集群内的内部网络地址，则需要将这些私有地址映射到可以从外部访问的地址。
导航到该工具的解压后的文件夹，并修改配置文件 conf/hosts.properties。
cd starrocks-cluster-sync
vi conf/hosts.properties
该文件的默认内容如下，描述了如何配置网络地址映射
# <SOURCE/TARGET>_<domain>=<IP>
以下示例执行以下操作
- 将源集群的私有网络地址
192.1.1.1和192.1.1.2映射到10.1.1.1和10.1.1.2。 - 将目标集群的私有网络地址
fe-0.starrocks.svc.cluster.local映射到10.1.2.1。
# <SOURCE/TARGET>_<domain>=<IP>
SOURCE_192.1.1.1=10.1.1.1
SOURCE_192.1.1.2=10.1.1.2
TARGET_fe-0.starrocks.svc.cluster.local=10.1.2.1
步骤 3：启动迁移工具
配置该工具后，启动迁移工具以启动数据迁移过程。
./bin/start.sh
注意
- 确保源集群和目标集群的 BE 节点可以通过网络正常通信。
- 在运行时，迁移工具会定期检查目标集群中的数据是否落后于源集群。如果存在滞后，它将启动数据迁移任务。
- 如果新数据不断加载到源集群中，则数据同步将继续，直到目标集群中的数据与源集群中的数据一致为止。
- 您可以在迁移期间查询目标集群中的表，但不要将新数据加载到表中，因为这可能会导致目标集群和源集群中的数据不一致。目前，迁移工具不会禁止在迁移期间将数据加载到目标集群中。
- 请注意，数据迁移不会自动终止。您需要手动检查并确认迁移完成，然后停止迁移工具。
查看迁移进度
查看迁移工具日志
您可以通过迁移工具日志 log/sync.INFO.log 查看迁移进度。
示例 1：查看任务进度。
重要的指标如下
Sync job progress：数据迁移的进度。迁移工具会定期检查目标集群中的数据是否落后于源集群。因此，100% 的进度仅表示数据同步在当前检查间隔内完成。如果新数据继续加载到源集群中，则进度可能会在下一个检查间隔内降低。total：此迁移操作中所有类型的作业总数。ddlPending：待执行的 DDL 作业数。jobPending：待执行的挂起数据同步作业数。sent：从源集群发送但尚未启动的数据同步作业数。从理论上讲，此值不应太大。如果该值不断增加，请联系我们的工程师。running：当前正在运行的数据同步作业数。finished：已完成的数据同步作业数。failed：失败的数据同步作业数。失败的数据同步作业将被重新发送。因此，在大多数情况下，您可以忽略此指标。如果此值非常大，请联系我们的工程师。unknown：状态未知的作业数。从理论上讲，此值应始终为0。如果此值不为0，请联系我们的工程师。
示例 2：查看表迁移进度。
Sync table progress：表迁移进度，即在此迁移任务中已迁移的表与需要迁移的所有表的比率。finishedTableRatio：至少成功执行一个同步任务的表的比率。expiredTableRatio：具有过期数据的表的比率。total table：参与此数据迁移进度的表总数。finished table：至少成功执行一个同步任务的表的数量。unfinished table：没有同步任务执行的表的数量。expired table：具有过期数据的表的数量。
查看迁移事务状态
迁移工具为每个表打开一个事务。您可以通过检查其相应事务的状态来查看表的迁移状态。
SHOW PROC "/transactions/<db_name>/running";
<db_name> 是表所在的数据库的名称。
查看分区数据版本
您可以比较源集群和目标集群中相应分区的数据版本，以查看该分区的迁移状态。
SHOW PARTITIONS FROM <table_name>;
<table_name> 是分区所属的表的名称。
查看数据量
您可以比较源集群和目标集群中的数据量以查看迁移状态。
SHOW DATA;
查看表行数
您可以比较源集群和目标集群中的表行数，以查看每个表的迁移状态。
SELECT
TABLE_NAME,
TABLE_ROWS
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_TYPE = 'BASE TABLE'
ORDER BY TABLE_NAME;
限制
当前支持同步的对象列表如下（未包含的对象表示不支持同步）
- 数据库
- 内部表及其数据
- 物化视图架构及其构建语句（物化视图中的数据不会被同步。并且如果物化视图的基础表未同步到目标集群，则物化视图的后台刷新任务会报告错误。）
- 逻辑视图