JDBC数据服务是通过JDBC将后端数据库访问能力在CSB实例上发布为服务,发布服务时只能以RESTful开放类型发布。

前提条件

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

背景信息

  • JDBC目前支持单表和多表查询,后续根据需要会提供插入、修改和删除库表数据的能力。
  • 每个CSB实例可以配置多个数据源,多个服务可以共享一个数据源。

管理数据源

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

CSB目前支持PostgreSQL兼容的数据库,包括RDS PostgreSQL、AnalyticDB PostgreSQL、PostgreSQL。

每个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模板需要包含XML转义字符时,请参见SQL模板包含XML转义字符该如何设置?

        如果SQL模板需要判断入参是否存在时,请参见SQL模板如何判断某个入参是否存在?

      • 生成的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服务调用方式完全一样。

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

java -jar http-sdk-1.1.5.8.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数据服务问题