本章节为使用者介绍统一SQL配置相关内容。

4.1. 配置文件

统一SQL提供配置文件夹 config(24.1.8版本之前为unisqlconf) ，相关的配置文件必须放在该文件夹下，供统一SQL动态库第一次加载调用时初始化。 config文件夹内配置文件包括：

  • 系统配置文件：unisql.conf

  • 兜底策略配置文件：oracle2gaussdb_oracle.json、mysql2goldendb_mysql.json

4.2. 目录层级

.
└── workspace
    ├── xxx
    ├── start.sh
    ├── xxx
    └── config -- 统一SQL配置目录
        ├── unisql.conf -- 系统参数配置文件
        ├── oracle2gaussdb_oracle.json -- 兜底配置文件
        └── mysql2goldendb_mysql.json -- 兜底配置文件

4.3. 配置方式

统一SQL寻找配置文件方法有两种，建议使用第二种方式，手动将config目录放在当前工作目录下。

  1. 通过环境变量： unisql_conf_dir 指定统一SQL配置所在目录

    • 例如:export unisql_conf_dir=/xxx/xxx/cres/fbase/workspace/config

  2. 如果没有配置环境变量则会去业务启动脚本所在目录（业务当前工作目录）的 config 目录下寻找

注意

  • 优先级：环境变量>工作目录>默认配置。

  • 建议使用第二种方式，将 config 目录放在当前工作目录下。如果一个服务器上部署了多个不同业务应用，环境变量可能会被覆盖，因此不推荐使用环境变量。

4.4. unisql.conf文件说明

统一SQL支持unisql.conf配置文件设置系统参数，配置以key=value形式，每一行一个配置参数。

unisql.lib.full-path

定义:

指定动态库所在完整路径

取值范围及说明:

具有最高优先级，例如：/path/lib/unisql.xxx.x86_64.so（动态库寻找优先级：unisql.lib.full-path > Maven 依赖 > unisql.lib.dir）

是否可运行修改:

否

应用范围:

不限制

参数详细说明:

指定统一SQL动态库所在完整路径

unisql.lib.dir

定义:

指定动态库所在的目录

取值范围及说明:

最低优先级，例如：/path/lib/ （动态库寻找优先级：unisql.lib.full-path > Maven 依赖 > unisql.lib.dir）

是否可运行修改:

否

应用范围:

不限制

参数详细说明:

指定统一SQL动态库所在的目录

unisql.go.gomemlimit

定义:

统一 SQL 的 GOMEMLIMIT 配置

取值范围及说明:

统一 SQL 的 GOMEMLIMIT 配置，可指定 go 最大内存使用量， MB 为单位，默认 256 MB

是否可运行修改:

否

应用范围:

不限制

参数详细说明:

统一 SQL 的 GOMEMLIMIT 配置，可指定 go 最大内存使用量， MB 为单位，默认 256 MB,非必要无需调整。

unisql.go.gogc

定义:

GOGC 参数

取值范围及说明:

GOGC 参数，可指定 go gc 每次的增长比例，设置垃圾回收目标百分比‌，默认1000

是否可运行修改:

否

应用范围:

不限制

参数详细说明:

GOGC 参数，可指定 go gc 每次的增长比例，设置垃圾回收目标百分比‌，默认1000,非必要无需调整。

unisql.cache

定义:

缓存开关

取值范围及说明:

1或true：开启，0或false：关闭；默认为开启；在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

缓存开关，统一SQL会将SQL转换结果进行缓存，来提高效率。

unisql.skip

定义:

全局透传开关

取值范围及说明:

1或true：开启，0或false：关闭；默认为关闭；在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

开关开启时，所有SQL（SQL中没有 /*+noSkipTransform*/ 提示）不进行转换直接透传；开关关闭时，所有SQL进行统一SQL转换。

unisql.error.skip

定义:

全局异常透传开关

取值范围及说明:

1或true：开启，0或false：关闭；默认为关闭；在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

开关开启时，统一SQL转换过程中出现任何异常，SQL保持原样透传；开关关闭时，统一SQL转换过程中出现任何异常，返回报错提示信息。

unisql.global.replace.sql

定义:

全局替换SQL配置

取值范围及说明:

sql语句；默认为空字符串

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

配置了全局替换SQL时，对于目标库不支持的特性，返回用户配置的SQL。如果未配置替换SQL，对于目标库不支持的特性，是否报错以unisql.error.skip配置项为准。

目标库为gauss-oracle时，不支持特性如下：alter table … move tablespace …; alter table … convert to charset; flush privileges; set foreign_key_checks;

unisql.charset

定义:

编码格式设置

取值范围及说明:

0：utf-8 ，1：gbk ；默认为 utf-8 ;在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

编码格式，统一SQL支持源sql的编码格式。

unisql.schema

定义:

指定自定义函数所在Schema

取值范围及说明:

schema或database名称，默认值为 unisql

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

统一SQL自定义函数脚本执行所在的schema或database

unisql.remove.doubleQuoted

定义:

移除列名双引号开关

取值范围及说明:

1：开启，0：关闭；默认关闭

是否可运行修改:

是

应用范围:

源：mysql(8.x)/oracle(11g或19c)，目标：gaussdb_oracle(v500或v505)

参数详细说明:

当转换目标库为Gaussdb-Oracle,移除Alter Table、Create Table、Select、Insert、Inesrt All语句中列上的双引号

unisql.change.database.to.schema

定义:

database替换为schema开关

取值范围及说明:

0:不替换,1:替换 ;默认不替换

是否可运行修改:

是

应用范围:

源：mysql(8.x)/oracle(11g或19c)，目标：gaussdb_oracle(v500或v505)

参数详细说明:

是否将MySQL的create database替换成create schema,0不替换,1替换

unisql.decode.parameters.funcnames

定义:

指定decode函数参数转化为相同类型(支持text、numeric、date、timestamp)

取值范围及说明:

数据库内置函数名，多个函数名之间用英文逗号分割；默认为空

是否可运行修改:

是

应用范围:

源：oracle(11g或19c)，目标：gaussdb_oracle(v500或v505)

参数详细说明:

当转换目标库为Gaussdb-Oracle,decode函数的参数为函数且函数名在本参数的配置内时

（多个函数名之间用英文逗号分割），decode的参数类型转化为相同类型。

unisql.print.sysinfo

定义:

打印内存信息开关

取值范围及说明:

1：开启，0：关闭；默认关闭

是否可运行修改:

否

应用范围:

不限制

参数详细说明:

是否开启打印内存信息(注意：本参数仅适合在开发/测试环境开启观察内存使用情况，不允许在生产环境开启)。

unisql.print.logMemMinute

定义:

周期打印内存信息时间间隔设置

取值范围及说明:

整型数字，默认为10

是否可运行修改:

否

应用范围:

不限制

参数详细说明:

每隔多少分钟打印一次内存dump信息(在unisql.print.sysinfo=1时生效)

unisql.table.column.name.random

定义:

自定义表或字段使用随机数

取值范围及说明:

1：随机，0：不随机；默认不随机；在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

转换后的sql中自定义表或字段名称结尾是否使用随机数

unisql.keyword.doublequotes

定义:

关键字配置

取值范围及说明:

数据库关键字，如果配置多个用逗号隔开；默认为空

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

配置关键字，对象名如果匹配到了此配置参数中配置的关键字则使用双引号包裹，每个关键字之间用逗号分隔

unisql.on.update.currentimestamp.columns

定义:

指定mysql表中列含有ON UPDATE current_timestamp()属性

取值范围及说明:

配置表名及列名，格式:tableName:column1,column2

是否可运行修改:

是

应用范围:

原源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

对于mysql表中含有ON UPDATE current_timestamp()属性的列，在配置指定该列后，若更新语句中未指定该列的值，则会自动使用当前时间赋值

unisql.mysql.backslash.escapes

定义:

转义字符配置

取值范围及说明:

1：开启，0：关闭；默认关闭

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(V500)

参数详细说明:

源库是mysql时，是否识别  为转义字符

unisql.auto.increment.column

定义:

自增列配置

取值范围及说明:

配置格式为 tableName1:column1,column11;tableName2:column2；默认为空

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

兼容mysqlToGuassDB,对于auto_increment约束的列，insert into语句会将自增列截断处理，

不插入自增列的值，完全随数据库自增模式;格式:tableName1:column1;tableName2:column2;

unisql.table.column.replace.datatype

定义:

数据类型转换配置

取值范围及说明:

配置格式为 tableName:columnName:datatype；默认为空

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

源库是mysql时，指定表中字段转换后的数据类型

（如果 create table…/alter table … add | modify | change… 语句中表的字段和配置匹配，

则使用指定的数据类型，否则使用统一SQL正常转换数据类型，见数据类型章节）,格式： tableName:columnName:datatype;…，

tableName为表名，columnName为字段名，datatype为数据类型，如int、varchar(100);表名，字段名大小写敏感(需要填写数据库中创建后真实名称);

表名、字段名、数据类型不能为空;原始语句使用时不支持反引号中带双引号，例如: “object”

unisql.table.column.metadata.schemas

定义:

获取元数据时指定目标库schema

取值范围及说明:

字符串，指定目标库schema，默认为当前库连接当前操作schema

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

配置获取元数据的所在目标端schema,多个用逗号隔开

unisql.table.metadata.schedule.switch

定义:

定时拉取元数据开关

取值范围及说明:

1：开启，0：关闭；默认关闭

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

定时拉取最新元数据更新到缓存中开关，开启之后会周期性的去系统表拉取最新的元数据信息缓存到本地

unisql.table.metadata.schedule.frequency

定义:

定时拉取元数据频率设置

取值范围及说明:

正整数数字，默认为1440

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

用于设置周期性拉取元数据更新到缓存的频率，

当开启拉取缓存定时任务后会根据设置频率周期性拉取元数据更新到缓存，单位分钟，默认一天

unisql.null.table.columns

定义:

查询列为空转化配置

取值范围及说明:

配置格式为  tableName1:column1,column11;tableName2:column2;tableName3:*； 其中列名为*，指表中所有列；默认为空

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

源库是mysql，在查询语句中，为了解决列名的绑定变量值为空的转化问题，指定表名和列名后，

会将 where columnName = ? `` 转化成 ``where (columnName =? or (cast ? as dataType) is null and columnName is null)

unisql.datatype.number.replace.integer

定义:

number类型转为int类型配置

取值范围及说明:

0:不转换,1:转换;默认不转换

是否可运行修改:

是

应用范围:

源：oracle，目标：postgresql

参数详细说明:

源库为oracle，目标库为postgresql时，是否将number数据类型转为integer，

 0 不转，1 转，默认为 0 。在取值范围之外的按照默认值处理 。

unisql.drop.notnull.for.default.empty(@Deprecated)

定义:

按需去除 not null

取值范围及说明:

1：去除not null，0：不去除not null，默认为0

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

ddl中对于列约束为 not null default ‘’ 时，允许用户设置是否去除 not null。

1:去除not null，0:不去除not null，默认为0。

null和空在gauss-oracle中是相同的含义，not null default ‘’ 时也需要显式指定插入值，该配置项用于解决此问题。

unisql.notnull.behavior

定义:

处理字段约束包含not null

取值范围及说明:

0:不变，1:not null default ‘’去除not null转换后default ‘’，2:not null default ‘’转换到not null default ‘ ‘，默认值是0

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

ddl中对于列约束为 not null 的处理。 0:不变， 1:not null default ‘’去除not null转换后default ‘’， 2:not null default ‘’转换后not null default ‘ ‘， null和空在gauss-oracle中是相同的含义，not null default ‘’ 时也需要显式指定插入值，该配置项用于解决此问题。

unisql.table.column.upper.case

定义:

配置哪些表的哪些列查询时需要忽略大小写

取值范围及说明:

配置格式为 表名1:列名1,列名2;表名2:列名1;

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

mysql查询字符串列值时默认是忽略大小写的，Gaussdb-Oracle不支持此特性，

该功能会将满足条件的字段和条件值通过Upper函数包裹来实现查询时忽略大小写的功能。暂时只支持=、!=、like、not like。

同时会在统一SQL配置目录下生成create_index.sql文件, 提供业务手动创建索引。(索引名称是否超长、是否已创建和能否创建成功由业务方自己保证,和修改)。

unisql.table.column.upper.case.print.sql.switch

定义:

指定表的字段查询大小写不敏感时，解析DDL生成创建索引语句时，是否日志提示还是启动失败

取值范围及说明:

0：提示且不启动统一SQL，1：提示并启动统一SQL。默认为0

是否可运行修改:

是

应用范围:

源：mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

如果配置了unisql.table.column.upper.case参数，

指定表的字段查询大小写不敏感时，此参数才会生效，

用于提示业务手动创建统一SQL配置目录下生成的create_index.sql文件中的索引。

unisql.transform.replace.into

定义:

用于控制mysq转GoldenDB-Mysql的场景是否将replace into语法转化为merge into语法

取值范围及说明:

0：不转换，1：转换。默认为0

是否可运行修改:

是

应用范围:

源：Mysql(8.x)，目标：GoldenDB-Mysql

参数详细说明:

将replace into语法转化为merge into语法，前提为目标库是mysql系且支持merge into语法。

unisql.mysql.restore.name.back.quotes

定义:

用于控制SQL语句转换后表明、列名是否携带反引号

取值范围及说明:

0：关闭，转换后不带反引号，1：开启，转换后带反引号。默认为0

是否可运行修改:

是

应用范围:

源：Mysql(8.x)，目标：Gaussdb-Oracle(v500)

参数详细说明:

Gaussdb-Oracle(v500)表名，列名不带反引号时大小写敏感，带反引号时大小写不敏感，用户可以根据实际需求配置该参数。

unisql.log.enable

定义:

日志打印开关

取值范围及说明:

1：开启，0：关闭；默认为开启；在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

用来控制是否开启日志打印功能。开启时可以打印日志，关闭时不能打印日志，作用范围仅为统一SQL日志。(注意：1.只有打印日志逻辑外层套有.IsXXXEnabled()逻辑判断时才会生效 2.配置文件初始化日志不受此配置影响，默认都会打印)

unisql.log.level

定义:

日志级别设置

取值范围及说明:

DEBUG、INFO、WARN、ERROR；默认为ERROR,在取值范围之外的按照默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

统一SQL日志级别设置，作用范围仅为统一SQL日志，日志级别优先级为：debug<info<warn<error（注意：配置文件初始化日志不受此配置影响，默认都会打印）

unisql.slowsql.enable

定义:

慢SQL/大SQL告警日志打印开关

取值范围及说明:

1:开启,0:关闭;默认为关闭,取值范围之外的值按默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

打印慢SQL和大SQL日志开关，作用范围仅为统一SQL日志，只有在开启时配置项[unisql.slowsql.duration]和[unisql.slowsql.length]才会生效

unisql.slowsql.length

定义:

大SQL阈值配置

取值范围及说明:

取值范围:正整数，默认值2000,单位字节,取值范围之外按默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

大SQL阈值配置，当原始SQL或转换后SQL长度大于配置阈值且[unisql.slowsql.enable]配置项为开启时打印大SQL告警日志

unisql.slowsql.duration

定义:

慢SQL阈值配置

取值范围及说明:

取值范围:正整数，默认值100,单位微妙,取值范围之外按默认值处理

是否可运行修改:

是

应用范围:

不限制

参数详细说明:

慢SQL阈值配置，当SQL转换耗时超过配置阈值且[unisql.slowsql.enable]配置项为开启时打印慢SQL告警日志

unisql.remove.ignore

定义:

update ignore set xxx 转化是否去除 ignore

取值范围及说明:

1：开启，0：关闭；默认为开启；在取值范围之外的值按照默认值处理

是否可运行修改:

是

应用范围:

源：Mysql(8.x)，目标：gaussdb_oracle(v500)

参数详细说明:

源库为mysql，update ignore set xxx 相关语法转化时，允许用户设置是否去除 ignore，1:去除ignore，0:不去除ignore

unisql.target.database.version

定义:

设置目标端版本号信息

取值范围及说明:

统一SQL具体的目标端数据源版本号

是否可运行修改:

是

应用范围:

所有统一SQL已支持的目标端数据源版本号

参数详细说明:

统一SQL转换逻辑会根据不同的数据库及版本有所差异，可以配置此参数来指定目标端数据库版本号。

unisql.plsql.connUrl

定义:

设置LightDB连接字符串

取值范围及说明:

LightDB连接字符串

是否可运行修改:

是

应用范围:

目标库为OceanBase_Oracle时，plsql语法转换场景会使用该配置项

参数详细说明:

plsql语法转换当前通过LightDB实现，该配置用于配置LightDB数据库连接字符串，格式为[ host=LightDB主机IP port=LightDB服务端口 user=LightDB连接用户 password=LightDB连接密码 dbname=LightDB数据库名 sslmode=disable ]，LightDB版本需要在24.3及以上

unisql.bind.variable.mode

定义:

是否将ares studio伪SQL中的绑定变量前缀@原样返回，0:按照正常处理（目标端mysql则为@，目标端为oracle则为:），1:全部返回@。默认为0

取值范围及说明:

0:按照正常处理（目标端mysql则为@，目标端为oracle则为:），1:全部返回@。默认为0

是否可运行修改:

是

应用范围:

所有统一SQL已支持的目标端数据源版本号

参数详细说明:

是否将ares studio伪SQL中的绑定变量前缀@原样返回，0:按照正常处理（目标端mysql则为@，目标端为oracle则为:），1:全部返回@。默认为0。

4.5. 兜底配置文件(24.1.6版本开始支持)

兜底配置文件内容是一个kv结构的json数组。如果配置了兜底文件，统一SQL转换前会将源sql和兜底配置文件中的from内容匹配，匹配一致则不进行转换，直接返回to中的内容。

备注

配置文件命名： <来源方言>2<目标方言>.json 方言都小写，例如：oracle2gaussdb_oracle.json

配置案例:

[
{"from": "select * from unisql_people_source where person_id = ? and person_id= ?",
    "to": "select * from unisql_people_source where person_id in (?,?)"
},
{"from": "select * from unisql_people_source where person_id in (3,5)",
    "to": "select * from unisql_people_source where person_id = 3 or person_id= 5"
}
]

4.6. 系统参数与环境变量

统一SQL支持以下系统变量或环境变量

环境变量名

说明

unisql_lib_dir

指向动态库所在的目录，等同于系统参数 unisql.lib.dir，环境变量与系统参数选一种方式配置即可；都配置则以系统参数优先

unisql_lib_full_path

指定动态库所在完整路径，等同于系统参数 unisql.lib.full-path ，环境变量与系统参数选一种方式配置即可；都配置则以系统参数优先

4.7. JDBC 连接参数

即 JDBC 连接 URL 中 ? 后面的参数部分，以下参数是统一SQL驱动识别的必须参数。

参数名

说明

sourceDialect

来源方言，必须配置。目前支持 oracle 或 mysql，统一SQL和多发都必须配置此参数。

targetDialect

目标方言，必须配置。统一SQL和多发都必须配置此参数。目前支持 postgresql、lightdb_oracle、tdsql_mysql、tdsql_oracle、oceanbase_mysql、oceanbase_oracle、gaussdb_oracle、dm、opengauss

mode

兼容模式，统一SQL模式下，如果源SQL中使用了mysql本身的SQL_CALC_FOUND_ROWS特性，则必须配置为MYSQL，历史遗留问题，当源方言是MySQL的时候也需要配置。如果是多发模式下，Oracle或MySQL数据库的连接串上必须配置为MULTIPLEX。

sourceDialect 对应源数据库方言，用于在统一SQL转换时，作为源方言，详细对应信息如下：

值

说明

oracle

oracle支持11g或19c

mysql

mysql8.x版本

targetDialect 对应目标数据库方言，用于在统一SQL转换时，作为目标方言，详细对应信息如下：

值

说明

postgresql

postgresql13.x,14.x

lightdb_oracle

lightdb_oracle 兼容模式

tdsql_mysql

tdsql mysql兼容模式，兼容mysql5.7 和 8

tdsql_pg_oracle

tdsql oracle兼容模式

oceanbase_oracle

oceanbase oracle兼容模式 3.2

oceanbase_mysql

oceanbase mysql兼容模式 3.2

gaussdb_oracle

GaussDB oracle兼容模式 V500/V505

达梦

达梦版本

openGauss

opengauss

oracle

多发源库为oracle时，使用此配置值

openGauss

opengauss