JDBC 数据服务是通过 JDBC 将后端数据库访问能力以 RESTful 方式在 CSB 实例上发布为服务。

前提条件

  • 创建或申请 CSB 实例,详情请参见创建实例
  • 了解如何在 CSB 实例上发布、订阅和调用 RESTful 服务的基本使用,详情请参见快速体验服务概述
  • 具有 SQL 和 MyBatis 基本使用基础知识。

背景信息

JDBC 目前支持单表和多表查询,后续根据需要会提供插入、修改和删除库表数据的能力。

每个 CSB 实例可以配置多个数据源,多个服务可以共享一个数据源:

管理数据源

CSB 目前支持 MySQL 兼容的数据库,包括 RDS、DRDS 和 MySQL。

CSB 默认使用的 MySQL JDBC 驱动版本为 5.1.40 (兼容此版本之前的驱动)。如需使用特定版本的 MySQL 驱动,请联系 CSB 技术支持人员。

每个 CSB 实例可以配置多个数据源,多个服务可以共享一个数据源。具体操作方式请参见管理数据源

发布 JDBC 服务

发布 JDBC 服务请参见发布服务。在接入协议步骤中因单表和多表查询而配置有所不同。

  • 单表查询
    1. 配置接入服务。 接入协议-接入服务-JDBC

      配置项说明:

      • 数据源:选择 CSB 实例上已配置好的数据源,或直接单击数据源管理进行当前 CSB 实例数据源的新增、修改和删除。
      • 返回记录数上限:一次查询服务请求最多允许返回多少条记录。
      • SQL 模板:以 MyBatis 语法进行查询 SQL 语句模板表达,只写 FROM 表名 WHERE 条件 ORDER/GROUP 子句,CSB 自动根据接入协议的出参配置进行 SELECT 结果字段列表子句的生成。SQL 模板示例如下:
        FROM tableName 
        WHERE field1 > #{参数1} and field2 in (#{参数21}, #{参数22}) and field3 like concat('%',#{参数3},'%') 
        ORDER BY field4 asc, field5 desc
      • 生成的SQL模板:显示根据当前出参和SQL模板最终生成的查询SQL示意。
      • 生成的统计SQL模板:显示根据当前配置和SQL模板最终生成的查询记录数统计SQL示意。
      • 高级选项COUNT扫描总记录数保护是通过设置 COUNT扫描总记录数上限,对 SQL 语句进行封装,限定统计 SQL 扫描记录数量的上限,避免 COUNT 命令对数据库造成的压力。

    2. 编辑 SQL 条件参数。

      CSB 自动生成单表查询的入参模板字段,并根据入参配置自动将请求参数传递给 MyBatis 语法的 SQL 模板,以便执行数据查询。

      接入服务-编辑 SQL 条件参数-JDBC

      各入参字段说明如下:

      • requireTotalCount:是否返回总记录数,CSB 客户端传 true 时,CSB 会使用“统计SQL模板”进行总记录数统计。可以删除此模板字段入参,删除后不允许此服务进行总记录统计。
      • offset:从第 n 条查询结果记录开始返回,含义与 MySQL 的此关键字一致。可以删除此模板字段入参,删除后不允许此服务进行 offset 操作。
      • limit:限定本次服务请求返回的记录数,含义与 MySQL 的此关键字一致。可以删除此模板字段入参,删除后不允许此服务进行 limit 操作。
      • queryValues:所有查询参数的结构体,每个子结点的“SQL模板参数”对应一个 SQL 模板的 MyBatis 参数,“发布入参名”对应客户端发起请求时传入的参数名。此结构体入参结点不可删除。
    3. 编辑 SQL 结果参数

      CSB 根据结果参数配置自动生成 SQL 模板的“SELECT 字段列表”子名。

      SQL 结果参数-JDBC

      CSB 自动生成单表查询的结果参数说明:

      • resultCode:查询服务返回码,参见错误代码,不可删除。
      • resultMsg:查询服务执行结果消息,不可删除。
      • tatalCount:符合查询条件的总记录数,不可删除。
      • count:本次查询请求返回的记录数,不可删除。
      • result:本次查询结果记录集结构体,CSB 根据此结构体子结点自动生成“SELECT 字段列表”子句,不可删除。
      • __csbRecordError:如果记录的某个字段解析错误,则此字段保存错误信息。例如出参定义某个字段为 Long 型,但数据表中对应字段的某条记录为字符值,则在试图解析到此记录的字段值并转换为 Long 型时会抛出异常,导致此条记录生成失败,此时定义的业务结果字段为空,而此字段则会表达出生成记录的错误信息。不可删除。
  • 多表查询

    与单表查询类似,可参见单表查询结果参数说明,只是特定配置项和字段要求略有不同。

    1. 配置接入服务。接入协议-配置接入服务-JDBC-多表查询

      配置项说明:

      • 数据表名和表别名列表:以英文逗号分隔的多个数据库表和别名,如table1 as t1, table2 t2
      • SQL模板:与单表查询不同之处在于需要明确写各表的别名,以及各字段归属表的别名,SQL 模板示例如下:
        FROM table1 alias1, table2 alias2 
        WHERE alias1.id=alias2.id1 and alias1.field1 > #{参数1} and alias2.field2 in (#{参数21}, #{参数22}) and alias2.field3 like concat('%',#{参数3},'%') 
        ORDER BY alias1.field4 desc, alias2.field5 desc
    2. 编辑 SQL 条件参数。

      多表查询与单表查询的参数配置一致,详情请参见单表查询 SQL 条件参数说明。

    3. 编辑 SQL 结果参数。

      多表查询与单表查询的参数配置一致,只是需要明确字段归属的表别名.字段名

订阅 JDBC 服务

与订阅其它类型服务的步骤一致,详情请参见订阅服务

调用 JDBC 服务

JDBC 数据服务目前只支持 RESTful 协议,客户端调用时与普通 RESTful 服务调用方式完全一样。详情请参见使用 HTTP-SDK 调用 Console API

命令行方式调用 JDBC 数据服务示例如下:

java -jar http-sdk-1.1.4.jar -method post -url "http://CSB服务地址:8086/CSB" \
     -api "JDBC数据服务名" -version "服务版本号" -ak "凭证ak" -sk "凭证sk" \
     -cbJSON "{'requireTotalCount':true,'offset':跳过n条记录,'limit':返回记录数上限,'queryValues':{'查询条件字段1':'查询条件字段值1', '查询条件字段2':'查询条件字段值2'}}"     
说明 CSB 服务地址即创建该实例时绑定的 SLB 的地址。

相关信息

如果您对 CSB 中的 JDBC 数据服务有任何疑问,可参见JDBC 数据服务问题