配置数据迁移

环境要求

系统环境

操作系统：Windows / Linux / MacOS
数据库状态：源数据库和目标数据库已安装并正常运行
用户权限：用户拥有源数据库和目标数据库的相关操作权限，包括：
- 数据库的创建权限
- 表数据的读取权限
- 表数据的写入权限

安装包

KDTS 提供跨平台支持，针对不同操作系统提供相应的安装包格式：

Windows：KaiwuDB_Data_Transformer-x.x.x-win-x86_64.zip
Linux：KaiwuDB_Data_Transformer-x.x.x-linux-x86_64.tar.gz
MacOS：KaiwuDB_Data_Transformer-x.x.x-mac-x86_64.app.tar.gz / KaiwuDB_Data_Transformer-x.x.x-mac-aarch64.app.tar.gz

图形化界面

图形化界面适用于交互式操作场景，提供完整的可视化配置流程，支持实时预览迁移进度和日志，适合需要逐步确认配置项、首次使用或迁移任务较少的场景。

启动工具

解压缩 KaiwuDB 数据迁移工具安装包，进入安装包目录。

（可选）打开 KaiwuDBDataTransformer.ini 文件，根据需要配置工作区数据目录和 JVM 参数（其余参数暂不支持修改）。

...
-data  ; 指定工具工作区数据目录
data
...
-vmargs  ; 指定 JVM 启动参数
-XX:+IgnoreUnrecognizedVMOptions
--add-modules=ALL-SYSTEM
...
-Xms128m
-Xmx2048m
-Dproject.debug.log.enable=false

启动工具：
- Windows：双击运行 KaiwuDB Data Transformer.exe。
- Linux：双击运行 KaiwuDB Data Transformer 或在命令行执行 ./KaiwuDB\ Data\ Transformer。
- MacOS：双击运行 KaiwuDB Data Transformer 或在终端执行 ./KaiwuDB\ Data\ Transformer。

操作流程概览

使用 KDTS 图形化界面进行数据迁移需按以下流程操作：

创建工程：在数据迁移导航窗口中创建新工程，用于组织和管理迁移任务。
创建迁移任务：在工程目录下创建具体的迁移任务，每个任务对应一次数据迁移操作。
配置与执行迁移任务：
- 选择迁移方式（仅结构、仅数据或结构+数据）
- 配置源端和目的端数据库连接信息
- 设置迁移选项（自动执行、迁移约束、索引、视图等）
- 选择迁移对象（整库或多表）
- 配置映射关系和迁移策略（多表迁移）
- 检查配置无误后执行迁移并监控进度

提示

在正式迁移生产数据前，建议先使用测试数据验证迁移配置的正确性。

工程管理

创建工程

在左侧的数据迁移导航窗口中，右键单击空白区域或已建工程，选择创建 > 工程。
在新建工程窗口中，输入工程名称，根据需要设置工程描述，然后单击确定。系统将自动创建对应的工程目录。

删除工程

在数据迁移导航窗口中，右键单击待删除的工程，选择删除。
在删除对象窗口中，单击是确认删除。

重命名工程

在数据迁移导航窗口中，右键单击待重命名的工程，选择重命名。
在重命名工程窗口中，输入工程的新名称，然后单击确定。

迁移任务管理

创建迁移任务

在数据迁移导航窗口中，展开新建的工程目录，右键单击下方的迁移目录，依次选择创建 > 迁移。
在新建迁移任务窗口，输入迁移任务名称，根据需要填写迁移描述，然后单击确定。系统将自动跳转至新建迁移任务的主页。

复制粘贴迁移任务

在数据迁移导航窗口中，展开工程目录和迁移目录。
右键单击待复制的迁移任务，选择复制。
在数据迁移导航窗口中，右键单击任意位置，选择粘贴，系统将自动创建该任务的副本。

删除迁移任务

在数据迁移导航窗口中，展开工程目录和迁移目录。
右键单击待删除的迁移任务，选择删除。
在删除对象窗口中，单击是确认删除。

重命名迁移任务

在数据迁移导航窗口中，展开工程目录和迁移目录。
右键单击待重命名的迁移任务，选择重命名。
在重命名迁移任务窗口中，输入迁移任务的新名称，然后单击确定。

配置与执行迁移任务

结构化数据

适用于 MySQL、Oracle、PostgreSQL、InfluxDB、TDengine 等数据库到 KaiwuDB 的迁移。以下步骤以 MySQL 到 KaiwuDB 的数据迁移为例，说明如何进行结构化数据迁移：

在数据迁移导航窗口，双击待打开的迁移任务，或右键单击待配置的迁移任务，选择打开。
在迁移任务配置窗口，单击下一步。
在迁移方式页面，设置迁移方式和数据源：
- 迁移方式：支持选择仅结构、仅数据、以及结构+数据三种迁移方式
- 数据源：选择要迁移的源端数据库以及目的引擎类型，默认为时序引擎
  说明
  目前只支持以下结构或结构+数据迁移：
  - MySQL、Oracle 或 PostgreSQL 迁移到 KaiwuDB 关系和时序引擎
  - InfluxDB 或 TDengine 3.x 迁移到 KaiwuDB 时序引擎
在源端信息页，选择连接模式：
- 常规：选择主机或 URL 连接模式，配置相应的连接参数信息。系统会自动校验连接信息，校验成功后方可进行下一步。
  提示
  源端存在 TDengine Decimal 类型数据时，建议使用原生 TCP 连接（jdbc:TAOS://）或 WS 连接（jdbc:TAOS-WS://），REST 连接（jdbc:TAOS-RS://）对复杂类型兼容性较弱。
- 离线：如需在不连接源端数据库的情况下完成配置，可在获取源端元数据配置文件后（详见第 8 步导出配置操作），然后选择离线模式，填写离线元数据文件路径。
在目的信息页，选择主机或 URL 连接模式，配置相应的连接参数信息。系统会自动校验连接信息，校验成功后方可进行下一步。
在迁移选项页，根据需要设置结构迁移和数据迁移的参数信息。
参数说明：
- 自动执行：控制是否自动在目标数据库中执行 DDL 建表语句
  - 选中：自动在 KaiwuDB 数据库中创建表结构
  - 取消选中：需手动执行建表脚本（脚本位于 kdts/data/sql_scripts 目录）
- 迁移约束：控制是否迁移表约束。注意：目前暂不支持迁移默认约束
- 迁移视图：控制是否迁移视图。注意：目前仅支持 MySQL 视图迁移
- 全局通道数量：控制并行度，默认值为 1，建议设置为 CPU 核心数的 1~1.5 倍
- 全局字节流量限制：控制总带宽，默认值 1048576（1 MB/s）
- 全局读取记录数限制：默认值为 1000，设置为 -1 表示无限制
- 单通道字节流量限制：控制单通道带宽，默认值 1048576（1 MB/s）
- 单通道读取记录数限制：默认值为 1000，设置为 -1 表示无限制
提示
全局通道速度 ≈ 单通道字节流量 × 全局通道数量。当源数据库具有高吞吐能力时，建议优先增大通道字节流量而非单纯提高通道数量，减少线程上下文切换开销。
在选择对象页，选择整库迁移或多表迁移：
- 整库迁移
  说明
  整库迁移仅支持 MySQL、Oracle、PostgreSQL 到 KaiwuDB 关系引擎的迁移。
  1. 在源端选择待迁移的数据库。
  2. 在目的端选择目标数据库，然后单击下一步。
- 多表迁移
  1. 在源端选择待迁移的数据库。
  2. 在目的端选择目标数据库。
  3. 勾选待迁移的数据表，然后单击对应的设置。
  4. 在设置映射关系页面，根据需要选择待迁移的列。如果需要迁移到时序引擎，设置目标表的时间戳列（只能选择一个，且必须为 TIMESTAMP 或 TIMESTAMPTZ 类型）、标签列和主标签，然后单击下一步。
  5. 在迁移策略页面，根据需要设置过滤条件、查询 SQL 语句、切分主键、写入模式、写入前后要执行的 SQL 语句，然后单击确认。
    提示
    - 不同数据源支持配置的参数有所不同。每个数据源支持的具体配置参数，参见迁移策略配置参数。
    - 写入模式支持通过下拉框选择 INSERT 或 UPSERT，选择 UPSERT 时需根据提示配置相应的附加参数。
  6. 完成所有表的设置后，在选择对象页，单击下一步。
在检查确认页面，检查参数配置信息。如已选择结构迁移，可单击预览查看即将执行的 DDL 脚本。如需保存当前配置供命令行或离线配置复用，可单击导出配置将配置导出为 JSON 文件。确认配置无误后，单击执行按钮开始执行迁移。
在任务进度页查看迁移进度，等待迁移完成。页面实时展示迁移日志，页面下方以进度条形式显示整体迁移进度，同时显示待迁移的总表数量和当前已完成迁移的表数量。

非结构化数据

适用于 FTP 等 NoSQL 数据库和文件系统到 KaiwuDB 的数据迁移。以下以 FTP 到 KaiwuDB 的数据迁移为例，说明如何进行非结构化数据迁移

在数据迁移导航窗口，双击待打开的迁移任务，或右键单击待配置的迁移任务，选择打开。
在迁移任务配置窗口，单击下一步。
在迁移方式页面，选择数据迁移方式，设置数据源为 FTP，选择迁移到时序引擎或关系引擎，然后单击下一步。
在源端信息页，配置 FTP 服务器的连接参数信息，包括主机地址、端口、用户名、密码等。系统会自动校验连接信息，校验成功后方可进行下一步。
在目的信息页，选择主机或 URL 连接模式，配置 KaiwuDB 数据库的连接参数信息。系统会自动校验连接信息，校验成功后方可进行下一步。
在迁移选项页，根据需要设置数据迁移的参数信息。
在选择对象页，选择整库或多表迁移，其中时序引擎只支持多表迁移。以下以多表迁移为例说明如何进行迁移：
1. 在源端填写待迁移的文件路径或数据库名。
2. 在目的端填写目标数据库名。
3. 单击添加，填写待迁移的表对象，单击设置。
4. 在设置映射关系页面，配置源端文件字段和目的端表字段的映射关系，然后单击下一步。
5. 在迁移策略页面，根据需要设置编码配置、NULL 字符串等信息，然后单击确认。
6. 在选择对象页面，单击下一步。
在检查确认页面，检查参数配置信息。确认配置无误后，单击执行按钮开始执行迁移。
在任务进度页查看迁移进度，等待迁移完成。

命令行（Headless 模式）

命令行（Headless 模式）适用于无图形界面的服务器环境或需要集成到自动化脚本的场景，支持通过参数直接触发迁移任务，无需人工干预。如果需要在 CI/CD 流程中定期执行迁移、或在远程服务器上批量执行任务，推荐使用此模式。

前提条件： 已在图形化界面完成迁移任务配置并导出配置文件。

步骤：

解压缩 KaiwuDB 数据迁移工具安装包，进入安装包目录。

通过以下任一方式指定参数：

命令行直接传参：在终端中运行启动器时，直接附加参数。

./'KaiwuDB Data Transformer' -headless -nosplash -consoleLog \
-dsHost 127.0.0.1 -dsPort 6041 -dsUser root -dsPassword password \
-migrationConfigPath /home/kaiuwdb/config/test_config.json

修改配置文件：打开 KaiwuDBDataTransformer.ini，在 -vmargs 行之前添加启动参数。

;; 以命令行方式启动
-headless
;; 关闭启动屏显
-nosplash
;; 可选，控制日志输出至控制台
-consoleLog
;; 指定数据迁移配置文件路径
-migrationConfigPath
/home/kaiuwdb/config/test_config.json

保存后，在终端中执行：

./'KaiwuDB Data Transformer'

参数说明

参数	是否必填	说明
`-headless`	是	以命令行方式启动
`-nosplash`	是	关闭启动屏显
`-consoleLog`	否	将日志输出至控制台
`-dsType`	导出元数据时必填	数据源类型
`-dsHost`	导出元数据时可选	数据源主机 IP 地址
`-dsPort`	导出元数据时必填	数据源端口
`-dsUser`	导出元数据时必填	获取元数据的数据库用户名
`-url`	导出元数据时可选	数据源 URL 地址
`-migrationConfigPath`	否	数据迁移配置文件路径

性能调优

迁移大数据量时，可通过以下三个层面的参数进行调优，提升迁移效率并避免内存溢出（OOM）问题：

调优方式	适用场景
调整 core.json 全局参数	需要持久化生效的全局默认配置，修改后对所有迁移任务生效
调整迁移选项页面参数	针对单个迁移任务灵活调整，无需修改全局配置文件
JVM 内存管理	迁移超大数据量时出现内存溢出（OOM）问题，需要提升 JVM 堆内存上限

调整 core.json 全局参数

打开 KDTS 根目录下的 /datax/conf/core.json 文件。

根据实际环境修改以下参数：

提示

源数据库具有高吞吐能力时，建议优先增大通道缓冲字节数（byteCapacity）而非单纯提高通道数量，在不增加并发线程数的前提下提升吞吐，减少线程切换带来的额外开销。

{
   "entry": {
      "jvm": "-Xms2G -Xmx4G",
      "environment": {}
   },
   ...
   "core": {
      ...
      "transport": {
         "channel": {
            ...
            "speed": {
               "byte": 2000000,
               "record": -1
            },
            "flowControlInterval": 20,
            "capacity": 512,
            "byteCapacity": 67108864
         }
         ...
      }
   }
}

参数	说明	默认值	生产环境建议值
`entry.jvm`	DataX 运行环境 JVM 参数	`-Xms2G -Xmx4G`	根据生产环境自行调整
`core.transport.channel.speed.byte`	单通道字节流量限制（byte/s）	2 MB/s	网络带宽充足时可调整至 10~50 MB/s
`core.transport.channel.speed.record`	单通道记录数限制（record/s）	-1（无限制）	通常无需限制，保持 -1 即可
`core.transport.channel.flowControlInterval`	流量控制间隔（ms）	20 ms	高并发场景可调整至 50~100 ms，减少 CPU 消耗
`core.transport.channel.capacity`	通道缓冲记录数	512	大数据量突发传输可调整至 1024~4096
`core.transport.channel.byteCapacity`	通道缓冲字节数	64 MB	存在大字段记录时可调整至 128~256 MB

保存文件后，重启 KDTS 使配置生效。

调整迁移选项页面参数

配置迁移任务时，在迁移选项页面，根据当前环境调整以下参数：

参数	说明	默认值
全局通道数量	控制并行度，建议设置为 CPU 核心数的 1~1.5 倍	1
全局通道速度（全局字节流量限制）	限制总带宽，避免网络拥塞	1048576（1 MB/s）
全局读取记录数限制	设置为 -1 表示无限制	1000
单通道速度（单通道字节流量限制）	通道级带宽控制	1048576（1 MB/s）
单通道读取记录数限制	设置为 -1 表示无限制	1000

提示

全局通道速度 ≈ 单通道速度 × 全局通道数量，实际速度受网络、磁盘 I/O 等因素影响。

JVM 内存管理

打开 KDTS 根目录下的 /datax/bin/datax.py 文件。

找到默认 JVM 参数配置项，根据实际环境调整参数值：

DEFAULT_JVM = "-Xms2g -Xmx4g -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=%s/log" % (DATAX_HOME)

参数	说明
`-Xms` / `-Xmx`	初始和最大堆内存，建议设置为物理内存的 50%~70%
`-XX:+HeapDumpOnOutOfMemoryError`	JVM 发生 OOM 时自动生成堆转储文件，用于事后分析原因
`-XX:HeapDumpPath`	指定堆转储文件的输出路径
`-XX:NewRatio`	新生代与老年代内存比例，`NewRatio=3` 表示老年代：新生代 = 3:1（新生代占堆内存的 1/4）
`-XX:+UseG1GC`	启用 G1 垃圾收集器，适合大内存、低延迟场景
`-XX:MaxGCPauseMillis`	G1GC 目标停顿时间（毫秒），JDK 8 需显式配置，启用 G1GC 时生效
`-XX:ParallelGCThreads`	并行 GC 线程数，启用 G1GC 时生效。计算公式：CPU 核心数 ≤ 8 时取核心数，否则取 `8 + (核心数 - 8) × 5/8`
`-XX:ConcGCThreads`	并发 GC 线程数，启用 G1GC 时生效。计算公式：`ParallelGCThreads / 4`（向下取整，最小为 1）

保存文件后，重启 KDTS 使配置生效。

故障排查

配置或结构迁移报错

迁移配置和结构迁移出现异常时，可前往 KDTS 根目录下的 /data/.metadata 文件夹，通过查看 .log 文件获取具体报错详情。

用户数据迁移报错

用户业务数据迁移过程中如果出现报错，可前往 KDTS 以下目录查看迁移日志文件，获取具体报错详情：

Linux 系统：根目录下的 /data/log/ 目录
Windows 系统：根目录下的 /data/report/ 目录

# 配置数据迁移

# 环境要求

# 系统环境

# 安装包

# 图形化界面

# 启动工具

# 操作流程概览

# 工程管理

# 创建工程

# 删除工程

# 重命名工程

# 迁移任务管理

# 创建迁移任务

# 复制粘贴迁移任务

# 删除迁移任务

# 重命名迁移任务

# 配置与执行迁移任务

# 结构化数据

# 非结构化数据

# 命令行（Headless 模式）

# 性能调优

# 调整 core.json 全局参数

# 调整迁移选项页面参数

# JVM 内存管理

# 故障排查

# 配置或结构迁移报错

# 用户数据迁移报错