cloudberry-contrib / cloudberry-contrib/cbcopy

[FEATURE] 【支持异构表结构的迁移】

Open
#28 1 comment 1 reaction 1 assignee View on GitHub

@robertmu is already working on this.

Since Apr 1, 2026.

Dominant language
Go
Stars
25
Forks
13
PR merge metrics
No merged PRs in 30d

Description

Describe the feature

当前 cbcopy 工具仅支持源端与目标端表结构完全一致的迁移场景,当源表与目标表存在结构差异(异构)时,迁移任务会直接失败。

本功能请求为 cbcopy 新增异构表结构数据迁移能力,支持在源、目标表结构不完全匹配的情况下,完成数据的精准迁移,核心能力包括:
1、自动匹配源、目标表的同名字段,仅迁移匹配字段的数据
2、支持字段映射配置(源字段 → 目标字段的自定义映射关系)
3、支持源表多余字段的自动忽略
4、提供结构差异校验报告,提前告知不匹配项与风险

Motivation

1、业务场景刚需:在 CloudberryDB集群迁移、分库分表合并、数据同步等场景中,源、目标表结构不一致的情况不少,多数场景存在字段增减、类型调整、字段重命名等异构情况,当前 cbcopy 无法满足这类核心业务需求,严重限制工具的实用性。
2、提升迁移效率:无需手动编写 INSERT ... SELECT 脚本、无需临时调整表结构,直接通过工具完成异构迁移,大幅降低运维成本,减少人工操作失误。
3、降低业务风险:通过自动校验、类型安全转换、差异报告,避免手动迁移导致的数据丢失、类型不兼容、字段错位等问题,保障数据一致性。

Describe the solution

1、新增异构迁移模式

  • 新增命令行参数 --heterogeneous,开启异构迁移模式
  • 新增参数 --map-file <mapping.yaml>,支持通过 YAML 文件配置字段映射规则
  • 新增参数 --on-mismatch [skip|error|warn],配置结构不匹配时的处理策略(默认 warn)

2、字段匹配逻辑

  • 默认按字段名自动匹配源、目标表字段
  • 支持通过 --map-file 自定义映射,示例:
    mappings:
    • source_column: user_id
      target_column: id
    • source_column: create_time
      target_column: dt_create
      type_convert: timestamp → timestamptz

3、结构校验与报告

  • 迁移前自动执行源、目标表结构全量校验
  • 生成结构化校验报告,包含:

匹配成功字段列表
源表多余字段(将被忽略)
目标表缺失字段(将填充默认值 / NULL)
类型不匹配字段(转换风险提示)

  • 校验不通过时,根据 --on-mismatch 策略终止 / 警告 / 跳过
Additional context
  • 使用场景示例:
    源表:create table t1(id int,id2 int,id3 text,id4 varchar(20));
    目标表:create table t2(id int,id3 int,id4 text,id6 varchar(20));
    通过异构迁移自动完成字段映射、类型转换、默认值填充。

  • 分表合并:多个分表结构略有差异,合并到总表时自动忽略分表特有字段,填充总表新增字段。

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.