# sqlhelper **Repository Path**: coderjn/sqlhelper ## Basic Information - **Project Name**: sqlhelper - **Description**: SQL开发、测试工具套件（分页、动态数据源、批处理、DDL等）其中分页支持MyBatis，SpringJDBC，commons-dbutils, jfinal, ebean, mango等 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: dev_6.x - **Homepage**: https://github.com/fangjinuo/sqlhelper - **GVP Project**: No ## Statistics - **Stars**: 77 - **Forks**: 16 - **Created**: 2019-07-30 - **Last Updated**: 2026-11-09 ## Categories & Tags **Categories**: database-dev **Tags**: None ## README [![License](https://img.shields.io/badge/license-Apache2.0-green.svg)](https://github.com/fangjinuo/sqlhelper/blob/master/LICENSE) [![Build Status](https://www.travis-ci.org/fangjinuo/sqlhelper.svg?branch=master)](https://travis-ci.org/fangjinuo/sqlhelper) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/9c27e94ffa3a4ee58279c36236b2b075)](https://www.codacy.com/manual/fs1194361820/sqlhelper?utm_source=github.com&utm_medium=referral&utm_content=fangjinuo/sqlhelper&utm_campaign=Badge_Grade) [![JDK](https://img.shields.io/badge/JDK-1.6+-green.svg)](https://www.oracle.com/technetwork/java/javase/downloads/index.html) [![MyBatis](https://img.shields.io/badge/MyBatis-3.x-green.svg)](http://www.mybatis.org/mybatis-3/index.html) [![MyBatis](https://img.shields.io/badge/MyBatisPlus-3.x-green.svg)](http://www.mybatis.org/mybatisplus-3/index.html) [![jFinal](https://img.shields.io/badge/jFinal-3.x-green.svg)](https://github.com/jfinal/jfinal) [![jFinal](https://img.shields.io/badge/jFinal-4.x-green.svg)](https://github.com/jfinal/jfinal) [![EBean](https://img.shields.io/badge/Ebean-11.x-green.svg)](https://ebean.io/docs/query/sqlquery) [![Mango](https://img.shields.io/badge/Mango-1.6.x-green.svg)](https://github.com/jfaster/mango) [![Commons-DBUtils](https://img.shields.io/badge/Apache_Commons_DBUtils-1.7.x-green.svg)](http://commons.apache.org/proper/commons-dbutils/index.html) [![Solon](https://img.shields.io/badge/solon-1.x-green.svg)](https://github.com/noear/solon) [![Spring-Jdbc](https://img.shields.io/badge/SpringJdbc-2.x-green.svg)](https://spring.io/projects/spring-framework) [![Spring-Jdbc](https://img.shields.io/badge/SpringJdbc-3.x-green.svg)](https://spring.io/projects/spring-framework) [![Spring-Jdbc](https://img.shields.io/badge/SpringJdbc-4.x-green.svg)](https://spring.io/projects/spring-framework) [![Spring-Jdbc](https://img.shields.io/badge/SpringJdbc-5.x-green.svg)](https://spring.io/projects/spring-framework) [![SpringBoot](https://img.shields.io/badge/SpringBoot-1.x-green.svg)](https://spring.io/projects/spring-boot/) [![SpringBoot](https://img.shields.io/badge/SpringBoot-2.x-green.svg)](https://spring.io/projects/spring-boot/) [![maven](https://img.shields.io/badge/maven-v6.0.5-green.svg)](https://search.maven.org/search?q=g:com.github.fangjinuo.sqlhelper%20AND%20v:6.0.5) ## [GitHub地址](https://github.com/fangjinuo) ## [Gitee地址](https://gitee.com/fangjinuo) ## [教程](./.wiki/index.md) # sqlhelper SQL Tools ( **Dialect**, **Pagination**, **DDL Dump**, **UrlParser**, **SqlStatementParser**, **WallFilter**) based Java ## modules | module | sqlhelper version | JDK | framework version| Description | |------------------|-------------------|-----|------------------|------------------| |sqlhelper-dialect | 1.0+ |1.6+ | |the core （绝大部分功能都离不开它）| |sqlhelper-mybatis | 1.0+ |1.6+ | |提供对MyBatis的支持 (主要包括：通用分页、通用批量操作) | |sqlhelper-mybatis-spring-boot | 1.0+ |1.6+ | | 为MyBatis + SqlHelper 提供了Spring Boot 快速启动| |sqlhelper-mybatis-over-pagehelper|1.0+|1.6+ | | 引入它就可以无缝的从 ***mybatis-pagehelper*** 迁移到 SqlHelper| |sqlhelper-jfinal | 1.2+ |1.6+ |4.3+ | 对国产框架jfinal支持 (主要包括：通用分页) | |sqlhelper-ebean | 1.2+ |1.6+ | | 对 ebean 支持(主要包括：通用分页) | |sqlhelper-hibernate| 1.2+ |1.6+ | | 对 hibernate 支持(主要包括：通用分页) | |sqlhelper-mango | 1.2+ |1.6+ | | 对 mango 支持 支持(主要包括：通用分页) | |sqlhelper-springjdbc | 2.0.2+ |1.6+ |spring 4.0+ | 对 spring-jdbc 支持 (主要包括：通用分页)| |sqlhelper-springjdbc-spring-booter| 2.0.2+|1.8+| |对 spring-jdbc 应用提供了 Spring Boot 快速启动| |sqlhelper-mybatisplus-3|2.0.7+ |1.8+ | mybatis-plus 3.2.0+ |对 mybatis-plus 支持| |sqlhelper-mybatisplus-spring-boot-starter|2.0.7+ |1.8+ |mybatis-plus 3.1.2+ |对 mybatis-plus 应用提供了 Spring Boot 快速启动| |sqlhelper-mybatisplus-2|3.3.0+ |1.6+ | mybatis-plus 3.2.0+ |对 mybatis-plus 支持| |sqlhelper-mybatisplus_2x-spring-boot-starter|2.0.7+ |1.6+ |mybatis-plus 3.1.2+ |对 mybatis-plus 应用提供了 Spring Boot 快速启动| |sqlhelper-mybatisplus-mapper|6.1.0+ |17+ |mybatis-plus 3.5.4+ |基于 mybatis-plus BaseMapper 的唯一 Mapper 基接口 IBaseMapper，提供实体表与关系表的全部能力：IBaseMapper 把读取与删除条件从 Wrapper 收窄到 LambdaQueryWrapper（列表、分页、单条、计数、存在性、删除，以及 Map / 单列结果；只有 update 两个重载沿用 mybatis-plus 原生 Wrapper 签名，不设窄签名也不设桩，代价是这两行的列名没有编译期保障）——被收窄的那几行 Wrapper 宽签名标注 @Deprecated 并抛 UnsupportedOperationException，另以同名窄签名重载提供唯一入口（selectList×3 / selectOne×2 / selectFirstOne / selectPage / delete），窄签名直接复用 mybatis-plus 注入的语句；分页用 selectPage(IPage, LambdaQueryWrapper)（自定义语句把 IPage 作为方法参数），经 sqlhelper-mybatisplus 的 extractor / result adapter 双向适配到 sqlhelper 分页插件；两类表的全部写入入口都在 TableMappers：update-or-insert 用 TableMappers#save(mapper, entity)（方言支持 insert-conflict 时走原子 upsert），先查后写用 TableMappers#insertOrUpdate(mapper, entity)，幂等插入用 TableMappers#insertIfAbsent(mapper, entity)，关系表按多组复合键批量删除用 TableMappers#deleteByCompositeKeys(mapper, entities)。实体表方言支持 insert-conflict 时由 SqlHelperMybatisSqlInjector 生成单条原子 upsert，不支持时 save / insertOrUpdate 自动退化为 selectById + insert/updateById（先查后写）；关系表按 @CompositePrimaryKey 声明的业务唯一键处理：方言支持时 save 走原子 upsert，不支持时退化为按复合键先查后写（insertOrUpdate）；insertIfAbsent 支持 insert-if-absent 时走单条语句，不支持时先查后插（实体表 selectById、关系表按复合键 selectCount），冲突时不覆盖；另有 selectList 的 ResultHandler 窄签名（流式逐行回调，适合大结果集导出）；Spring Boot 下由自动配置装配（方言优先取 Dialect bean 或 sqlhelper-mybatis 插件的 sqlhelper.mybatis.instrumentor.dialect，未配置时在 mapper 解析阶段按 MyBatis databaseId / 数据源元数据自动识别，与分页插件的检测机制一致；已有自定义 SqlInjector 时按 mapper 类型分流（IBaseMapper 子接口交给本模块注入器，其它 mapper 继续用原注入器，原方法不丢）；sqlhelper.mybatisplus-mapper.enabled=false 可关闭）；启动期强制约束（mapper 解析阶段，违反即启动失败）：每个 IBaseMapper 的 PO 必须用 @TableId(type = IdType.INPUT) 声明单主键，或用 @CompositePrimaryKey({"a","b"}) 声明联合业务唯一键（冲突列取该注解），两者都没有直接抛 UnsupportedPOException；同一实体不能同时使用 @TableId 与 @CompositePrimaryKey，@CompositePrimaryKey 的属性名也会在启动期校验；insert 不要求表有数据库主键（用 @CompositePrimaryKey 表达业务唯一键即可），IBaseMapper 的 insert 按表类型分流（实体表自动补主键、关系表校验复合键），TableMappers.insertIfAbsent / insertOrUpdate / save / deleteByCompositeKeys 要求表有主键或声明了 @CompositePrimaryKey（两者都没有抛 UnsupportedPOException）；写入口主键缺失时自动生成——String 用 langx 的 SparkId、Long 用雪花（worker/datacenter 由 langx provider 解析）、UUID 用 langx 的 UUIDv7，其它类型抛 IllegalArgumentException；禁用全部 Map 参数方法、弱类型结果的宽签名（selectMaps / selectMapsPage / selectObjs 的 Wrapper 版本——Map 与单列结果本身不禁，已提供 LambdaQueryWrapper 窄签名，聚合统计走 TableMappers.selectAggregate，SELECT 里的列名全部由方法引用解析生成）与链式 Wrapper 的 list/one/page/count/remove（只有 update() 落在未被拦截的原生签名上，仍可用）），其它 SQL 写在 XML| |sqlhelper-tkmapper-spring-boot-starterer|3.1.0+ |1.8+ | |对 tk.mybatis Mapper 应用提供了 Spring Boot 快速启动| |sqlhelper-dbutils | 2.2.0 |1.6+| |对 Apache Commons-DBUtils 支持 (主要包括：通用分页) | |sqlhelper-jsqlparser | 3.0.3 |1.6+| |对于要基于SQL Parser接口来完成的功能 由jsqlparser 这个库来实现| |sqlhelper-mybatis-solon-plugin|3.2.0|1.8+| |支持solon 框架| |sqlhelper-mybatis-spring-common|3.4.0|1.6+||提供mybatis + spring 环境下，通用的代码| |sqlhelper-examples|1.0+ |1.8+ | |为这些工具提供 **测试用例** | ## tools usage ### 关键特性 1. 支持 MyBatis, MyBatis-Plus, Tk.Mapper, SpringJdbc, Apache Commons-DBUtils, JFinal, EBean, Mango, Hibernate 等众多对数据库操作的框架 2. 支持 130+ 数据库（所有功能均支持，不限于分页功能）, 支持的数据库列表参考： ***[here](https://github.com/f1194361820/sqlhelper/wiki/Pagination_Database)***. 如果你想了解这些数据库的排名，可以参考这里：[DB Engines](https://db-engines.com/en/ranking/relational+dbms).下面是所有支持的国产数据库: + AliSQL (阿里 MySQL) + AntDB (亚信) + CirroDB (东方国信 行云) + CynosDB (腾讯云数据库) + Doris (Apache Doris，百度研发) + DM (达梦) + EsgynDB (易鲸捷) + GaussDB (华为 高斯) + GBase (南大通用) + GoldenDB (中兴) + HHDB (恒辉数据库) + HighGo (瀚高) + HybridDB (阿里巴巴 分布式PostgreSQL) + K-DB (浪潮) + KingBase (金仓) + MaxCompute (阿里巴巴) + OBase (上海丛云信息科技) + OceanBase (阿里巴巴/蚂蚁金服 兼容mysql) + OSCAR (神州通用) + OpenBase (东软) + RadonDB (青云) + SequoiaDB (巨杉) + SinoDB (星瑞格) + TDSQL (腾讯 分布式MySQL) + TiDB (北京平凯星辰科技)) + Trafodion (易鲸捷 EsgynDB的开源版) + UxDB (优炫数据库) 3. 支持多个数据库在同一个应用中并存，且不需要做任何的区分，就能自动识别 4. 支持自动获取数据库 dialect （方言），也可以指定 5. 性能要比**Mybatis-PageHelper**更高, 因为SQL中的 limit、offset 会以占位符 '?'的形式存在，支持缓存等，总之PageHelper支持的这里都支持，PageHelper不支持的这里也支持。 6. 对于 select count语句，会自动的排除掉 order by 子句，以提升查询效率 7. 可以基于 Java SPI 规范来自定义Dialect，以此来扩展数据库 8. 分页功能支持**子查询**：mybatis, mybatis-plus, spring-jdbc, apache commons-dbutils 9. 支持 spring boot 1.x , 2.x 10. 支持 JDK6+ 11. 支持 **Memory Pagination** 12. 支持 SqlSymbolMapper, 可以使用它来自动映射数据库字段、表名等 13. 支持 **Dump DDL** 14. 支持 **like parameter escape [%]** : mybatis, mybatis-plus, tk.mapper 下使用 #### sqlhelper vs mybatis-pagehelper | metric | mybatis-pagehelper | sqlhelper | |--------------------------|:------------------:|:-----------------:| | databases | 13 | 100+ | | multiple databases in runtime | √ | √ | | auto detect dialect | √ | √ | | plugin | √ | √ | | PrepareStatement with '?'| X | √ | | mybatis | 3.x | 3.x | | spring boot | 1.x, 2.x | 1.x, 2.x | | JDK | 1.6+ | 1.6+ | | jFinal | X | √ | | Mango | X | √ | | EBean | X | √ | | 国产数据库 | X | √ （参见上述列表） | | Spring JDBC | X | √ 2.x,3.x,4.x,5.x | | SqlSymbol Mapping | X | √ | | MyBatis-Plus | X | √ | | tk.mapper | √ | √ | | Apache Commons-DBUtils | X | √ | | Subquery pagination | X | √ | | solon | X | √ | # 分页工具使用说明 * [Quick Start](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart) + [MyBatis application](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_MyBatis) - [Installation](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_MyBatis) - [How To](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_MyBatis) - [Migrate from mybatis-pagehelper application](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_MyBatis) + [SpringJDBC application](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_SpringJDBC) - [Installation](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_SpringJDBC) - [How To](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_SpringJDBC) + [jFinal application](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_jFinal) - [Installation](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_jFinal) - [How To](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_jFinal) + [MyBatis-Plus application](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_MyBatis_Plus) + [EBean application](https://github.com/fangjinuo/sqlhelper/wiki/Pagination_QuickStart_ebean) * Advanced Usage 更多说明，参见教程： ```html 1. https://fangjinuo.gitee.io/docs/index.html 2. https://fangjinuo.github.io ``` # UrlParser Parse jdbc url. ## usage: 
String url = "jdbc:mysql://${localhost}:${port}....";
DatabaseInfo dbinfo = new JdbcUrlParser().parse(url)
...
# [FAQ](https://github.com/fangjinuo/sqlhelper/wiki/FAQ) 这里提供了一些常见问题，对于刚使用SQLHelper时，可能对你很有帮助 # Contact QQ 交流群: 750929088 ![QQ Group](https://github.com/fangjinuo/sqlhelper/blob/master/_images/qq_group.png) ## [推广](https://github.com/fangjinuo) + langx 系列 - [langx-js](https://github.com/fangjinuo/langx-js)：TypeScript, JavaScript tools - [langx-java](https://github.com/fangjinuo/langx-java): Java tools ，可以替换guava, apache commons-lang,io, hu-tool等 + [easyjson](https://github.com/fangjinuo/easyjson): 一个通用的JSON库门面，可以无缝的在各个JSON库之间切换，就像slf4j那样。 + [sqlhelper](https://github.com/fangjinuo/sqlhelper): SQL工具套件（通用分页、DDL Dump、SQLParser、URL Parser、批量操作工具等）。 + [esmvc](https://github.com/fangjinuo/es-mvc): ElasticSearch 通用客户端，就像MyBatis Mapper那样顺滑 + [agileway](https://github.com/fangjinuo/agileway): 提供大量的框架扩展，方便日常开发 + [audit](https://github.com/fangjinuo/audit)：通用的Java应用审计框架 ## 鸣谢 最后，感谢 Jetbrains 提供免费License，方便了开源项目的发展。 [![Jetbrains](https://github.com/fangjinuo/sqlhelper/blob/master/_images/jetbrains.png)](https://www.jetbrains.com/zh-cn/)