# 1 简介
数据库访问是平台提供的访问数据库的接口DB。它的基本用法与JDBC相似，但是它提供更加统一方便的接口。在使用DB访问数据库的时候统一使用KSQL语法。在苍穹系统中，支持每个应用使用独立的数据库，SQL在哪个数据库上执行是通过DBRoute来路由。DB屏蔽了物理数据库信息，用DBRoute对应具体的物理库，由mc的数据中心管理进行配置。DBRoute内置了常用的routeKey，也可以通过DBRoute.of("routeKey")来构造。表单的routeKey在设计时已自动指定，在同一个应用下的表单routeKey相同。
# 2 应用场景
在需要通过SQL访问的场景下必须使用DB来访问数据库。
# 3 接口说明
数据库访问DB相关接口定义和实现存在于bos-dbengine-1.0.jar中。对于使用者来说只需要调用kd.bos.db.DB类中的方法即可。
## 3.1 接口列表
| 方法 | 说明 |
| - | - |
| query | 查询 |
| queryDataSet | 查询（返回DataSet） |
| update | 插入、更新或删除 |
| execute | 执行任何类型的SQL |
| executeBatch | 批量执行任何类型的SQL |
| timeout | 设置超时时间 |
| getDBType | 获取数据库类型 |
| exitsTable | 判断表是否存在 |
| exitsIndex | 判断表索引是否存在 |
| getPrimaryKeys | 获取表主键 |
| getFieldInfo | 获取表的字段信息 |
| getIndexInfo | 获取表的索引信息 |
| isXDBEnable | 是否启用了xdb引擎(水平分表) |
| isSplittingReadEnable | 是否开启读写分离 |
| isSplittingAutoReadWrite | 是否开启自动读写模式 |
| getWrittenRouteKey | 获取当前事务已写的库路由标识 |
## 3.2 接口详情
### query
+ **功能描述**
查询数据库操作。
+ **方法**
```java
public static <T> T query(DBRoute dbRoute, String sql, ResultSetHandler<T> rh)
public static <T> T query(DBRoute dbRoute, String sql, Object[] params, ResultSetHandler<T> rh)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| dbRoute | DBRoute | 数据库路由 |
| sql | String | 查询SQL语句 |
| params | Object[] | SQL参数 |
| rh | ResultSetHandler\<T> | jdbc结果集ResultSet处理器 |
+ **返回值**
返回ResultSet处理器返回的结果。
+ **示例代码**
```java
// 不带参数
String sql = "SELECT * FROM table;"
DB.query(DBRoute.basedata, sql, rs -> {
return rs.next();
});
// 带参数
String sql = "SELECT * FROM table WHERE fid=?;"
DB.query(DBRoute.basedata, sql, new Object[]{"xxxxxxxx"}, rs -> {
return rs.next();
});
```
### queryDataSet
+ **功能描述**
查询数据库操作（返回DataSet）。
+ **方法**
```java
public static DataSet queryDataSet(String algoKey, DBRoute dbRoute, String sql)
public static DataSet queryDataSet(String algoKey, DBRoute dbRoute, String sql, Object[] params)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| algoKey | String | algo标识 |
| dbRoute | DBRoute | 数据库路由 |
| sql | String | 查询SQL语句 |
| params | Object[] | SQL参数 |
> 参数algoKey用于跟踪性能，当前执行的时间将被记录到指标系统。这个值，应能有效定位到代码, 如=类名+方法，至少含类名。
+ **返回值**
返回DataSet数据集（它是根据查询结果ResultSet包装而来）。
+ **示例代码**
```java
// 不带参数
String sql = "SELECT * FROM table;"
DataSet dataSet = DB.queryDataSet(this.getClass.getName(), DBRoute.basedata, sql);
// 带参数
String sql = "SELECT * FROM table WHERE fid=?;"
DataSet dataSet = DB.queryDataSet(this.getClass.getName(), DBRoute.basedata, sql, new Object[]{"xxxxxxxx"});
```
### update
+ **功能描述**
插入、更新或删除数据库操作。
+ **方法**
```java
public static int update(DBRoute dbRoute, String sql)
public static int update(DBRoute dbRoute, String sql, Object[] params)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| dbRoute | DBRoute | 数据库路由 |
| sql | String | 查询SQL语句 |
| params | Object[] | SQL参数 |
+ **返回值**
更新数据的行数。
+ **示例代码**
```java
// 不带参数
String sql = "UPDATE t_xxx SET field=xxx WHERE fid=xxx;"
DB.update(DBRoute.basedata, sql);
// 带参数
String sql = "UPDATE t_xxx SET field=? WHERE fid=?;"
DB.update(DBRoute.basedata, sql, new Object[]{"xxx", "xxx"});
```
### execute
+ **功能描述**
执行任何类型的SQL。
+ **方法**
```java
public static boolean execute(DBRoute dbRoute, String sql)
public static boolean execute(DBRoute dbRoute, String sql, Object[] params)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| dbRoute | DBRoute | 数据库路由 |
| sql | String | 查询SQL语句 |
| params | Object[] | SQL参数 |
+ **返回值**
是否执行成功。
+ **示例代码**
```java
// 不带参数
String sql = "UPDATE t_xxx SET field=xxx WHERE fid=xxx;"
DB.execute(DBRoute.basedata, sql);
// 带参数
String sql = "UPDATE t_xxx SET field=? WHERE fid=?;"
DB.execute(DBRoute.basedata, sql, new Object[]{"xxx", "xxx"});
```
### executeBatch
+ **功能描述**
批量执行任何类型的SQL。
+ **方法**
```java
public static boolean execute(DBRoute dbRoute, String sql, List<Object[]> paramsList)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| dbRoute | DBRoute | 数据库路由 |
| sql | String | 查询SQL语句 |
| paramsList | List<Object[]> | SQL参数列表 |
+ **返回值**
批量执行的数量。
+ **示例代码**
```java
String sql = "UPDATE t_xxx SET field=? WHERE fid=?;";
List<Object[]> paramsList = new ArrayList();
Object[] params = new Object[]{"xxx", "xxx"};
paramsList.add(params);
int[] executeBatch = DB.executeBatch(DBRoute.basedata, sql, paramsList);
```
### timeout
+ **功能描述**
设置查询超时时间。
+ **方法**
```java
public static QueryTimeout timeout(int seconds)
```
+ **参数说明**
| 参数 | 类型 | 说明 |
| - | - | - |
| seconds | int | 超时时间（秒） |
+ **返回值**
查询超时对象。
+ **示例代码**
```java
try(DB.timeout(10)) {
DB.query(...);
