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

3.1. 配置文件

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

系统配置文件：unisql.conf
兜底策略配置文件：oracle2gaussdb_oracle.json、mysql2goldendb_mysql.json

3.2. 目录层级

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

3.3. 配置方式

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

通过环境变量： unisql_conf_dir 指定统一SQL配置所在目录
- 例如:export unisql_conf_dir=/xxx/xxx/cres/fbase/workspace/config
如果没有配置环境变量则会去业务启动脚本所在目录（业务当前工作目录）的 config 目录下寻找

注意

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

3.4. unisql.conf文件说明

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

unisql.cache

定义

缓存开关

取值范围及说明

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

是否可运行修改

否

应用范围

不限制

参数详细说明

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

unisql.debug

定义

debug级别日志开关

取值范围及说明

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

是否可运行修改

否

应用范围

不限制

参数详细说明

是否开启 DEBUG 模式，将打印更多的日志。

unisql.error.skip

定义

SQL执行异常透传开关

取值范围及说明

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

是否可运行修改

否

应用范围

不限制

参数详细说明

全局异常透传，转换过程中出现任何异常,SQL保持原样透传。

unisql.skip

定义

全局透传开关

取值范围及说明

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

是否可运行修改

否

应用范围

不限制

参数详细说明

全局透传，开启后所有SQL不进行转换直接透传。

unisql.compare.server.url

定义

比对服务URL地址

取值范围及说明

http请求格式的 URL串；默认为空

是否可运行修改

否

应用范围

不限制

参数详细说明

统一SQL对比服务的http请求URL，如果配置了正确的对比服务URL，则每条SQL都将发送到对比服务，

对比服务会对源库执行结果和目标库执行结果进行语义一致性对比，并输出对比报告。默认为空不开启对比

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)

参数详细说明

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

unisql.decode.parameters.funcnames

定义

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

取值范围及说明

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

是否可运行修改

否

应用范围

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

参数详细说明

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

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

unisql.global.replace.sql

定义

全局SQL替换配置

取值范围及说明

sql语句；默认为空字符串

是否可运行修改

否

应用范围

不限制

参数详细说明

按需将目标库无法支持的特性语句转换成自定义的SQL,默认是 select 1 。

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.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.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

定义

按需去除 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.table.column.upper.case

定义

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

取值范围及说明

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

是否可运行修改

否

应用范围

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

参数详细说明

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

该功能会将满足条件的字段和条件值通过Upper函数包裹来实现查询时忽略大小写的功能。

同时会在统一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文件中的索引。

3.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"
}
]