11.1. 统一SQL http接口
11.1.1. 简介
统一SQL开放了一个http接口，用户可以通过该接口获取统一SQL的转换结果，多发执行和比对结果是否一致。
11.1.2. 接口请求地址
11.1.3. 请求方式
POST
11.1.4. Content-Type
application/json;charset=UTF-8
11.1.5. 接口请求参数
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
|---|---|---|---|---|---|
sourceDialect |
String |
是 |
源端数据库方言ORACLE，MYSQL |
ORACLE、MYSQL |
ORACLE |
targetDialectInfos |
List<TargetDialectInfo> |
是 |
目标数据库信息 |
详细见如下TargetDialectInfo对象结构 |
|
sql |
String |
是 |
转换前sql |
update unisql_test set name = @name where id=@id |
|
sqlParameters |
List<BindVariable> |
否 |
预编译sql语句的参数信息 |
详细见如下BindVariable对象结构 |
TargetDialectInfo对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
targetDialect |
String |
是 |
目标数据库类型加兼容模式（大小写均可，建议全大写）。注：此处GAUSSDB_ORACLE表示gaussdb 505版本，GAUSSDB500_ORACLE表示gaussdb 500版本 |
当源为ORACLE时，目标库取值范围：LIGHTDB_ORACLE, POSTGRESQL, TDSQL_MYSQL, TDSQL_PG_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE, OCEAN_BASE_MYSQL; 当源为MYSQL时，目标库取值范围GAUSSDB500_ORACLE, GOLDENDB_MYSQL |
GAUSSDB500_ORACLE |
targetDbVersion |
String |
否 |
目标数据库版本（预留项，暂未使用） |
||
schemaName |
String |
否 |
多发执行时，会在每个目标数据库下指定的业务库或schema下执行sql，不填则按照数据源配置中的dbname执行SQL。oracle系为用户名；mysql、postgresql系为URL中ip和port后面的databaseName |
dbtrade |
|
multiCompare |
Boolean |
是 |
是否执行多发比对，为true时，转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致 |
true |
BindVariable对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
示例 |
|---|---|---|---|---|
name |
String |
是 |
sql语句的绑定变量名(伪代码SQL中的@绑定变量的名字) |
name |
type |
Integer |
是 |
预编译sql语句的绑定变量参数值类型（java.sql.Types中的具体值）支持范围见如下：数据类型支持范围和java.sql.Types映射值章节 |
12 |
value |
Object |
是 |
预编译sql语句的绑定变量参数的内容 |
lilei |
11.1.6. 数据类型支持范围和java.sql.Types映射值章节
variableType支持的数据类型映射值如下：
字段类型 |
java.sql.Types |
variableType值(对应java.sql.Types值) |
|---|---|---|
BINARY_FLOAT、FLOAT、REAL |
Types.FLOAT |
6 |
BINARY_DOUBLE、DOUBLE、DOUBLE PRECISION |
Types.DOUBLE |
8 |
CHAR、CHARACTER |
Types.CHAR |
1 |
NCHAR |
Types.NCHAR |
-15 |
NVARCHAR、NVARCHAR2、NCHAR VARYING |
Types.NVARCHAR |
-9 |
VARCHAR、VARCHAR2、TINYTEXT |
Types.VARCHAR |
12 |
TINYINT 、INT1 |
Types.TINYINT |
-6 |
SMALLINT 、INT2 |
Types.SMALLINT |
5 |
INTEGER、INT、INT3、MEDIUMINT、INT4 |
Types.INTEGER |
4 |
BIGINT、INT8 |
Types.BIGINT |
-5 |
BLOB |
Types.BLOB |
2004 |
CLOB |
Types.CLOB |
2005 |
DECIMAL、DEC、NUMBER、NUMERIC |
Types.DECIMAL |
3 |
DATE |
Types.DATE |
91 |
TIME |
Types.TIME |
92 |
TIMESTAMP、DATETIME、TIMESTAMP(p) WITH TIME ZONE |
Types.TIMESTAMP |
93 |
ROWID |
Types.ROWID |
-8 |
BOOL、BOOLEAN |
Types.BOOLEAN |
16 |
TEXT、MEDIUMTEXT、LONGTEXT |
Types.LONGVARCHAR |
-1 |
11.1.7. 接口返回参数
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
|---|---|---|---|---|---|
code |
int |
是 |
状态码，0表示成功，非0表示异常 |
完整清单详见下文错误码清单 |
0 |
message |
String |
是 |
信息描述 |
转换成功/转换成功且需要多发的目标端[xxx]已经发送多发服务，后续可根据traceId查看多发比对结果是否一致 |
|
data |
MultiplexOutput |
否 |
目标库转换后信息实体 |
MultiplexOutput对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
示例 |
|---|---|---|---|---|
sourceDialect |
String |
是 |
源端数据库类型 |
oracle/mysql |
targetDialectInfos |
List<TargetDialectInfo> |
是 |
目标数据库信息 |
|
traceId |
String |
否 |
用于查询比对报告的ID |
84cbb67ad75b47b689445f33c3d4cef3 |
TargetDialectInfo对象结构如下：
参数名 |
类型 |
是否必须 |
说明 |
取值范围 |
示例 |
targetDialect |
String |
是 |
目标数据库类型加兼容模式（大小写均可，建议全大写）。注：此处GAUSSDB_ORACLE表示gaussdb 505版本，GAUSSDB500_ORACLE表示gaussdb 500版本 |
当源为ORACLE时，目标库取值范围：LIGHTDB_ORACLE, POSTGRESQL, TDSQL_MYSQL, TDSQL_PG_ORACLE, GAUSSDB_ORACLE, DM, OCEAN_BASE_ORACLE, OCEAN_BASE_MYSQL; 当源为MYSQL时，目标库取值范围GAUSSDB500_ORACLE, GOLDENDB_MYSQL |
GAUSSDB500_ORACLE |
targetDbVersion |
String |
否 |
目标数据库版本（预留项，暂未使用） |
||
schemaName |
String |
否 |
多发执行时，会在每个目标数据库下指定的业务库或schema下执行sql，不填则按照数据源配置中的dbname执行SQL。oracle系为用户名；mysql、postgresql系为URL中ip和port后面的databaseName |
dbtrade |
|
multiCompare |
Boolean |
是 |
是否执行多发比对，为true时，转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致 |
true |
|
sql |
String |
是 |
转换后sql |
update unisql_test set name = @name where id=@id |
11.1.8. 错误码
错误码 |
描述 |
|---|---|
0 |
转换成功/转换成功且需要多发的目标端[xxx]已经发送多发服务，后续可根据traceId查看多发比对结果是否一致 |
10000 |
入参不能为空！ |
10001 |
目标数据库信息[targetDialectInfos]不能为空！ |
10002 |
目标数据库类型[targetDialect]不能为空！ |
10003 |
目标数据库类型[%s]暂不支持！ |
10004 |
源端数据库类型[%s]输入不正确,目前只持支oracle，mysql！ |
10005 |
输入的源sql不能为空！ |
20000 |
源库[%s]到目标库[%s]转换失败 |
-1 |
未知异常 |
11.1.9. 两种使用场景以及示例
1、仅通过统一SQL进行SQL转换
2、通过统一SQL进行SQL转换同时转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致
11.1.9.1. 请求示例一
仅通过统一SQL进行SQL转换
{
"sourceDialect": "ORACLE", // 源端数据库类型，本例源库为oracle
"targetDialectInfos": [ // 目标数据库类型信息
{
"targetDialect": "LIGHTDB_ORACLE" // 目标数据库类型1，表示lightdb-oracle
}
,
{
"targetDialect": "GAUSSDB_ORACLE" // 目标数据库类型2，表示gaussdb-oracle
}
,
{
"targetDialect": "GAUSSDB500_ORACLE" // 目标数据库类型3，表示gaussdb500-oracle
}
,
{
"targetDialect": "DM" // 目标数据库类型4，表示dm
}
,
{
"targetDialect": "OCEAN_BASE_ORACLE" // 目标数据库类型5，表示ob-oracle
}
],
"sql": "select id,name from unisql_test where id=@id and name=@name order by id" // 业务原始SQL语句，本例中表示需要转换到各目标库的oracle语句
}
11.1.9.2. 返回示例一
{
"code": 0, // 返回状态码，0表示转换成功
"data": {
"sourceDialect": "ORACLE", // 源端数据库类型，本例中源库为oracle
"targetDialectInfos": [ // 目标数据库SQL转换信息
{
"targetDialect": "LIGHTDB_ORACLE", // 目标数据库类型1，表示lightdb-oracle
"sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id" // 由oracle源sql转换而来的lightdb-oracle的方言语句
},
{
"targetDialect": "GAUSSDB_ORACLE", // 目标数据库类型2，表示gaussdb-oracle
"sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id" // 由oracle源sql转换而来的gaussdb-oracle的方言语句
},
{
"targetDialect": "GAUSSDB500_ORACLE", // 目标数据库类型3，表示gaussdb500-oracle
"sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id" // 由oracle源sql转换而来的gaussdb500-oracle的方言语句
},
{
"targetDialect": "DM", // 目标数据库类型4，表示dm
"sql": "select id,name from unisql_test where id=@id and name=@name order by id" // 由oracle源sql转换而来的dm的方言语句
},
{
"targetDialect": "OCEAN_BASE_ORACLE", // 目标数据库类型5，表示ob-oracle
"sql": "select id,name from unisql_test where id=@id and name=@name order by id" // 由oracle源sql转换而来的ob-oracle的方言语句
}
]
},
"message": "转换成功" // 返回状态具体信息描述
}
11.1.9.3. 请求示例二
通过统一SQL进行SQL转换同时转换成功后内部会异步调用多发服务并直接返回traceId，后续可根据traceId查看多发比对结果是否一致。如下例子为ORACLE到LIGHTDB_ORACLE、GAUSSDB_ORACLE、GAUSSDB500_ORACLE、DM、OCEAN_BASE_ORACLE 5个库的统一SQL转换。同时 ORACLE到LIGHTDB_ORACLE、GAUSSDB_ORACLE、DM、OCEAN_BASE_ORACLE 4个库的异步多发验证。
{
"sourceDialect": "ORACLE", // 源端数据库类型，本例源库为oracle
"targetDialectInfos": [ // 目标数据库类型信息
{
"targetDialect": "LIGHTDB_ORACLE", // 目标数据库类型1，表示lightdb-oracle
"multiCompare": true // 是否进行多发验证
}
,
{
"targetDialect": "GAUSSDB_ORACLE", // 目标数据库类型2，表示gaussdb-oracle
"multiCompare": true // 是否进行多发验证
}
,
{
"targetDialect": "GAUSSDB500_ORACLE", // 目标数据库类型3，表示gaussdb500-oracle
"multiCompare": false // 是否进行多发验证
}
,
{
"targetDialect": "DM", // 目标数据库类型4，表示dm
"multiCompare": true // 是否进行多发验证
}
,
{
"targetDialect": "OCEAN_BASE_ORACLE", // 目标数据库类型5，表示ob-oracle
"multiCompare": true // 是否进行多发验证
}
],
"sql": "select id,name from unisql_test where id=@id and name=@name order by id", // 业务原始SQL语句，本例中表示需要转换到各目标库的oracle语句
"sqlParameters": [ // 绑定变量参数内容
{
"name": "id", // 绑定变量名称
"type": 4, // 绑定变量类型
"value": 1 // 绑定变量值
}
,
{ // 第二个绑定变量参数内容
"name": "name",
"type": 12,
"value": "测试"
}
]
}
11.1.9.4. 返回示例二
{
"code": 0, // 返回码，0成功
"data": {
"sourceDialect": "ORACLE", // 源端数据库类型，本例中源库为oracle
"targetDialectInfos": [ // 目标数据库SQL转换信息
{
"targetDialect": "LIGHTDB_ORACLE", // 目标数据库类型1，表示lightdb-oracle
"sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id", // 由oracle源sql转换而来的lightdb-oracle的方言语句
"multiCompare": true // 进行多发验证
},
{
"targetDialect": "GAUSSDB_ORACLE", // 目标数据库类型2，表示gaussdb-oracle
"sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id", // 由oracle源sql转换而来的gaussdb-oracle的方言语句
"multiCompare": true // 进行多发验证
},
{
"targetDialect": "GAUSSDB500_ORACLE", // 目标数据库类型3，表示gaussdb500-oracle
"sql": "SELECT id,name FROM unisql_test WHERE id=@id AND name=@name ORDER BY id", // 由oracle源sql转换而来的gaussdb500-oracle的方言语句
"multiCompare": false // 不进行多发验证
},
{
"targetDialect": "DM", // 目标数据库类型4，表示dm
"sql": "select id,name from unisql_test where id=@id and name=@name order by id", // 由oracle源sql转换而来的dm的方言语句
"multiCompare": true // 进行多发验证
},
{
"targetDialect": "OCEAN_BASE_ORACLE", // 目标数据库类型5，表示ob-oracle
"sql": "select id,name from unisql_test where id=@id and name=@name order by id", // 由oracle源sql转换而来的ob-oracle的方言语句
"multiCompare": true // 进行多发验证
}
],
"traceId": "fdea3b18-118d-453f-b5a6-2cf4745ea654" // 用于查询比对报告的ID
},
"message": "转换成功且需要多发的目标端[GAUSSDB_ORACLE,DM,OCEAN_BASE_ORACLE,ORACLE]已经发送多发服务，后续可根据traceId查看多发比对结果是否一致" // 返回状态信息
}