StarRocks跨集群数据迁移工具

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

本文将指导您如何使用StarRocks跨集群数据迁移工具,在源集群保持在线且业务服务不中断的状态下高效、安全地进行数据复制。该工具提供全量及增量同步功能,旨在为您提供一键式解决方案,实现源集群数据无缝迁移至目标集群,确保数据一致性的同时,最大限度减少对业务运营的影响。

适用场景

StarRocks跨集群数据迁移工具适用于以下迁移场景,包括:

  • 自建StarRocks集群向Serverless StarRocks的升级迁移。

  • EMR on ECS(半托管)集群向Serverless StarRocks的升级迁移。

  • Serverless StarRocks实例间的数据迁移。

前提条件

  • 需要购买单独的ECS实例部署迁移工具,且部署迁移工具的ECS实例和源集群、目标集群的网络互通,具体网络交互和使用端口如下所示。

    ECS控制台创建实例,详情请参见自定义购买实例

    说明

    建议选择至少4 vCPU 8.0 GiB或更高规格的实例,以确保迁移工具能够高效运行。

    image

    涉及的默认端口如下表所示。

    端口名称

    默认端口号

    FE QueryPort

    9030

    FE RpcPort

    9020

    FE HttpPort

    8030

    BE BePort

    9060

    BE HttpPort

    8040

    说明

    如未使用默认端口,请通过SHOW FRONTENDS;SHOW BACKENDS;命令确认实际端口。

  • 网络连通性检查

    • 检查迁移工具所在ECS节点的网络联通性

      校验目标:确保ECS节点到源集群和目标集群的网络链路畅通(对应上图中的链路1、2、3、48)。

      ECS节点上执行telnet命令,检查ECS到源集群和目标集群各端口的连通情况。

      telnet <source_fe_ip> 9030
      telnet <source_fe_ip> 9020
      telnet <source_fe_ip> 8030
      
      telnet <target_fe_ip> 9030
      telnet <target_fe_ip> 9020
      telnet <target_fe_ip> 8030

      其中,<source_fe_ip>和<target_fe_ip>分别为SHOW FRONTENDS输出中的IP地址字段。

    • 检查集群间的网络连通性

      校验目标:确保目标集群到源集群的网络链路畅通(对应上图中的链路6、7)。

      您需要确认目标集群可以连接到源集群每个BE节点的IP地址,并确保能够访问该IP90608040端口。

      • 为保障网络互通,可以考虑从网络规划层面出发,例如确保两者部署在同一VPC中,或者通过专线、VPN等方式建立稳定的连接。

      • 如果仍有连接问题,请联系我们,我们将协助您进一步定位和解决问题。

使用限制

  • 源集群要求:仅支持源集群为存算一体集群,源集群版本无要求。

  • 目标集群要求:目标集群类型无要求,但目标集群小版本必须为3.1.9、3.2.4及其之后的版本。不支持迁移至2.x系列版本的集群。

    如果您的目标集群版本低于所需版本,建议您提交工单升级到合适的小版本。

  • 迁移的内容:

    • 仅支持同步内表,视图和物化视图,暂不支持外表迁移。

    • 暂不支持迁移包含自增列AUTO_INCREMENT的数据表。

注意事项

  • 数据迁移功能目前处于公测阶段。迁移完成后,请务必进行充分测试,验证数据的完整性和系统的正常运行,以确保业务不受影响。

  • 在数据迁移阶段,您可以对目标集群中正在迁移的表进行查询操作,但禁止在目标集群对正在同步的表上执行写入和更改表数据,以及更改和删除数据表操作,以避免同步数据错乱。

  • 如果数据迁移的目标集群为存算分离集群,在将数据迁移到存算分离集群之前,您需要先手动关闭目标集群的Compaction,迁移完成后尽快启用Compaction。

    1. 查看Compaction状态。

      StarRocks实例的参数配置页面,搜索并查看lake_compaction_max_tasks参数的值。

      • 如果参数值为0,则表示Compaction已关闭,无需调整。

      • 如果参数值不为0,需要手动修改该参数以关闭Compaction。

    2. 关闭Compaction。

      StarRocks实例的参数配置页面,将lake_compaction_max_tasks参数设置为0,以关闭Compaction功能。

      lake_compaction_max_tasks = 0

      修改完成后,提交参数修改并重启目标集实例以使更改生效。

    3. 恢复Compaction。

      警告

      使用迁移工具完成数据迁移后,请务必及时恢复Compaction功能,以确保目标集群的性能和数据管理能力。

      StarRocks实例的参数配置页面,将lake_compaction_max_tasks参数设置不为0,然后重启集群以恢复Compaction功能。

迁移流程

准备工作

配置目标集群参数

根据目标集群的类型(存算一体或存算分离),提前设置以下参数。迁移完成后,请及时恢复默认配置。

  • 迁移到存算一体集群

    SQL Editor中执行以下命令,配置目标集群参数。

    ADMIN SET FRONTEND CONFIG ('emr_serveless_replication_enable' = 'true');
    ADMIN SET FRONTEND CONFIG('enable_legacy_compatibility_for_replication'='true');
    SET GLOBAL enable_filter_unused_columns_in_scan_stage=false;
  • 迁移到存算分离集群

    重要

    存算分离迁移过程中需要关闭Compaction,这可能会对线上业务产生影响。因此,请尽快完成迁移并迅速恢复相关配置。

    • SQL Editor中执行以下命令,配置目标集群参数。

      ADMIN SET FRONTEND CONFIG ('emr_serveless_replication_enable' = 'true');
      ADMIN SET FRONTEND CONFIG('enable_legacy_compatibility_for_replication'='true');
      SET GLOBAL enable_filter_unused_columns_in_scan_stage=false;
    • StarRocks实例的参数配置页面,将lake_compaction_max_tasks参数设置为0,以关闭Compaction功能。

配置数据迁移(可选)

您可以根据需求调整以下FEBE参数来优化数据迁移操作。通常情况下,默认配置已足够满足大多数场景的需求。如果您对性能要求较高,可以适当调整这些参数以加速迁移,但需要注意,增大这些配置项可能会增加源集群的负载压力。

  • FE参数

    参数

    默认值

    描述

    replication_max_parallel_table_count

    100

    允许同时执行的数据同步任务数。每个表对应一个同步任务。

    replication_max_parallel_data_size_mb

    1048576

    允许并发同步的最大数据量。单位为MB。

    replication_max_parallel_replica_count

    10240

    同步任务的超时时间,超过该时间未完成的任务将被终止。单位为秒。

  • BE参数

    参数

    默认值

    描述

    replication_threads

    0

    执行同步任务的线程数。设置为0时,线程数等于BE所在机器的CPU核数。

步骤一:获取源集群或实例的Token

  • 自建集群或EMR on ECS(半托管)集群

    (推荐)方法一:通过FE节点的元数据获取Token

    登录FE节点所在的服务器,执行以下命令获取集群Token。

    cat fe/meta/image/VERSION | grep token

    如果您使用的是EMR on ECS的集群,请登录集群Master节点,然后执行以下命令获取集群token。

    cat /mnt/disk1/starrocks/meta/image/VERSION | grep token

    返回信息如下所示。其中token字段即为当前集群的Token。

    token=wwwwwwww-xxxx-yyyy-zzzz-uuuuuuuuuu

    方法二:通过FEHTTP端口获取Token

    在源集群的FE节点上,执行以下命令获取Token。

    curl -v http://<fe_host>:<fe_http_port>/check

    其中,涉及参数如下:

    • <fe_host>:集群FEIP地址或FQDN。

    • <fe_http_port>:集群FEHTTP端口(默认为8030,EMR半托管环境为18030)。

    如果您使用的是EMR on ECS的集群,则命令执行后会返回类似以下内容。其中token字段即为当前集群的Token。

    * Trying xxx.xx.xxx.xx...
    * TCP_NODELAY set
    * Connected to xxx.xx.xxx.xx (xxx.xx.xxx.xx) port 18030 (#0)
    > GET /check HTTP/1.1
    > Host: xxx.xx.xxx.xx:18030
    > User-Agent: curl/7.29.0
    > Accept: */*
    >
    < HTTP/1.1 200 OK
    < content-length: 0
    < cluster_id: yyyyyyyyyyy
    < content-type: text/html
    < token: wwwwwwww-xxxx-yyyy-zzzz-uuuuuuuuuu
    < connection: keep-alive
    <
    * Connection #0 to host xxx.xx.xxx.xx left intact
  • Serverless StarRocks实例

    在进行Serverless StarRocks实例间的数据迁移时,您可以在StarRocks实例的实例详情页面的基础信息区域,单击获取迁移Token,以获取待迁移实例所需的Token。

步骤二:下载迁移工具

单击starrocks-cluster-sync-2.0.1.tar.gz以获取EMR Serverless StarRocks迁移工具。

步骤三:配置迁移工具

  1. 连接ECS实例,并上传获取到的迁移工具,详情请参见连接实例使用Workbench上传或下载文件

  2. 配置迁移工具。

    修改starrocks-cluster-sync-2.0.1/conf/目录下的sync.properties配置文件。

    必填参数

    以下参数是迁移任务成功运行所必需的,请根据实际环境正确配置。

    参数

    说明

    one_time_run_mode

    选择是否关闭增量同步模式,默认值为false。启用后,系统将仅执行一次全量数据同步而不进行后续的增量数据更新,即每张表将只同步一次。

    source_fe_host

    源集群FEIP地址或FQDN。

    source_fe_query_port

    源集群FE的查询端口(query_port)。

    source_cluster_user

    用于登录源集群的用户名。

    source_cluster_password

    用于登录源集群的用户密码。

    source_cluster_token

    源集群的Token。

    target_fe_host

    目标集群FEIP地址或FQDN。

    target_fe_query_port

    目标集群FE的查询端口(query_port)。

    target_cluster_user

    用于登录目标集群的用户名。

    target_cluster_password

    用于登录目标集群的用户密码。

    include_data_list

    需要迁移的数据库和表,多个对象时使用逗号(,)分隔。例如,db1,db2.tbl2,db3。该参数优先于 exclude_data_list生效。

    说明

    如果您需要迁移集群中所有数据库和表,则无须配置该项。

    exclude_data_list

    不需要迁移的数据库和表,多个对象时使用逗号(,)分隔。例如,db1,db2.tbl2,db3include_data_list优先于该参数生效。

    说明

    如果您需要迁移集群中所有数据库和表,则无须配置该项。

    可选参数

    以下参数可以根据需求进行调整,但通常保持默认值即可。

    参数

    说明

    target_cluster_storage_volume

    当目标集群是存算分离集群时,用于指定待迁移的表所在的Storage Volume,默认为空,表示使用目标集群的默认存储卷。

    target_cluster_replication_num

    指定目标集群表的副本数量,默认为 -1,表示目标集群表的副本数量与源集群保持一致。

    target_cluster_max_disk_used_percent

    迁移工具对目标集群 BE 磁盘检查阈值,当任何一个 BE 的最大磁盘使用率大于这个配置的百分比,迁移工具会自动退出,防止磁盘打满。默认为90

    max_replication_data_size_per_job_in_gb

    迁移工具产生同步任务时,该任务包含的最大差异数据量,分区粒度,默认为 -1 表示不限制。

    非必要不调整的参数

    以下参数通常可以使用默认值,无需调整。仅在特殊场景下需要修改时,请根据实际需求进行调整。

    参数

    默认值

    说明

    meta_job_interval_seconds

    180

    迁移工具获取源集群和目标集群元数据的周期,单位为秒。

    meta_job_threads

    4

    迁移工具获取源集群和目标集群元数据的线程数量。

    ddl_job_interval_seconds

    10

    迁移工具在目标集群执行DDL的周期,单位为秒。

    ddl_job_batch_size

    10

    迁移工具在目标集群执行DDL的批大小。

    ddl_job_allow_drop_target_only

    false

    迁移工具是否自动删除仅在目标集群存在而源集群不存在的数据库和数据表。

    ddl_job_allow_drop_partition_target_only

    true

    迁移工具是否自动删除仅在目标集群存在而源集群不存在的分区。

    ddl_job_allow_drop_schema_change_table

    true

    迁移工具是否自动删除源集群和目标集群Schema不一致的表。

    ddl_job_allow_drop_inconsistent_partition

    true

    迁移工具是否自动删除源集群和目标集群数据分布方式不一致的分区。

    ddl_job_allow_drop_materialized_view_target_only

    false

    迁移工具是否自动删除仅在目标集群存在而源集群不存在的物化视图。

    ddl_job_allow_drop_view_target_only

    false

    迁移工具是否自动删除仅在目标集群存在而源集群不存在的逻辑视图。

    ddl_job_allow_drop_bitmap_index_target_only

    true

    迁移工具是否自动删除仅在目标集群存在而源集群不存在的bitmap索引。

    replication_job_interval_seconds

    15

    迁移工具触发数据同步任务的周期,单位为秒。

    replication_job_batch_size

    10

    迁移工具触发数据同步任务的批大小。

    compaction_job_interval_seconds

    30

    迁移工具在目标集群对迁移完成的表执行Compaction的周期,单位为秒。

    compaction_job_batch_size

    10

    迁移工具在目标集群对迁移完成的表执行Compaction的批大小。

步骤四:启动迁移工具

ECS实例中执行以下命令,启动迁移工具,开始数据迁移。

./bin/start.sh
说明
  • 迁移工具将定期检查目标集群的数据状态,以确认其是否与源集群同步。如果发现目标集群数据版本落后,工具将自动启动新的数据迁移任务。

  • 若源集群在迁移过程中不断有新数据加入,数据同步将持续进行直到目标集群的数据完全与源集群相匹配。

  • 请注意,数据迁移进程并不会自动结束。您必须定期手动监测数据同步状态,并在确认数据迁移完全完成之后主动停止迁移工具。

步骤五:查看迁移进度

查看迁移工具日志

您可以通过迁移工具日志log/sync.INFO.log查看迁移进度,包括同步任务进度和同步表进度。

  • 正在同步的表

    image

    搜索关键字Running table detail,会输出当前正在迁移的表名称。

  • 同步任务进度

    image

    搜索关键字Sync job progress,如果进度显示100%,则说明迁移完成。

    说明

    该进度只反映了本次同步检查的进度。由于源集群的数据可能会持续更新,同步工具会在接下来的检查周期中启动新的数据同步任务。因此,在下一周期的进度检查后,显示的进度百分比可能会下降,例如可能从100%减少到90%。

    以下是与进度相关的参数详情。

    参数

    说明

    total

    此次数据迁移中的总作业数。

    ddlPending

    待执行的DDL作业数量。

    ddlRunning

    当前正在执行的DDL作业的数量,该参数值通常为01。

    jobPending

    待执行的数据同步作业数量。

    sent

    已发送但尚未开始的数据同步作业数量。

    running

    正在运行中的数据同步作业数量。

    finished

    已成功执行完毕的数据同步作业数量。

    failed

    执行失败的数据同步作业累积数量。通常,此数值可忽略,因为迁移过程中会周期性地重试失败的作业。

    unknown

    状态未知的作业数量。

  • 同步表进度

    image

    搜索关键字Sync table progress,如果进度显示100%,则说明迁移完成。

    说明

    该进度反映了自同步工具启动运行后,至少有一次同步任务执行成功的表数量占配置的表总数量的占比,当配置的所有表至少同步成功过一次之后,该进度便为100%,且该值不会下降。若同步表进度为100%且同步任务进度为100%时,说明在该检查周期内,源集群和目标集群的数据完全一致;若同步表进度为100%且同步任务进度小于100%时,说明有部分表在同步增量数据。

    以下是与进度相关的参数详情。

    参数

    说明

    finishedTableRatio

    至少有一次成功执行同步任务的数据表所占比例。

    expiredTableRatio

    数据表过期数据所占比例。

    total table

    此次数据迁移配置的数据表总数。

    finished table

    至少有一次同步任务执行成功过的数据表数量。

    unfinished table

    还未进行过数据同步的数据表数量。

    unfinished detail

    还未进行过数据同步的数据表名称列表。

查看迁移事务状态

迁移工具会为每张表开启一个事务,您可以通过查看事务的状态了解该表的迁移进度。

SHOW PROC "/transactions/<db_name>/running";

其中,<db_name>为该表所在数据库的名称。

返回结果中会显示当前正在运行的事务及其状态。如果事务状态为“完成”,则表示该表的迁移任务已完成;如果长时间处于“运行中”,可能需要排查是否存在异常。

查看分区数据版本

您可以通过选择具有代表性的分区,比较源集群与目标集群中对应分区的数据版本,以便了解分区的迁移状态。

SHOW PARTITIONS FROM <table_name>;

其中,<table_name>为该分区所属表的名称。

返回结果中包含每个分区的版本号(Version)。对比源集群和目标集群中相同分区的版本号,若版本号一致,则表示该分区已成功迁移。

查看数据量

通过对比源集群和目标集群的数据量,可以快速了解整体迁移进度。

SHOW DATA;

返回结果中会显示每个数据库和表的数据量(包括磁盘占用大小)。对比源集群和目标集群的数据量,若两者一致,则表示数据迁移已完成。

查看表行数

通过对比源集群和目标集群中表的行数,可以进一步验证各表的迁移状态。

SELECT 
    TABLE_NAME, 
    TABLE_ROWS 
FROM 
    INFORMATION_SCHEMA.TABLES 
WHERE 
    TABLE_TYPE = 'BASE TABLE' 
ORDER BY 
    TABLE_NAME;

返回结果中会列出每个表的名称及其行数。对比源集群和目标集群中相同表的行数,若行数一致,则表示该表已成功迁移。

步骤六:恢复目标集群配置

使用该工具完成数据迁移后,请根据目标集群的类型(存算一体或存算分离),设置以下参数及时恢复默认配置。

  • 迁移到存算一体集群

    SQL Editor中执行以下命令。

    ADMIN SET FRONTEND CONFIG ('emr_serveless_replication_enable' = 'false');
    ADMIN SET FRONTEND CONFIG('enable_legacy_compatibility_for_replication'='false');
    SET GLOBAL enable_filter_unused_columns_in_scan_stage=true;
  • 迁移到存算分离集群

    • SQL Editor中执行以下命令。

      ADMIN SET FRONTEND CONFIG ('emr_serveless_replication_enable' = 'false');
      ADMIN SET FRONTEND CONFIG('enable_legacy_compatibility_for_replication'='false');
      SET GLOBAL enable_filter_unused_columns_in_scan_stage=true;
    • StarRocks实例的参数配置页面,将lake_compaction_max_tasks参数设置不为-1,然后重启集群以恢复Compaction功能。

联系我们

如果您在迁移过程中有任何疑问,请提交工单进行咨询。