# java-db

> java-db 使用文档：Db、Row、ActiveRecord、事务、SQL 模板与多数据源

## 检索入口

- [机器可读目录](https://java-db.io.nexus/ai/index.json): 页面标题、章节、摘要、原文地址、内容哈希和占位状态。
- [分段语料](https://java-db.io.nexus/ai/chunks.jsonl): 每行一个 JSON 对象，按正文标题分段，保留代码块。
- [完整正文](https://java-db.io.nexus/llms-full.txt): 所有页面原文。优先按章节或单页获取。
- [站点地图](https://java-db.io.nexus/sitemap.xml): HTML 页面入口。

回答时引用 url 字段；结合版本与验证范围，placeholder 表示短内容候选，不应当作完整实现。

## overview

- [本章完整正文](https://java-db.io.nexus/ai/chapters/overview.txt)
- [Db 工具类](https://java-db.io.nexus/ai/pages/00.md): toc 使用 java-db 库时，单数据源业务直接调用静态 Db ，复用 ActiveRecord 已初始化的默认配置，无需持有 DbPro 实例；JSONB 显式解析、命名数据源、事务边界和测试隔离见 PostgreSQL 业务实践 。 --- 基础使用 1. 常见用法 Db 类及其配套的 Row 类，提供了在 M
- [java‑db](https://java-db.io.nexus/ai/pages/01.md): 一个轻量级、零配置、支持多数据源、读写分离、SQL 模板管理、ActiveRecord ORM、批量操作、事务、统计等功能的 Java 数据库操作框架。 🚀 特性 - ✅ 支持 MySQL、PostgreSQL、Oracle、SQLite 等多种数据库 - ✅ 内置 Druid/HikariCP 连接池 - ✅ Ac
- [操作数据库入门示例](https://java-db.io.nexus/ai/pages/02.md): java-db 支持多种数据库,以 mysql 为例进行演示 mysql 添加测试数据 首先，我们创建一个表： 然后，我们随意插入几条记录： 连接 mysql 接下来，我们添加依赖项： 最后，我们编写测试代码： 这段代码使用 ActiveRecord 插件来连接 MySQL 数据库并执行查询。以下是每部分的详细解释： 
- [SQL 模板 (SqlTemplates)](https://java-db.io.nexus/ai/pages/03_SQL%20Template.md): toc 1. 简介 SqlTemplates 是一个强大且灵活的SQL管理工具，旨在将SQL语句从Java代码中分离出来，实现更清晰的代码结构和更便捷的SQL维护。它通过解析特定格式的 .sql 文件，将SQL语句加载到内存中，并允许通过唯一的ID进行调用。 该工具支持两种灵活的加载模式： 主文件模式 ：通过一个入口文
- [数据源配置与使用](https://java-db.io.nexus/ai/pages/04_%E6%95%B0%E6%8D%AE%E6%BA%90%E9%85%8D%E7%BD%AE%E4%B8%8E%E4%BD%BF%E7%94%A8.md): HikariCP java-db 为了支持 HikariCP 内置了 HikariCpPlugin,下面讲解一下 如何使用 HikariCP 引入依赖 在项目的 pom.xml 文件中，需要引入以下依赖库： 这里 java-db 提供了 ActiveRecordPlugin 的支持， postgresql 是 Post
- [ActiveRecord](https://java-db.io.nexus/ai/pages/05_ActiveRecordPlugin.md): 概述 ActiveRecord 是 JFinal-Plugins 最核心的组成部分之一，通过 ActiveRecord 来操作数据库，将极大地减少代码量，极大地提升开发效率。 ActiveRecord 模式的核心是：一个 Model 对象唯一对应数据库表中的一条记录，而对应关系依靠的是数据库表的主键值。 因此，Acti
- [Db 工具类](https://java-db.io.nexus/ai/pages/06_db%E5%B7%A5%E5%85%B7%E7%B1%BB%E5%9F%BA%E7%A1%80.md): toc 使用 java-db 库时，单数据源业务直接调用静态 Db ，复用 ActiveRecord 已初始化的默认配置，无需持有 DbPro 实例；JSONB 显式解析、命名数据源、事务边界和测试隔离见 PostgreSQL 业务实践 。 --- 基础使用 1. 常见用法 Db 类及其配套的 Row 类，提供了在 M
- [批量操作](https://java-db.io.nexus/ai/pages/07_db%E5%B7%A5%E5%85%B7%E7%B1%BB%E9%AB%98%E7%BA%A7.md): 批量操作方法 在实际开发中，批量操作能够显著提高数据库的处理效率，减少单条操作带来的性能开销。本文将以 Java-db 框架中的 Db 类为例，详细介绍批量操作的使用方法，包括批量保存和批量更新。 类名： Db.java 方法签名 参数说明 1. sql ：指的是 INSERT INTO 或 UPDATE 语句。动态参
- [Model](https://java-db.io.nexus/ai/pages/08_Model.md): 1、基本用法 Model 是 ActiveRecord 中最重要的组件之一，它充当 MVC 模式中的 Model 部分。以下是 Model 定义示例代码： 以上代码中的 User 通过继承 Model，便立即拥有的众多方便的操作数据库的方法。在 User 中声明的 dao 静态对象是为了方便查询操作而定义的，该对象并不
- [Model生成器](https://java-db.io.nexus/ai/pages/09_%E7%94%9F%E6%88%90%E5%99%A8%E4%B8%8E%20JavaBean.md): 本文档介绍了如何使用 ActiveRecord 模块下的 Generator 工具类，自动生成 JavaBean 相关的 Model 、 BaseModel 、 MappingKit 、 DataDictionary 四类文件。通过生成器，可以快速创建符合 JavaBean 规范的模型类，提升开发效率和代码质量。 1.
- [注解](https://java-db.io.nexus/ai/pages/10.md): 本文档介绍了如何通过 Java 注解的方式操作数据库表 amazon product variant example table，实现数据的增删改查。我们将使用 JavaDb 框架中的 ActiveRecord 模块，并借助注解来简化数据库操作。 java-db 核心特性说明. - 驼峰命名映射 Java 属性如hiR
- [异常处理](https://java-db.io.nexus/ai/pages/11_%E5%BC%82%E5%B8%B8%E5%A4%84%E7%90%86.md): toc ActiveRecordException --- 1、背景简介 在使用 Java-DB（即 LitongJava ActiveRecord 框架）操作数据库时，当执行增删改查操作失败，框架会抛出 ActiveRecordException 。出于安全考虑，该异常默认不会将完整的 SQL 语句及参数打印到控制台
- [数据库事务处理](https://java-db.io.nexus/ai/pages/12_%E6%95%B0%E6%8D%AE%E5%BA%93%E4%BA%8B%E5%8A%A1%E5%A4%84%E7%90%86.md): 在现代应用开发中，确保数据的完整性和一致性至关重要。数据库事务（Transaction）是实现这一目标的核心机制。它将一系列数据库操作捆绑成一个不可分割的逻辑工作单元，确保这些操作要么全部成功执行，要么在出现任何错误时全部回滚，使数据恢复到操作前的状态。 本文将详细介绍 ActiveRecord 框架中支持的三种主流事
- [Cache 缓存](https://java-db.io.nexus/ai/pages/13_Cache%20%E7%BC%93%E5%AD%98.md): 1、使用 Ehcache 缓存 ActiveRecord 可以使用缓存以大大提高性能，默认的缓存实现是 ehcache，使用时需要引入 ehcache 的 jar 包及其配置文件，以下代码是 Cache 使用示例： 上例 findByCache 方法中的 cacheName 需要在 ehcache.xml 中配置如： 
- [Dialect 多数据库支持](https://java-db.io.nexus/ai/pages/14_Dialect%E5%A4%9A%E6%95%B0%E6%8D%AE%E5%BA%93%E6%94%AF%E6%8C%81.md): 目前 ActiveRecordPlugin 提供了 MysqlDialect、OracleDialect、PostgresqlDialect、SqlServerDialect、Sqlite3Dialect、AnsiSqlDialect 实现类。MysqlDialect 与 OracleDialect 分别实现对 Mys
- [表关联操作](https://java-db.io.nexus/ai/pages/15_%E8%A1%A8%E5%85%B3%E8%81%94%E6%93%8D%E4%BD%9C.md): ActiveRecord 天然支持表关联操作，并不需要学习新的东西，此为无招胜有招。表关联操作主要有两种方式：一是直接使用 sql 得到关联数据；二是在 Model 中添加获取关联数据的方法。 假定现有两张数据库表：user、blog，并且 user 到 blog 是一对多关系，blog 表中使用 user id 关联
- [复合主键](https://java-db.io.nexus/ai/pages/16_%E5%A4%8D%E5%90%88%E4%B8%BB%E9%94%AE.md): ActiveRecord 采用极简设计支持复合主键，对于 Model 来说需要在映射时指定复合主键名称，以下是具体例子： 如上代码所示，对于 Model 来说，只需要在添加 Model 映射时指定复合主键名称即可开始使用复合主键，在后续的操作中 JFinal 会对复合主键支持的个数进行检测，当复合主键数量不正确时会报异
- [Oracle 支持](https://java-db.io.nexus/ai/pages/17_Oracle%E6%94%AF%E6%8C%81.md): Oracle 数据库具有一定的特殊性，JFinal 针对这些特殊性进行了一些额外的支持以方便广大的 Oracle 使用者。以下是一个完整的 Oracle 配置示例： 由于 Oracle 数据库会自动将属性名(字段名)转换成大写，所以需要手动指定主键名为大写，如：arp.addMaping(“user”, “ID”, U
- [Enjoy SQL 模板](https://java-db.io.nexus/ai/pages/18_Enjoy%20SQL%20%E6%A8%A1%E6%9D%BF.md): JFinal 利用自带的 Enjoy Template Engine 极为简洁的实现了 Sql 模板管理功能。一如既往的极简设计，仅有 sql、 para、 namespace 三个指令，学习成本依然低到极致。 重要：除了以上三个 sql 管理专用指令以外，jfinal 模板引擎的所有指令和功能也可以用在 sql 管理
- [整合 Enjoy 模板最佳实践](https://java-db.io.nexus/ai/pages/19_%E6%95%B4%E5%90%88%20Enjoy%20%E6%A8%A1%E6%9D%BF%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5.md): 简介 在 Java 应用程序中整合 Enjoy 模板引擎 ，特别是在处理数据库操作和 SQL 文件管理方面，可以显著提高开发效率并增强代码的可维护性。本指南将详细介绍如何配置数据库连接、添加和管理 SQL 文件，以及通过模板引擎执行查询测试。 整合优势 - 统一管理 SQL 文件 ：使用 Enjoy 模板引擎，您可以将
- [多数据源支持](https://java-db.io.nexus/ai/pages/20_%E5%A4%9A%E6%95%B0%E6%8D%AE%E6%BA%90%E6%94%AF%E6%8C%81.md): ActiveRecordPlugin 可同时支持多数据源、多方言、多缓存、多事务级别等特性，对每个 ActiveRecordPlugin 可进行彼此独立的配置。简言之 JFinal 可以同时使用多数据源，并且可以针对这多个数据源配置独立的方言、缓存、事务级别等。 当使用多数据源时，只需要对每个 ActiveRecord
- [独立使用 ActiveRecord](https://java-db.io.nexus/ai/pages/21_%E7%8B%AC%E7%AB%8B%E4%BD%BF%E7%94%A8%20ActiveRecord.md): ActiveRecordPlugin 可以独立于 java web 环境运行在任何普通的 java 程序中，使用方式极度简单，相对于 web 项目只需要手动调用一下其 start() 方法即可立即使用。以下是代码示例： 注意：ActiveRecordPlugin 所依赖的其它插件也必须手动调用一下 start()方法，
- [调用存储过程](https://java-db.io.nexus/ai/pages/22_%E8%B0%83%E7%94%A8%E5%AD%98%E5%82%A8%E8%BF%87%E7%A8%8B.md): 使用工具类 Db 可以很方便调用存储过程，以下是代码示例： 如上所示，使用 Db.execute(...) 可以很方便去调用存储过程，其中的 connection 是一个 Connection 类型的对象，该对象在使用完以后，不必 close()，因为 jfinal 在上层会默认帮 close() 掉。 此外，MySQ
- [java-db 整合 Guava 的 Striped 锁优化](https://java-db.io.nexus/ai/pages/23.md): 在现代高并发应用中，确保数据的一致性和线程安全性是至关重要的。本文将详细介绍如何使用 Guava 库提供的 Striped 锁机制来优化 Java 应用中的并发控制。通过一个具体的业务案例，展示 Striped 锁在实际应用中的优势和实现方法。 业务背景 假设我们有一个系统，用于处理教授的学生评论数据，并生成对应的汇总
- [生成 SQL](https://java-db.io.nexus/ai/pages/24.md): 生成创表 SQL 定义实体类 生成创表 SQL output
- [通过实体类操作数据库](https://java-db.io.nexus/ai/pages/25.md): 保存 创建实体类 使用 Db 类保存数据 布尔字段映射 Db.findFirst(Entity.class, sql, args) 和 Row.toBean(Entity.class) 使用默认实体转换器。Java 字段使用驼峰命名，SQL 列使用下划线命名即可自动对应。 - PostgreSQL 原生 boolean
- [java-db 读写分离](https://java-db.io.nexus/ai/pages/26.md): java-db 的 Db 工具类内置了读写分离功能。未处于默认数据源事务中时，自动读路由选择读数据源；默认数据源事务中，自动读路由固定使用主库的事务连接，以保证读取本事务写入的数据及行锁有效。写操作使用写数据源。 - 当调用 Db.find 、 Db.query 、 Db.paginate 等方法时，系统会自动执行读操
- [Spring Boot 整合 Java-DB](https://java-db.io.nexus/ai/pages/27.md): 整合 ActiveRecord 操作关系型数据库 Spring Boot 整合 Java-DB 有两种方式： 1. 方式 1：不使用 Spring Boot，自行创建数据源并配置到 ActiveRecordPlugin 中 2. 方式 2：使用 Spring Boot 的数据源，并将 ActiveRecordPlugi
- [like 查询](https://java-db.io.nexus/ai/pages/28.md): LIKE 查询是 SQL 中用于执行模糊匹配的重要操作符，常用于在 WHERE 子句中查找符合特定模式的记录。以下是关于如何进行 LIKE 查询的详细介绍，包括其基本用法、常见场景以及在 Java 中的实现示例。 1. 基本语法 - column name ：要进行匹配的列。 - pattern ：用于匹配的模式，可以
- [常用操作示例](https://java-db.io.nexus/ai/pages/29.md): 查询 in 语句查询示例 in 查询 - 查询的表是 professor,查询的字段是 id - 使用 java 的 stream 语法拼接 生成的 sql 语句和参数 从 row 中获取记录 使用 findIn 方法 updateById 根据 id 值更新 ENOTE USER DEVICES 表中的 mac ad
- [Druid 监控集成指南](https://java-db.io.nexus/ai/pages/30.md): toc --- 一、前置依赖 在项目的构建文件（如 Maven 的 pom.xml ）中添加 Druid 和数据库驱动依赖： - Druid ：提供高性能 JDBC 连接池、慢 SQL 日志、Web 监控等功能。 - 数据库驱动 ：根据实际使用的关系型数据库选择对应驱动。 --- 二、配置 Druid 连接池与过滤器 
- [SQL 统计](https://java-db.io.nexus/ai/pages/31.md): 简介 Java db 内置了 LiteSqlStatementStat 用于进行 SQL 统计 使用 使用 LiteSqlStatementStat 进行 SQL 统计 本文介绍了如何在 Java 应用中使用 LiteSqlStatementStat 进行 SQL 统计，并展示了相关配置、测试和输出结果。 1. 配置类
- [Db 与 PostgreSQL 业务实践](https://java-db.io.nexus/ai/pages/32.md): 本章介绍 java-db 的静态 Db、JSONB 和事务用法，以及与 tio-boot-admin 的集成方式。使用 java-db 库时，单数据源业务直接使用 nexus.io.db.activerecord.Db ，无需在 Store/Service 中持有或注入 DbPro。这是 java-db 的使用方式，不
- [支付回执与权益事务](https://java-db.io.nexus/ai/pages/33_%E6%94%AF%E4%BB%98%E5%9B%9E%E6%89%A7%E4%B8%8E%E6%9D%83%E7%9B%8A%E4%BA%8B%E5%8A%A1.md): java-db 的线程绑定连接让收款事实、权益批次和原操作结果可以在同一短事务中提交。结合数据库唯一约束和行锁，可以同时处理重复回执、并发通知和返回丢失。 区分三个事实 发起付款、核明实际收款、实际权益交付分别建模。提交付款请求后发生超时，保留原请求号并查询原请求；页面成功提示不能作为收款依据。回执先完成验签、商户作用
- [商业库存与按量履约事务](https://java-db.io.nexus/ai/pages/34_%E5%95%86%E4%B8%9A%E5%BA%93%E5%AD%98%E4%B8%8E%E6%8C%89%E9%87%8F%E5%B1%A5%E7%BA%A6%E4%BA%8B%E5%8A%A1.md): java-db 的线程绑定事务适合将原操作、库存分配、权益扣量和累计交付金额一起提交。数据库负责并发互斥，服务端负责当前资格与计量证据，客户端展示已经确认的事实。 请求、预占与交付分开 用户确认使用时，将选中批次的可用量转入预占量，不增加已用量。排队只决定等待顺序；只有独占位置真实可用，才形成开始含、结束不含的服务区间
- [会员周期与独立增量池](https://java-db.io.nexus/ai/pages/35_%E4%BC%9A%E5%91%98%E5%91%A8%E6%9C%9F%E4%B8%8E%E7%8B%AC%E7%AB%8B%E5%A2%9E%E9%87%8F%E6%B1%A0.md): java-db 的线程绑定事务可以将业务原操作、周期额度和结果引用原子提交；PostgreSQL 唯一约束及条件更新负责最后一个单位的并发互斥。会籍按固定期限计算，额度按业务时区自然日/月计算，二者分别建模，可以清楚解释续费、升级和实际剩余。 会籍和额度分别记录 会籍表达账号在哪个区间享有什么承诺；额度表达责任账号在某
- [java-db](https://java-db.io.nexus/ai/pages/index.md): 下列条目提供数据库文档导航。 文件清单 - 00.md : 文档《Db 工具类》。 - 01.md : 文档《java‑db》。 - 02.md : 文档《操作数据库入门示例》。 - 03 SQL Template.md : 文档《SQL 模板 ( SqlTemplates )》。 - 04 数据源配置与使用.md :
- [查询资源自动管理](https://java-db.io.nexus/ai/pages/query-resources.md): 结果集、语句和连接 DbPro.queryListBytes 、SQL 查询形式的 find 、按 Row 条件查询的 find 和 findByField 在每次调用中管理自己创建的 JDBC 语句与结果集。返回的是已经读取完成的数据，调用方不需要关闭返回的列表。 queryListBytes 面向单列二进制结果，每
- [Row 展示转换与表格导出](https://java-db.io.nexus/ai/pages/row-presentation.md): 转换为 Kv RowUtils.toKv 创建新的 Kv，并将顶层 Long 和 BigInteger 转为字符串，方便展示较大的整数。传入 true 时，将字段名从下划线形式转换为驼峰形式。原始 Row 中的值和类型保持不变。 例如 user id 为 Long 时，结果的 userId 是字符串，而原 Row 的