跨集群数据迁移工具
StarRocks 跨集群数据迁移工具由 StarRocks 社区提供。您可以使用此工具轻松地将数据从源集群迁移到目标集群。
注意
- StarRocks 跨集群数据迁移工具仅支持将数据从共享无关（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=
jdbc_connect_timeout_ms=30000
jdbc_socket_timeout_ms=60000
# 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 字符串。 |
| jdbc_connect_timeout_ms | FE 查询的 JDBC 连接超时时间（毫秒）。默认值：30000。 |
| jdbc_socket_timeout_ms | FE 查询的 JDBC 套接字超时时间（毫秒）。默认值：60000。 |
| include_data_list | 需要迁移的数据库和表，多个对象用逗号（,）分隔。例如：db1, db2.tbl2, db3。此项的优先级高于 exclude_data_list。如果要迁移集群中所有的数据库和表，则无需配置此项。 |
| exclude_data_list | 不需要迁移的数据库和表，多个对象用逗号（,）分隔。例如：db1, db2.tbl2, db3。include_data_list 的优先级高于此项。如果要迁移集群中所有的数据库和表，则无需配置此项。 |
| target_cluster_storage_volume | 目标集群为共享数据集群时，用于存储表的存储卷。如果希望使用默认存储卷，则无需指定此项。 |
| target_cluster_replication_num | 在目标集群创建表时指定的副本数。如果希望使用与源集群相同的副本数，则无需指定此项。 |
| target_cluster_max_disk_used_percent | 目标集群为共享无关集群时，目标集群 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>_<host>=<mappedHost>[;<srcPort>:<dstPort>[,<srcPort>:<dstPort>...]]
注意
<host> 必须与 SHOW FRONTENDS、SHOW BACKENDS 或 SHOW COMPUTE NODES 返回的 IP 列中显示的地址匹配。
以下示例执行了这些操作
- 将源集群的私有网络地址
192.1.1.1和192.1.1.2映射到10.1.1.1和10.1.1.2。 - 将源集群的 FE 端口
8030和9030在10.1.1.1上映射到38030和39030。 - 将目标集群的私有网络地址
fe-0.starrocks.svc.cluster.local映射到10.1.2.1并重新映射端口9030。
# <SOURCE/TARGET>_<host>=<mappedHost>[;<srcPort>:<dstPort>[,<srcPort>:<dstPort>...]]
SOURCE_192.1.1.1=10.1.1.1;8030:38030,9030:39030
SOURCE_192.1.1.2=10.1.1.2
TARGET_fe-0.starrocks.svc.cluster.local=10.1.2.1;9030:19030
步骤 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;
限制
当前支持同步的对象列表如下（未包含的表示不支持同步）
- 数据库
- 内部表及其数据
- 物化视图的 Schema 及其构建语句（物化视图中的数据不会被同步。如果物化视图的基础表未同步到目标集群，物化视图的后台刷新任务会报错。）
- 逻辑视图
