MySQL语法兼容性评估工具

本工具支持利用已有的openGauss节点评估数据SQL文本在openGauss的兼容性。包含但不限于以下限制:

  • 仅支持SQL文本文件输入,且SQL之间以;分割。

  • 不使用dolphinwhale等兼容性插件场景,不兼容语句的报错信息可能不准确。如果使用对应插件,需遵循插件使用约束。

  • 暂不支持#注释,请将文本内的#注释替换为--注释或直接删除。

  • 存储过程、函数语句仅支持:创建体的合法性校验和函数体的语法兼容校验。

  • 对于评估结果的准确率:

    • 完全兼容:openGauss完全支持该语法。兼容结果可能依赖于传入SQL语句的前置执行结果,因此实际在openGauss内执行时不一定完全兼容。

    • 语法兼容:openGauss支持该语法,但是实际使用过程中可能包含字段类型不支持、函数不存在等问题。

    • 语句不兼容:openGauss不支持该语法。

    • 不支持评估:未考虑的语句。后续会陆续支持语句评估(例如create database等跨数据库影响语句)。

    • 忽略语句:注释等。

代码获取

  • openGauss源码路径:

https://gitee.com/opengauss/openGauss-server

  • openGauss插件仓路径:

https://gitee.com/opengauss/Plugin

编译插件

  • 必备插件
必备插件备注
contrib/assessment评估插件,包含插件so和可执行文件
  • 数据库运行时使用以下插件可以提高整体兼容率。
可选插件(对应数据库兼容性插件)备注
contrib/dolphinB兼容数据库插件
  1. 下载openGauss源码,按照READMD.md指导编译openGauss源码。

  2. 将上述插件拷贝到openGauss源码路径的contrib路径下。cd进入对应目录后make install -sj

  3. 将插件必须的文件拷贝到对应二进制路径下面。一般来说包含:extesion.soExtension.sqlExtension.controlassessment插件包含可执行文件assessment_database。本例中涉及文件如下:如果使用的二进制为步骤1中的二进制,此步骤可以省略。

assessment依赖文件

  1. 二进制路径
  2. ├── bin
  3. └── ***assessment_database***
  4. ├── lib
  5. └── postgresql
  6. └── ***assessment.so***
  7. └── share
  8. └── postgresql
  9. └── Extension
  10. ├── ***assessment--1.0.sql***
  11. └── ***assessment.control***

dolphin依赖文件

  1. 二进制路径
  2. ├── lib
  3. └── postgresql
  4. └── ***dolphin.so***
  5. └── share
  6. └── postgresql
  7. └── Extension
  8. ├── ***dolphin--1.0.sql***
  9. └── ***dolphin.control***

运行

  1. 确保有一个正在运行的数据库,且当前支持通过gsql命令连接数据库。

  2. 运行命令如下:assessment_database [args],其中args包含以下参数:

参数描述使用
连接参数p端口(必选)-p 5432
d数据库(可选)-d evaluation
U用户名(可选),如果支持本地连接,可不填-U user
W密码(可选),如果支持本地连接,可不填-W **
兼容性评估c指定兼容类型(A\B\C\PG),如果指定d参数,该参数不可设置。MySQL场景下请指定B。-c B
文件参数f评估SQL文件(必填)-f intput.sql
o输出文件(必填),一般输入html结尾文件-o result.html

举例

case 1:

通过gs_initdb初始化数据库并启动,假设启动端口为5432。此时可以通过gsql -dpostgres -p5432方式直接连接数据库。假设输入文件为test.sql,输出报告路径为result.html,评估的源数据库类型为B,则评估使用的命令为:

  1. assessment_database -p5432 -cB -ftest.sql -oresult.html

此时回显信息为:

  1. assessment_database: create database "assessment_197561" automatically.
  2. assessment_database: Create plugin[dolphin] automatically.
  3. assessment_database: Create Extension[assessment] automatically.
  4. assessment_database: 解析[100.00%]:35/35
  5. assessment_database: Create database assessment_197561 automatically, clear it manually!

case 2:

假设远程已经有数据库节点,在兼容性评估节点可以通过``gsql -dpostgres -p5432 -h127.0.0.2 -Utest -W***** 连接数据库。假设输入文件为test.sql,输出报告路径为result.html`,评估的源数据库类型为B,则评估使用的命令为:

  1. assessment_database -p5432 -cB -h127.0.0.2 -Utest -W***** -ftest.sql -oresult.html

case 3:

假设远程已经有数据库节点,且自己创建了evaluation数据库用于兼容性评估。在兼容性评估节点可以通过``gsql -devalution -p5432 -h127.0.0.2 -Utest -W***** 连接数据库。期望通过假设输入文件为test.sql,输出报告路径为result.html`,则评估使用的命令为:

  1. assessment_database -p5432 -devaluation -h127.0.0.2 -Utest -W***** -ftest.sql -oresult.html

即将case 2中的-cB换成-devaluation指定数据库即可。

结果

评估工具最终会生成评估报告,以html形式展示。包含如下内容:语句、兼容类型、失败原因。兼容类型包括:语法兼容、完全兼容、语法不兼容、不支持评估。相关说明如下:

  • 完全兼容:openGauss完全支持该语法。执行结果依赖于数据库已有的表、函数、存储过程等。

  • 语法兼容:openGauss支持该语法,但是实际使用过程中可能包含字段类型不支持、函数不存在等问题。

  • 语句不兼容:openGauss不支持该语法。

  • 不支持评估:未考虑的语句。后续会陆续支持语句评估(例如create database等跨数据库影响语句)。

原理

  1. 首先存在一个正常运行的数据库节点,可以直接通过gs_initdb初始化。

  2. 配置好对应连接参数,连接参数与openGaussgsql连接方式是一致的。

  3. 如果指定-c 兼容类型方式,工具会通过上述配置的连接参数连接到数据库,手动创建对应兼容类型评估数据库,再通过create Extension创建必要的插件。(如assessmentdolphin)。

  4. 如果指定-d database方式,工具会在对应数据库创建插件。

  5. 在对应评估数据库评估。评估类型包含:语法树兼容评估、实际语句是否兼容评估。