【DataKit系列】数据迁移-使用说明（一）

DataKit简介

DataKit是开源的openGuass数据库管理工具，支持用户对openGuass进行安装，运维，卸载等其他功能。

DataKit的开源Gitee地址为https://gitee.com/opengauss/openGauss-workbench，其中对DataKit的介绍如下：

openGauss DataKit是基于Web的openGauss的可视化的平台系统，目的是方便客户使用和管理openGauss可视化工具，可以为客户降低openGauss数据库安装使用门槛，做到安全中心管理，插件管理，以及其它功能包括一键化部署、卸载、组件化安装、多版本升级、日常运维和监控。

本文的概述

本文主要对DataKit工具的数据迁移功能的使用进行详细讲解，DataKit数据迁移可以完成迁移MySQL数据到openGauss数据库中的功能。

本文是博主整理的DataKit数据迁移功能使用的详细教程，主要包含的内容有：环境准备，迁移前配置，执行迁移任务，DataKit安装portal教程，DataKit数据迁移常见问题。

阅读本文需要结合博主的另外两篇文章，分别是“DataKit数据迁移-2实例搭建步骤”，“DataKit数据迁移-3前置校验失败的处理”。三篇文章从不同方面，对DataKit数据迁移功能进行了全方位的使用教程。使用DataKit数据迁移功能，只需按照文章目录顺序阅读阅读即可。若有错误，不详，疑问或建议等，欢迎留言交流。

1 环境准备

• DataKit服务

  要求：成功加载data-migration插件

  DataKit安装教程，请参考码云仓库（https://gitee.com/opengauss/openGauss-workbench）

• openGauss企业版服务

  要求：可以被DataKit服务所在服务器访问

  openGauss企业版安装请参考官方社区（https://opengauss.org/zh/）教程，也可使用DataKit base-ops插件的“集群安装-安装部署”功能进行安装。

• MySQL服务

  要求：可以被DataKit服务所在服务器访问

• CentOS或openEuler系统服务器

  要求：可以被DataKit服务所在服务器访问；JDK 11+环境

  用途：用于安装迁移插件（portal）

2 迁移前配置

2.1 openGauss配置

2.1.1 参数配置

修改配置文件pg_hba.conf和postgresql.conf相关参数，以支持迁移过程。

配置白名单，以支持通过openGauss用户进行远程连接，配置命令如下：

-- 修改pg_hba.conf文件
gs_guc set -D -h "host all all 0.0.0.0/0 sha256"
-- 修改postgresql.conf文件
gs_guc set -D -c "listen_addresses = '*'"
-- 其中，“”为数据库节点路径，请替换为实际值，如“/opt/huawei/install/data/dn”，此文档中后续此参数含义不变。

配置日志参数及复制权限，以支持反向迁移，配置命令如下：

-- 修改pg_hba.conf文件
gs_guc set -D -h "host replication all 0.0.0.0/0 sha256"
-- 修改postgresql.conf文件
gs_guc set -D  -c "wal_level = logical"

配置完成后，重启数据库，重启命令如下：

gs_ctl restart -D 

2.1.2 创建管理员用户

连接数据库

gsql -d postgres -p

-r
-- 其中，“

”请替换为实际端口，如“5432”，此文档中后续此参数含义不变。

创建用户并赋予管理员权限

create user opengauss_test with password 'Sample@123';
grant all privileges to opengauss_test;
-- 其中，“opengauss_test”为用户名，可自定义，后续此文档中涉及到连接openGauss的用户，便使用此用户。
--       “Sample@123”为用户密码，可自定义。

3 执行迁移任务

请参考文档：“【DataKit系列】数据迁移-实例搭建步骤（二）（下期发布，敬请期待）”

4 DataKit安装Portal教程

4.1 DataKit安装Portal注意事项

• root用户下，依次安装如下依赖

yum install -y mysql-devel
yum install -y mysql5-devel
yum install -y mariadb-devel
yum install -y python3-devel
yum install -y python-devel

• 注：如果mysql5-devel与mariadb-devel冲突，保留一个即可。其他包如果未找到，则可忽略。

• 请确保安装用户的~/.bashrc已经配置java环境变量，并且版本满足11+。

• 安装6.0.0-RC1的portal包，并确认在线安装的安装包是否匹配对应主机架构。

  可能存在DataKit未成功获取目标执行机系统及架构信息的情况，导致在线安装给出的包是默认的centos-x86的安装包。遇到此情况，请自行前往portal仓库，下载匹配目标执行机系统及架构的安装包，然后使用datakit的portal离线安装，上传下载的安装包进行安装。

# portal码云仓库地址
https://gitee.com/opengauss/openGauss-migration-portal

• 安装目录尽量不要再用户的home目录下，即~目录下，并确保安装用户对安装目录有操作权限。因此建议使用安装用户创建目录，供安装portal使用。

• 请确保第三方工具的三个端口未被占用，如果默认端口已被占用，支持自定义端口。

4.2 DataKit安装Portal步骤

1. 访问Datakit服务，点击进入“数据迁移->迁移任务中心”目录下

2. 点击“创建数据迁移任务”按钮

3. 开始“选择迁移源库和目的库”步骤，分别选择源端数据库（database），选择目的端数据库（database），并点击“添加子任务”按钮。如果无数据源，点击“新增数据源”，输入所需参数进行新增。
   添加子任务成功后，在页面下方选择对应子任务的“迁移过程模式”，支持在线模式和离线模式。离线模式：自动执行全量迁移，完成后自动结束，释放资源。在线模式：自动执行全量迁移+增量迁移，用户手动启动反向迁移，需要用户操作结束迁移，释放资源。
   “选择迁移源库和目的库”配置成功，点击下一步。

4. 进入“配置迁移过程参数”步骤，可直接使用默认参数，直接点击“下一步”。

5. 进入“分配执行机资源”步骤，页面会展示所有的执行机列表信息，选择对应执行机点击“开始安装”，进入“迁移套件安装”步骤。
   此处如果无执行机信息显示，请前往“资源中心->服务器管理”添加服务器资源，注意添加服务器时需要勾选“记住密码”，添加服务器成功后，页面会显示添加成功的服务器记录。
   点击所需服务器记录右侧的“用户管理”，添加普通用户。至此，此服务器可作为安装portal的执行机。

6. 进行portal安装,
   “安装用户”选择上述添加的服务器的普通用户。“安装目录”选择使用“安装用户”创建的已有目录，不建议使用默认的“安装用户”的home目录。“第三方工具配置方式”选择“本机新安装”，选择后会出现“zookeeper 端口”，“kafka 端口”，“schema_registry 端口”三条配置项，请确保配置的三个端口未被占用，如默认端口被占用，支持自定义端口。“第三方工具安装目录”使用默认的即可，支持自定义，但同样请配置到使用“安装用户”创建的目录下。
   选择安装方式，“在线安装”是在线下载安装包，完成安装，需要确保对应的服务器网络正常。“离线安装”支持手动上传portal安装包进行安装，注意自行下载时请下载匹配对应服务器系统及架构的安装包。“导入安装”支持导入对应服务器上已安装的portal，但要求已安装的portal成功安装了所有的mysql迁移插件，否则导入安装无法成功。

7. “安装包名称”建议选用最新版本的安装包。至此“迁移套件安装”步骤配置成功，点击“确认”按钮，开始portal安装。

8. 进行portal安装时，“分配执行机资源”页面的对应执行机的“是否安装迁移套件”字段会显示为“安装中”，安装成功则显示为“已安装”。如果安装失败，可下载“安装日志”，排除故障后，点击“清理环境”，然后再次安装即可。

4.3 DataKit安装Portal可能出现的问题

无论遇到任何问题，请先按照“DataKit安装Portal注意事项”进行排查后，再次尝试安装。

4.3.1 kafka启动失败的问题

问题描述：

安装portal，所有迁移工具安装成功，但是启动kafka失败，报错类似如下：

Socket server failed to bind to 10.126.28.177:9089: Cannot assign requested address

问题原因：

网络问题，使用外网ip连接服务器时，本机无法感知，导致kafka无法成功启动，修改ip为本机ip，如192.168.0.123后，停止残留的zookeeper kafka等进程，重新启动kafka，启动kafka成功。

解决方式：

修改了配置文件的listeners属性中的ip地址为本机ip地址，配置文件位置：/portalpath/portal/tools/debezium/confluent-5.5.1/etc/kafka/server.properties。修改成功后，执行如下命令重启kafka：

-- 可以先执行停止kafka的命令，确保Kafka进程已停止，避免启动时出错，停止kafka的命令如下
java -Dpath=/data/dgq/portal/portal/ -Dorder=stop_kafka -Dskip=true -jar data/dgq/portal/portal/portalControl-6.0.0rc1-exec.jar
-- 启动kafka进程的命令
java -Dpath=/data/dgq/portal/portal/ -Dorder=start_kafka -Dskip=true -jar /data/dgq/portal/portal/portalControl-6.0.0rc1-exec.jar

5 DataKit数据迁移常见问题

5.1 在线模式，任务长时间卡顿在全量迁移过程中的问题

问题描述：

成功创建在线迁移任务后，点击启动，无前置校验失败，任务状态长时间卡顿在全量迁移进行中，页面无报错，后台full_migration.log无报错。

查看portal中对应任务workspace.id的log日志，日志目录为/portal_install_path/portal/logs/portal_3.log，其中的portal_install_path请替换为实际的portal安装路径，3请替换为实际的子任务worksapce.id（可以在子任务详情页面的左上角查看）。日志中包含报错信息“begin 0, end -1, length 0”，详细信息类似如下：

16:56:15,851 ERROR (ThreadExceptionHandler:uncaughtException) - thread main occur excetion:
java.lang.reflect.InvocationTargetException
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.base/java.lang.reflect.Method.invoke(Method.java:566)
at org.springframework.boot.loader.MainMethodRunner.run(MainMethodRunner.java:49)
at org.springframework.boot.loader.Launcher.launch(Launcher.java:108)
at org.springframework.boot.loader.Launcher.launch(Launcher.java:58)
at org.springframework.boot.loader.JarLauncher.main(JarLauncher.java:88)
Caused by: java.lang.StringIndexOutOfBoundsException: begin 0, end -1, length 0
at java.base/java.lang.String.checkBoundsBeginEnd(String.java:3319)
at java.base/java.lang.String.substring(String.java:1874)
at org.opengauss.portalcontroller.tools.mysql.IncrementalMigrationTool.changeGtidSet(IncrementalMigrationTool.java:165)
at org.opengauss.portalcontroller.tools.mysql.IncrementalMigrationTool.findOffset(IncrementalMigrationTool.java:139)
at org.opengauss.portalcontroller.tools.mysql.IncrementalMigrationTool.init(IncrementalMigrationTool.java:302)
at org.opengauss.portalcontroller.task.Plan.execPlan(Plan.java:448)
at org.opengauss.portalcontroller.PortalControl.startPlan(PortalControl.java:384)
at org.opengauss.portalcontroller.command.mysql.StartCommandReceiver.action(StartCommandReceiver.java:41)
at org.opengauss.portalcontroller.command.ConcreteCommand.execute(ConcreteCommand.java:24)
at org.opengauss.portalcontroller.PortalControl.main(PortalControl.java:181)
... 8 more
16:56:16,599 INFO (ChangeStatusTools:reduceDiskSpace) - isReduced:false,Plan.stopPlan:false,PortalControl.status:2
16:56:18,654 INFO  (ChangeStatusTools:reduceDiskSpace) - isReduced:false,Plan.stopPlan:false,PortalControl.status:2

问题原因：

直接原因：查询openGauss的t_gtid_set为空所致

-- 首先连接目标端数据库
-- 查询openGauss的t_gtid_set的sql如下
select t_binlog_name,i_binlog_position,t_gtid_set from sch_chameleon.t_replica_batch;

根本原因：查询MySQL的Executed_Gtid_Set为空所致

-- 查询MySQL的Executed_Gtid_Set的sql，其中字段Executed_Gtid_Set对应的值就是Executed_Gtid_Set
SHOW MASTER STATUS;

问题解决：

设置MySQL 端的gtid_mode参数值为on，设置的sql如下：

-- 逐行执行如下sql语句，完成设置
SET GLOBAL ENFORCE_GTID_CONSISTENCY = ON;
SET GLOBAL gtid_mode=OFF;
SET GLOBAL gtid_mode=OFF_PERMISSIVE;
SET GLOBAL gtid_mode=ON_PERMISSIVE;
SET GLOBAL gtid_mode=ON;

设置完成后，通过如下sql查询是否设置成功：

-- 查询gitid_mode状态的sql语句
SHOW GLOBAL VARIABLES LIKE 'gtid_mode';

设置成功后，任意执行一条插入语句，再次查询Executed_Gtid_Set，使得字段Executed_Gtid_Set对应的值变为类似如下格式bb95ff80-f621-11ee-a803-fa163e5bb329:1-3
，冒号后为1-n
的格式，迁移过程中会强校验此值的格式，格式变成上述格式则问题解决。

结束历史迁移任务，重新创建迁移任务并启动，问题解决。

5.2 全量迁移未开始，便提示迁移失败的问题

问题描述：

启动迁移任务，迁移状态至“全量迁移开始”，然后便提示迁移失败的情况。查看全量迁移日志，日志进行到创建schema步骤，且报错信息为“syntax error at or near “-””，详细日志类似如下。

2024-05-20 16:57:25.322 MainProcess DEBUG mysql_lib.py (826): Creating the loading schema demo-portal_tmp.
Traceback (most recent call last):
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/bin/chameleon.py", line 76, in
getattr(replica, args.command)()
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/global_lib.py", line 575, in init_replica
self.__init_mysql_replica()
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/global_lib.py", line 585, in __init_mysql_replica
self.mysql_source.init_replica()
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/mysql_lib.py", line 3013, in init_replica
self.create_destination_schemas()
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/mysql_lib.py", line 827, in create_destination_schemas
self.pg_engine.create_database_schema(loading_schema)
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/pg_lib.py", line 5291, in create_database_schema
self.pgsql_conn.execute(sql_create)
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/py_opengauss/driver/pq3.py", line 2318, in execute
self._pq_complete()
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/py_opengauss/driver/pq3.py", line 2623, in _pq_complete
self.typio.raise_error(x.error_message, cause = getattr(x, 'exception', None))
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/py_opengauss/driver/pq3.py", line 544, in raise_error
self.raise_server_error(error_message, **kw)
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/py_opengauss/driver/pq3.py", line 535, in raise_server_error
raise server_error
py_opengauss.exceptions.SyntaxError: syntax error at or near "-"
CODE: 42601
LOCATION: SERVER
POSITION: 20
CONNECTION: [idle]
client_address: 192.168.0.66/22
client_port: 6666
version:
(openGauss 5.0.2 build 48a25b11) compiled at 2024-05-14 10:26:01 commit 0 last mr on x86_64-unknown-linux-gnu, compiled by g++ (GCC) 7.3.0, 64-bit
CONNECTOR: [IP4] pq://gaussdb:***@192.168.0.66:5432/test1?[sslmode]=disable
category: None
DRIVER: py_opengauss.driver.pq3.Driver


Process Process-2:
Traceback (most recent call last):
File "/usr/lib64/python3.9/multiprocessing/process.py", line 315, in _bootstrap
self.run()
File "/usr/lib64/python3.9/multiprocessing/process.py", line 108, in run
self._target(*self._args, **self._kwargs)
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/global_lib.py", line 380, in dump_Json
self.write_Json()
File "/ops/portal/tools/chameleon/chameleon-6.0.0rc1/venv/lib64/python3.9/site-packages/pg_chameleon/lib/global_lib.py", line 356, in write_Json
dump_object = self.mysql_source.getmanagerJson().copy()
File "", line 2, in copy
File "/usr/lib64/python3.9/multiprocessing/managers.py", line 809, in _callmethod
conn.send((self._id, methodname, args, kwds))
File "/usr/lib64/python3.9/multiprocessing/connection.py", line 210, in send
self._send_bytes(_ForkingPickler.dumps(obj))
File "/usr/lib64/python3.9/multiprocessing/connection.py", line 415, in _send_bytes
self._send(header + buf)
File "/usr/lib64/python3.9/multiprocessing/connection.py", line 372, in _send
n = write(self._handle, buf)
BrokenPipeError: [Errno 32] Broken pipe
2024-05-20 16:57:38.525 MainProcess DEBUG pg_lib.py (704): There is already a database connection active.
2024-05-20 16:57:38.529 MainProcess INFO global_lib.py (517): Dropping the replica schema
2024-05-20 16:57:38.529 MainProcess DEBUG pg_lib.py (2831): Trying to connect to the destination database.
2024-05-20 16:57:38.684 MainProcess INFO chameleon.py (91): drop_replica_schema finished.

问题原因：

问题是由于源端MySQL数据库名中包含“-”连字符导致，迁移过程中，迁移插件会根据源端MySQL数据库名，在目标端openGauss数据库中，创建于MySQL数据库名同名的schema，但是openGauss的schema命名不支持使用“-”连字符，因此会报错。

问题解决：

修改源端数据的命名，重新创建迁移任务并启动。或选择远端数据库命名无“-”连字符的数据库。

5.3 全量校验失败的问题

问题描述：

成功创建迁移任务，并成功执行全量迁移，迁移校验失败，报错提示类似如下：

failed (insert=0 update=6 delete=0)If you want to repair data.please read the following files:/data/dgq/portal/portal/workspace/25/check_result/result/repair_source_db_table1_0_0.txt

repair_source_db_table1_0_0.txt
中内容如下:

update `source_db`.`table1` set name='data' , col='data1' where id=1 ;
update `source_db`.`table1` set name='data' , col='data2' where id=2 ;
update `source_db`.`table1` set name='data' , col='data3' where id=3 ;
update `source_db`.`table1` set name='data' , col='data4' where id=4 ;
update `source_db`.`table1` set name='data' , col='data5' where id=5 ;
update `source_db`.`table1` set name='data' , col='data6'  where id=6 ;

然而手动校验迁移后table1表中的数据，数据正确。

问题原因：

MySQL创建表table1时，字段NAME
的字段名使用的是大写，建表语句如下：

CREATE TABLE table1 (
id INT,
NAME VARCHAR(10),
col VARCHAR(20),
PRIMARY KEY(id)
);

由于，迁移到openGauss端后，迁移过程创建的table1表格的建表语句如下：

CREATE TABLE table1 (
id integer NOT NULL,
"NAME" character varying(10),
col character varying(20)
)
WITH (orientation=row, compression=no);
ALTER TABLE table1 ADD CONSTRAINT pk_table1_1712058063_0 PRIMARY KEY USING btree  (id);

可见大写的NAME
被双引号括起来，因此导致全量校验的时候，由于双引号的问题，导致检验时无法匹配两边的name
字段名，导致校验无法通过。

问题解决：

MySQL端创建表格时，字段名使用小写，问题解决。

5.4 全量检验未校验，便进行下一步骤增量迁移的问题

问题原因： 内存不够

问题解决： 释放服务器内存后，再次尝试

5.5 增量迁移删除拥有主键的表失败的问题

问题原因：

对于drop table操作，当表含有关联对象是，例如视图，MySQL端可以用drop table只删除表而保留视图，openGauss端用drop table仅删除表会失败，此问题属于内核兼容性问题。因此对于MySQL端的drop table语句，openGauss端将采用drop table cascade一并删除表及其关联的对象。

因此增量迁移源端删除有关联对象的表，目标端无法删除，导致此问题的出现。

问题解决：

删除表格关联对象后，再删除此表。

5.6 增量迁移创建view失败的问题

问题原因：

由于增量迁移解析出的创建view的语句语法类似如下：

CREATE ALGORITHM=UNDEFINED DEFINER=`test`@`%` SQL SECURITY DEFINER VIEW `view1` AS SELECT * FROM table1;

由于语句中包含@
符号，而openGauss端执行此创建view的语句，会在@
符号处报出语法错误。因此导致失败。

问题解决：

通过如下命令设置openGauss的b_compatibility_user_host_auth
参数值为on
使其支持此语法，问题便得到解决。

set b_compatibility_user_host_auth to on;

b_compatibility_user_host_auth参数说明：

参数说明：控制是否允许创建user@host、‘user’@'host’之类的用户并兼容mysql的user@host认证鉴权，对兼容mysql的user@host进行认证时，需要在配置文件postgresql.conf中设为on。

取值范围：布尔型

默认值：off

示例：

openGauss=# show b_compatibility_user_host_auth;
b_compatibility_user_host_auth
--------------------------------
off
(1 row)

5.7 反向迁移成功启动，数据反向迁移未成功的问题

问题描述：

创建迁移任务，无前置校验问题，成功进行全量迁移，增量迁移，数据同步后，停止增量迁移，反向迁移成功启动，在openGauss端添加数据记录，反向迁移条数仍为0，且MySQL端未成功同步数据。

问题原因：

openGuass数据库未开启用户复制权限的支持，即使用户的权限管理中具有复制的权限，但是数据库也需要通过修改配置文件pg_hba.conf，在文件末尾配置host replication {用户名} 0.0.0.0/0 sha256
，如此用户才能进行复制相关操作。其中，用户名也可以换成all，以支持所有用户的复制权限。

个人理解： 用户虽然具有复制权限，但是数据库服务不支持用户使用复制权限进行复制相关操作，因此需要开启数据库对复制权限的管理。

就比如我有从仓库拿东西的权限，所以我可以往外拿东西，但是后来仓库管理员说所有东西都不可以往外拿东西，那么即使我有往外拿东西的权限，他也不让我往外拿东西。配置的目的便是，领导告诉仓库管理员，现在可以让我往外拿东西，那么我再往外拿东西的时候，便能拿出来了。相当于用户有用户的权限管理，然后仓库管理员有仓库管理员的权限管理，两层权限都有，我才能往外拿东西。

问题解决：

修改配置文件pg_hba.conf，在文件末尾配置host replication {用户名} 0.0.0.0/0 sha256
。或通过如下命令配置，命令如下：

gs_guc set -D /opt/datakit/opengauss/datanode/dn1 -h "host replication {用户名} 0.0.0.0/0 sha256"

配置完成后重启数据库，使配置生效，重启数据库的命令如下：

gs_ctl restart -D /opt/datakit/opengauss/datanode/dn1

点击查看原文跳转作者文章