原文链接：【KWDB 2025 创作者计划】_Oracle11g整库迁移至KaiwuDB - 墨天轮

作者：董小姐

一、迁移需求

应开发要求，将Oracle11g orcl2实例中业务用户portal的数据全部迁移到KaiwuDB中，源库和目标库详细信息如下：

二、迁移概述

DataXopen是一款广泛使用的离线数据同步工具。KaiwuDB 基于 DataX 开发了数据库迁移工具 KaiwuDB DataX Utils，实现 KaiwuDB（2.0.3 及以上版本）与 MySQL、TDengine、MongoDB、InfluxDB、OpenTSDB、Oracle、PostgreSQL、ClickHouse、KaiwuDB（1.2.x）、KaiwuDB（2.x）等数据库的离线数据同步。

用户通过配置文件设置源数据库和目标数据库的连接、数据迁移等信息。KaiwuDB DataX Utils 自动校验、统计迁移数据并输出迁移报告。在迁移过程中，用户可以查看整体的数据迁移进度。

三、支持的迁移形式

KaiwuDB DataX Utils 支持以下数据迁移形式：

• 元数据迁移：无需在目标数据库创建待迁移的表，KaiwuDB DataX Utils 将自动读取源数据库的表结构信息，生成相应的建表语句，并创建符合目标数据库要求的表结构。
• 元数据和业务数据迁移：在迁移过程中，除了自动创建目标数据库中的表结构，KaiwuDB DataX Utils 还会将源数据库中的业务数据迁移到目标数据库中。
• 业务数据迁移：用户在目标数据库创建好表结构后，以单表、多表、单库和多库的形式对表内的业务数据进行迁移，其中：

• 以表的形式迁移数据时，支持全量数据迁移和增量数据迁移。
• 以库的形式迁移目前只支持将 Oracle11g 数据迁移到 KaiwuDB 的关系库。迁移时，源数据库与目标数据库必须一一对应。

下表列出了 KaiwuDB 支持迁移的异构源数据库和数据迁移方式。

说明

默认情况下，KaiwuDB 1.2.x 允许重复写入数据且不进行去重。KaiwuDB 2.x 对带有相同时间戳的数据整行去重，后写入的数据覆盖已存在的带有相同时间戳的数据。当将数据从 KaiwuDB 1.2.x 迁移到 KaiwuDB 2.x 时，如需保留源数据库中带有相同时间戳的数据，用户可以在目标数据库上运行 SET CLUSTER SETTING ts.dedup.rule = keep; 命令，允许写入带有相同时间戳的数据。keep 取值只适用于 KaiwuDB 2.x 单机部署模式。

3.1数据类型映射

KaiwuDB DataX Utils 支持 DataX 的数据类型。DataX 数据类型与 KaiwuDB 数据类型的映射关系如下表所示：

注意：不支持Oracle中CLOB大字段数据类型的迁移，ERROR: at or near "clob": syntax error: type does not exist

四、迁移前准备工作

4.1 安装迁移工具

需是Linux 系统环境

4.2 安装 openJDK

默认已安装，查看openJDK版本，需1.8 及以上版本， 推荐使用 1.8 版本

[root@localhost ~]# java -version
openjdk version "1.8.0_402"
OpenJDK Runtime Environment Bisheng (build 1.8.0_402-b06)
OpenJDK 64-Bit Server VM Bisheng (build 25.402-b06, mixed mode)

参考链接：https://openjdk.org/install/

4.3 安装 Python

默认已安装，查看python版本，需2.x 或 3.x版本

[root@localhost ~]# python -V
Python 2.7.18

Python下载链接：https://www.python.org/downloads/

4.4 安装 Maven

查看Maven版本，需3.6 及以上版本

tar -xvf apache-maven-3.9.9-bin.tar.gz -C /usr/local/

echo "PATH=$PATH:/usr/local/apache-maven-3.9.9/bin"  >> /etc/profile
source /etc/profile

mvn -version 或 mvn -v

参考链接：https://maven.apache.org/install.html

Maven下载链接：https://maven.apache.org/download.cgi

4.5 安装 DataX 3.0

4.5.1 DataX3.0介绍

DataX 是阿里巴巴集团内被广泛使用的离线数据同步工具/平台，实现包括 MySQL、SQL Server、Oracle、PostgreSQL、HDFS、Hive、HBase、OTS、ODPS 等各种异构数据源之间高效的数据同步功能。

DataX本身作为数据同步框架，将不同数据源的同步抽象为从源头数据源读取数据的Reader插件，以及向目标端写入数据的Writer插件，理论上DataX框架可以支持任意数据源类型的数据同步工作。同时DataX插件体系作为一套生态系统, 每接入一套新数据源该新加入的数据源即可实现和现有的数据源互通。

DataX 安装包中已包含几乎所有已适配数据库的数据读写插件。如果在 DataX 安装包中未找到所需的插件，或版本不兼容，建议从源数据库的官方网站获取适配插件。

将 InfluxDB 的元数据迁移到 KaiwuDB 时，需要使用 KaiwuDB 适配后的 InfluxDB reader 插件。

4.5.2 下载并解压

下载地址：https://datax-opensource.oss-cn-hangzhou.aliyuncs.com/202309/datax.tar.gz

下载后解压至本地某个目录，进入bin目录，即可运行同步作业

mkdir -p /opt/datax

tar -xvf datax.tar.gz -C /opt/datax

echo "$PATH=$PATH:/opt/datax/datax/bin" >> /etc/profile
source /etc/profile

参考链接：https://gitee.com/mirrors/DataX/blob/master/userGuid.md

4.5.3 下载KaiwuDB_datax插件

下载地址：https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0

4.6 源库准备工作

4.6.1 收集源库信息

--查看PORTAL用户数据量
ｓｅｌｅｃｔ round(sum(bytes) / 1024 / 1024 / 1024, 2) || 'G'
  from dba_segments
 where owner in ('PORTAL') ;

 ROUND(SUM(BYTES)/1024/1024/1024,2)||'G'
4.96G

4.6.2 生成源库PORTAl用户表结构脚本

用navicate工具连接导出

五、 目标库准备工作

5.1 创建数据库

--root用户连接 KaiwuDB
kwbase sql --insecure --host=192.168.19.115

--创建数据库
create database orcl2;

--创建普通用户
create user portal;
ｇｒａｎｔ admin to portal;

--root用户退出登录
\q

--portal用户登录orcl2数据库
kwbase sql --insecure --host=192.168.19.115 -u portal -d orcl2

5.2 执行表结构脚本

将源库导出的表结构文件在KaiwuDB中执行进行创建对象，因为将Oracle迁移到KaiwuDB过程中不支持在线创建表。

注意类型转换：

注意：不支持Oracle中CLOB大字段数据类型的迁移，ERROR: at or near "clob": syntax error: type does not exist

5.2.1 部分SQL转换整理

5.2.1.1 数据类型转换

5.2.1.2 函数转换

六、Oracle11g 迁移到 KaiwuDB过程

源数据库是 Oracle11g、PostgreSQL、TDengine 或 InfluxDB 且目标数据库是 KaiwuDB，用户可以使用迁移工具迁移表数据，需要提前在KaiwuDB中创建目标表。

6.1 上传并解压KaiwuDB DataX 插件包

解压缩 KaiwuDB DataX 插件包，将解压后的 kaiwudbwriter 复制到 datax/plugin/writer 目录。

unzip KaiwuDB_datax-2.2.0.zip 
cp -r kaiwudbwriter /opt/datax/datax/plugin/writer/

6.2 创建 .yml 格式的迁移配置文件

创建 .yml 格式的迁移配置文件，配置元数据、源数据库和目标数据库。有关配置参数的详细信息，参见配置参数。

[root@localhost datax]# cat Oracle11g2kaiwudb.yml
metadata:
  enable: true               # 启用元数据迁移
  engine-type: RELATIONAL    # 引擎类型为关系引擎
  auto-ddl: true             # 自动创建表
  primary-key: true          # 启用主键迁移
  constraint: true           # 启用约束迁移
  comment: true              # 启用注释迁移
  index: true                # 启用索引迁移
  view: true                 # 启用视图迁移
data:
  enable: true               # 启用业务数据迁移
  batchSize: 1000            # 每批次迁移 1000 条数据
  setting:
    speed:
      channel: 1             # 设置通道数为 1
    errorLimit:
      percentage: 0.02       # 允许错误数据的比例为 2%
  core:
    transport:
      channel:
        speed:
          byte: 1048576      # 每个通道的传输速率为 1 MB
          record: 1000       # 每个通道每批次传输 1000 条记录
source:
  type: ORACLE                # 源数据库类型是 MySQL
  url: jdbc:oracle://192.168.3.112:1521/orcl2?useSSL=false&useUnicode=true&characterEncoding=utf8  # Oracle 连接 URL
  username: portal # Oracle 数据库用户名
  password: oracle # Oracle 数据库密码
  databases:
    - name: orcl2 # 源数据库名
target:
  type: KAIWUDB              # 目标数据库是 KaiwuDB
  url: jdbc:kaiwudb://192.168.40.115:26257/orcl2 # KaiwuDB 连接 URL
  username: root       # KaiwuDB 数据库用户名
  password: 61608Hhd820.       # KaiwuDB 数据库密码
  databases:
    - name: orcl2 # 目标数据库名

6.3 开始迁移业务数据

在 kaiwudb-datax-utils-2.2.0.jar 所在目录，执行以下命令，开始迁移表元数据和业务数据。有关迁移命令支持的所有参数，参见迁移命令参数。

注意：默认会迁移到public模式下。

nohup java -jar -DyamlPath=/opt/datax/Oracle11g2kaiwudb.yml -DdataxPath=/opt/datax/datax -Dpython=python kaiwudb-datax-utils-2.2.0.jar &

查看迁移过程日志：

2025-04-14 09:58:53 INFO  c.k.migration.KaiwuDBApplication - Initialize heterogeneous database migration tool.
2025-04-14 09:58:53 INFO  c.k.migration.utils.YamlParseHelper - config file: /opt/datax/Oracle11g2kaiwudb.yml
2025-04-14 09:58:56 ERROR com.kaiwudb.migration.utils.DBHelper - 读取源端数据库表和列名信息异常: java.sql.SQLSyntaxErrorException: ORA-00933: SQL 命令未正确结束

https://docs.oracle.com/error-help/db/ora-00933/
2025-04-14 10:00:02 INFO  c.kaiwudb.migration.utils.CmdHelper - 执行命令成功: [python, /opt/datax/datax/bin/datax.py, /opt/datax/datax/job/ORACLE2KAIWUDB_2132013066775.json]
2025-04-14 10:01:06 INFO  c.kaiwudb.migration.utils.CmdHelper - 执行命令成功: [python, /opt/datax/datax/bin/datax.py, /opt/datax/datax/job/ORACLE2KAIWUDB_2132039748050.json]
......
......
2025-04-14 22:40:11 INFO  c.kaiwudb.migration.utils.CmdHelper - 执行命令成功: [python, /opt/datax/datax/bin/datax.py, /opt/datax/datax/job/ORACLE2KAIWUDB_3091725577061.json]
2025-04-14 22:40:11 INFO  c.k.m.s.impl.MigrationServiceImpl - 生成DataX迁移脚本，并执行脚本完成数据迁移同步，迁移报告路径为：/opt/datax/datax/log/迁移报告_20252240114917000277.pdf.

由于目前没有这种类似排除某张表或者某些表、数据类型映射的参数，Oracle迁移到KWDB的配置文件参数不完善，所以日志中有提示读取源端数据库表和列名信息异常，应该是不支持数据类型的提示，比如大字段。所以整库同步前需要将大字段的表整理出来，迁移完成后不在目标端对这些表进行校验或将这些表删除即不迁移这些表。新版本可能会更加完善，使用更加便捷。

6.4 注意事项

源数据库是 MySQL、PostgreSQL、TDengine 或 InfluxDB 且目标数据库是 KaiwuDB，用户可以使用迁移工具迁移表结构数据，无需提前创建目标表。

目标数据库的库名必须与源数据库的库名相同。

如果登录 KaiwuDB 数据库的用户为 admin 用户或 admin 角色的成员，则无需提前建库，KaiwuDB 将自动创建与源数据库同名的数据库。

迁移任务目录：-dataxPath启动参数指定目录下的job目录，以.json为后缀

迁移日志路径：-dataxPath启动参数指定目录下的log目录，以日期生成独立目录

迁移报告路径：-dataxPath启动参数指定，该迁移案例中迁移报告文件路径/opt/datax/datax/log/迁移报告_20250409144917000877.pdf

如果要避免内存溢出或增加datax内存提高迁移速度，可更改conf中的core.json中的jvm参数

{
    "entry": {
        "jvm": "-Xms1G -Xmx1G",
        "environment": {}
    },

6.5 扩展

6.5.1 配置文件参数

6.5.1.1 元数据 (metadata)

6.5.1.2 业务数据 (data)

6.5.1.3 源数据库（source）

6.5.1.4 目标数据库（target）

下表列出目标数据库的相关配置参数。

6.6 迁移命令参数

从 KaiwuDB 2.2.0 版本开始，迁移命令不再支持 arguments 参数设置。如果需要设置 JVM 参数以增加内存，可以通过修改 DataX 配置文件来实现。

示例

java -jar -DyamlPath=../datax/test/config.yml -DdataxPath=../datax -Dpython=python kaiwudb-datax-utils-2.2.0.jar

参考链接：https://www.kaiwudb.com/kaiwudb_docs/#/db-migration/migration-senarios/migrate-Oracle11g-to-kaiwudb.html#%E5%8D%95%E5%BA%93%E8%BF%81%E7%A7%BB%E5%85%83%E6%95%B0%E6%8D%AE