整合数据库
tio-boot-admin 通过 TioAdminDbConfiguration 初始化 Hikari 连接池和 java-db 的 ActiveRecord 插件。初始化完成后，业务代码直接使用静态 nexus.io.db.activerecord.Db，无需重新创建连接池或保存默认 DbPro 实例。
本章以 PostgreSQL 为例。管理员表及 ApiTable 元数据的初始化见 手动初始化数据库，初始化 SQL 由用户手动执行。
1. 添加 JDBC 驱动
在已有 tio-boot-admin 工程的 pom.xml 中声明 PostgreSQL 驱动；已经声明时无需重复添加：
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>42.5.0</version>
</dependency>
java-db 由框架依赖引入，应用应保持依赖一致，避免同时引入不同来源的 ActiveRecord 实现。完整工程配置见 入门指南。
2. 配置连接
app.properties 选择开发环境：
app.env=dev
app-dev.properties：
jdbc.url=jdbc:postgresql://127.0.0.1:5432/exampledb
jdbc.user=postgres
jdbc.MaximumPoolSize=5
jdbc.showSql=false
密码通过本地秘密配置提供，例如启动工作目录的 .env：
jdbc.pswd=replace-with-your-password
不要提交真实密码。数据库 exampledb 需要提前创建，应用使用的账号应具备相应连接和业务表访问权限。
| 配置项 | 含义与默认行为 |
|---|---|
jdbc.url | JDBC 地址；未配置时跳过数据库初始化，空字符串不表示关闭 |
jdbc.user | 数据库用户名 |
jdbc.pswd | 数据库密码 |
jdbc.MaximumPoolSize | 连接池最大连接数，默认 2；注意配置名大小写 |
jdbc.showSql | 是否输出 SQL，默认 false |
jdbc.connectionInitSql | 可选，创建连接后执行的 SQL，例如设置 schema；不是建表或数据迁移入口 |
只有需要指定 schema 时才添加：
jdbc.connectionInitSql=SET search_path TO public
3. 调用内置配置
在已有 AdminAppConfig.config() 中保留一次调用：
new TioAdminDbConfiguration().config();
配置类的完整类型是 nexus.io.tio.boot.admin.config.TioAdminDbConfiguration。不要在不同配置类中重复调用，也不要再手工启动一个使用相同数据库的默认 ActiveRecord 插件。
内置配置负责：
- 读取连接配置，创建 Hikari 数据源并注册到
DsContainer。 - 创建并启动 ActiveRecord 插件，配置 SQL 输出及开发模式。
- 根据连接地址为 PostgreSQL 或 SQLite 选择对应方言。
- 注册应用关闭时的插件停止和连接池关闭钩子。
它不会执行业务建表 SQL、创建管理员或重置密码。连接配置完成后，仍需按项目要求手动初始化表结构。
4. 使用静态 Db 查询
下面的查询不依赖业务表，可以用于检查数据库连接及参数绑定：
import com.jfinal.kit.Kv;
import nexus.io.db.activerecord.Db;
import nexus.io.model.body.RespBodyVo;
public class DatabaseService {
public RespBodyVo check() {
Kv result = Db.findFirstMap(
"select current_database() as database_name, cast(? as integer) as value",
new String[0], 1);
return RespBodyVo.ok(result);
}
}
findFirstMap 返回 Kv，第二个参数是需要按 JSON 解析的列名列表，没有 JSON 列时传空数组。可使用 result.getStr("database_name")、result.getInt("value") 读取类型明确的值。SQL 参数使用 ? 绑定，不拼接用户输入。
在实际接口中，Handler 负责解析、校验 HTTP 参数，Service 负责查询和业务逻辑，Handler 最后通过 TioRequestContext.getResponse().respond(serviceResult) 输出结果。Service 等共享对象使用 Aop，配置类和 Handler 直接创建。
5. 事务和通用表接口
多条写操作需要一起成功或一起回滚时，使用 Db.txResult(...)。先接收事务结果，再通过 RespBodyVo.ok(result) 返回；需要回滚时抛出异常，不把失败隐藏为正常返回值。
Db 负责程序中的数据库操作；后台表格、表单等使用的 ApiTable 接口由以下配置注册：
new TioAdminControllerConfiguration().config();
数据库连接初始化不能代替 Controller 注册，也不能代替后台鉴权配置。完整职责见 配置职责与扩展边界，代码组织方式见 后端开发规范。
6. 常见问题
- 驱动类找不到：检查 PostgreSQL 驱动是否进入运行时依赖和最终 JAR。
- 连接被拒绝或超时：检查地址、端口、数据库服务以及网络访问规则。
- 认证失败：核对实际生效的用户名、密码及 PostgreSQL 认证规则，不把真实密码写入排错记录。
- 表不存在：确认已手动执行初始化 SQL，并核对数据库和 schema。
- Db 未初始化：确认
jdbc.url已加载，且数据库配置在业务调用之前完成。 - 连接池耗尽：检查长事务、慢查询和未释放的手工连接，再按并发需求调整连接数。