简介面向 Java 开发者的轻量级 Access 数据库驱动 ucanaaccess-4.0.4.jar可彻底绕开 Access_JDBC30.jar 的查询次数与条数限制。该开源库支持以 JDBC 直连方式读取 mdb 文件无需配置 ODBC 桥接稳定性与易用性更佳适合需要频繁、大批量操作 Access 数据的桌面或 Web 项目。压缩包共 16 个文件以 jar 核心组件与依赖库为主辅以 txt 协议/许可说明以及 bat、sh 控制台脚本整体约 2.57MB可快速集成到既有 Java 工程。使用方法与原 Access_JDBC30.jar 大同小异切换成本低内含 ucanaccess 主包、HSQLDB、Jackcess 等必要依赖并附带版本与版权说明。目前已有 736 人学习使用对于受困于旧驱动限制的开发者是一份即取即用的替代方案。1. 告别ODBC为什么Java读Access要先换ucanaccess-4.0.4某公司内部一直用JDBC-ODBC桥接读Access库换到64位JVM的机器上直接装不上驱动几万行Excel导出的活只能停在工位上干瞪眼。后来把驱动换成ucanaccess-4.0.4——一个纯Java的Access驱动jar包不依赖Windows注册表、不用装ODBC数据源跨平台直接读.mdb和.accdb才把这条线救回来。这篇笔记围绕这个jar包展开从驱动原理、连接串写法、参数调优到四个高频坑适合正好接手Access存量数据的Java开发者照着落地。2. 驱动原理与依赖拼装ucanaccess只是门口那块牌2.1 为什么Access的JDBC路径绕不开ucanaccessJava读Access的老路有三条JDBC-ODBC桥、第三方商业驱动、ucanaccess。JDBC-ODBC桥在JDK 8里已被移除官方文档写得很明白Oracle不再推荐也不维护这条链路。即便你还在用JDK 732位ODBC驱动和64位JVM之间的位数匹配问题也会随时翻车更不用说Windows之外的操作系统压根没有可用的ODBC数据源配置入口。商业驱动不是贵就是闭源内部工具用起来总觉得不踏实。ucanaccess能成为默认选择核心就一句话它把Access文件当成一个普通的嵌入式数据库来读路径上不需要任何平台相关组件。拆开看ucanaccess其实是站在两个开源库肩膀上的封装的产物底层用Jackcess直接按Access文件格式读写物理文件上层用HSQLDB的内存模式承担SQL解析和查询运算。你自己写程序时只需要面向JDBC接口驱动内部会做文件解析、类型映射、SQL翻译这几层工作。理解这个分层有个实际好处当你遇到查询慢或者类型对不上的问题时你至少能判断是哪一层出了问题而不是对着一个黑匣子乱试参数。比如查询性能问题大概率在HSQLDB中转层字段读出来类型不对大概率在Jackcess的映射层。2.2 依赖构成与文件清单在IDE里手动导入ucanaccess-4.0.4.jar只是第一步这个jar还依赖几个运行时库缺一个就会在Class.forName时报ClassNotFoundException。常见的做法是用Maven或者Gradle拉依赖让工具链自动把传递依赖带全。如果项目环境是离线内网需要手动收集这一整套jar下面的表格列清楚每一份是干什么的。jar文件作用是否可以省略ucanaccess-4.0.4.jarJDBC驱动主类连接串入口否jackcess-3.x.x.jarAccess文件物理层读写处理.mdb和.accdb否hsqldb-2.x.x.jar内存数据库引擎承载SQL解析与结果集缓存否commons-lang3、commons-logging、commons-io字符串、日志、流操作的基础工具库否缺少会报NoClassDefFoundErrorlog4j可选打印驱动内部日志排查文件锁和编码问题时有用可省但建议保留离线环境下最容易漏掉的是jackcess和hsqldb这两个因为你的代码里不会直接import它们的类少了只在运行时报错。第一次连库报ClassNotFound时别急着怀疑主jar先看是不是传递依赖没带全。手动收jar的时候还要注意版本匹配ucanaccess-4.0.4要求jackcess的版本不能太旧推荐一套能编译通过就锁死的版本组合不要混着升级。2.3 驱动注册与连接串构成ucanaccess遵循JDBC 4.0规范从4.x版本开始支持SPI自动注册驱动也就是说你不在代码里写Class.forName也能拿到连接。但为了排查方便我习惯在静态代码块里显式注册一次这样驱动加载失败时能看到明确的ClassNotFound异常而不是被吞掉。驱动类的全名是net.ucanaccess.jdbc.UcanaccessDriver。连接串的格式是jdbc:ucanaccess://文件绝对路径;参数1值;参数2值路径部分指向Access文件本身参数用分号拼接。最基础的连接串长这样String url jdbc:ucanaccess://D:/data/erp.mdb; Connection conn DriverManager.getConnection(url);getConnection不带用户名密码也可以因为Access文件本身通常没有账号体系。如果你的Access库设置了数据库密码就需要在连接串上挂jackcessOpener参数配合自定义的CryptCodecOpener实现来解密。这是一个后面会展开的大坑这里先记住连接串的骨架结构后续调优无非是在这个分号参数区里加开关。3. 落地实操从pom依赖到可跑的读写Demo3.1 Maven依赖与IDE导入Maven项目里加依赖是最省心的方式。在pom.xml里声明ucanaccess坐标传递依赖会一并拉取。需要注意的一点是ucanaccess的主包groupId用的是net.sf.ucanaccess不是com.ucanaccess写错了坐标会直接拉不到包。dependency groupIdnet.sf.ucanaccess/groupId artifactIducanaccess/artifactId version4.0.4/version /dependency这段坐标声明了主jar和三个关键传递依赖的入口。4.0.4版本对应的jackcess和hsqldb版本是固定的Maven会按POM里的依赖声明自动解析不需要你手动指定版本。如果是Gradle项目写法等价为implementation net.sf.ucanaccess:ucanaccess:4.0.4。加完依赖后先跑一个最简单的连接测试确认Class.forName能正常加载再往下走。IDEA或Eclipse导入jar包的方式这里不细说但有一个经验不要用IDE的“Add as Library”去导一个散装的jar目录直接用构建工具声明依赖换机器、打包的时候才不折腾。3.2 第一个查询把表拉成List连接建立后查询逻辑和操作普通JDBC数据库完全一致。下面的例子读取Access库里一张名为t_sku的表把前100行打印出来。注意这里指定了memorytrue参数让HSQLDB把工作区完全放在内存中查询速度更快。import java.sql.Connection; import java.sql.DriverManager; import java.sql.ResultSet; import java.sql.Statement; public class UcanaccessQueryDemo { public static void main(String[] args) throws Exception { // memorytrue 让HSQLDB在内存中完成查询中转小文件场景比disk模式快 String url jdbc:ucanaccess://D:/data/erp.mdb;memorytrue; try (Connection conn DriverManager.getConnection(url); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(SELECT * FROM t_sku LIMIT 100)) { while (rs.next()) { String code rs.getString(sku_code); String name rs.getString(sku_name); System.out.println(code - name); } } } }这段代码的逻辑是先通过DriverManager拿到连接创建Statement对象执行SQL查询最后在try-with-resources里自动关闭所有资源。注意SQL里使用了LIMIT 100这是标准SQL语法ucanaccess的HSQLDB引擎能识别但直接写SELECT * FROM t_sku配合stmt.setMaxRows(100)也是等效做法。参数说明上memorytrue适合库文件不大的场景查询全部在内存中完成如果Access文件有几百MB继续用内存模式会占掉大量JVM堆内存建议去掉这个参数让HSQLDB走磁盘模式。另外LIMIT在这条链路上被HSQLDB执行不会翻译成Access原生SQL所以你不需要担心源库是否支持LIMIT语法。3.3 增删改事务边界怎么控制ucanaccess的AutoCommit默认打开每一条INSERT或UPDATE都会直接落到Access文件上。大批量写入时逐条提交会巨慢正确做法是关闭自动提交手动分批次提交让Jackcess在内存中攒一批再写盘。下面示例演示了插入一批记录并手动控制事务边界。import java.sql.Connection; import java.sql.DriverManager; import java.sql.PreparedStatement; public class UcanaccessWriteDemo { public static void main(String[] args) throws Exception { String url jdbc:ucanaccess://D:/data/erp.mdb;memoryfalse; try (Connection conn DriverManager.getConnection(url)) { conn.setAutoCommit(false); // 关闭自动提交事务边界由手动控制 try (PreparedStatement ps conn.prepareStatement( INSERT INTO t_sku(sku_code, sku_name, qty) VALUES(?, ?, ?))) { for (int i 0; i 5000; i) { ps.setString(1, SKU i); ps.setString(2, 样品 i); ps.setInt(3, i * 2); ps.addBatch(); if (i % 500 0) { ps.executeBatch(); // 每500条执行一次批处理 conn.commit(); // 显式提交保证这批数据持久化 } } ps.executeBatch(); conn.commit(); } } } }这段代码的关键在于setAutoCommit(false)和addBatch()的组合。addBatch只是把SQL压到驱动内部的批量缓冲区真正执行是在executeBatch()持久化是在commit()。按500条一批提交是因为Jackcess写Access文件时每笔事务都有固定开销攒多了又容易让JVM堆占用偏高500是一个相对稳妥的中间值。如果你写的是几万行的数据迁移可以按2000条一批试观察GC和写入耗时再调整没有一个绝对最优值。注意这里如果发生异常conn.rollback()不会自动回滚已经物理写入的文件块因为Jackcess对.mdb的写操作机制比较原始先改索引再改数据进程中断时索引可能残留不一致状态。所以大批量写入前强烈建议先备份原始文件这是血泪经验。4. 参数调优把内存、乱码和列类型一次性校准4.1 内存开关与性能参数ucanaccess的连接串参数决定驱动内部行为改对了能解决一大部分“运行起来慢得没法用”的问题。下面是4.0.4版本里几个高频使用的参数我按照自己在项目中的使用优先级排列。参数可选值作用使用建议memorytrue/falseHSQLDB工作区放内存还是磁盘文件小于50MB用true大文件用falseshutdowntrue/false连接关闭时是否执行压缩与结构校验建议true能尽早暴露文件损坏问题keepMirrortrue/false是否保留HSQLDB内存镜像文件设为false可避免重复生成镜像singleConnectiontrue/false是否限制为单一连接多线程并发写时设为falseignoreCasetrue/false查询时是否忽略表名字段名大小写老库表名不一致时设为truejackcessOpener类名自定义Access文件打开方式处理加密库、自定编码时使用shutdowntrue这个参数值得单独说。它让驱动在连接关闭时对HSQLDB执行SHUTDOWN操作触发Access文件的结构校验和压缩检查。如果你经常遇到“程序正常退出后文件打不开”的问题多半是shutdown没开启缓冲区的数据没完全刷盘。代价是连接关闭时间会变长批量任务结束时多等几秒可以接受。4.2 中文乱码到底在哪一层修Access老库里的中文乱码通常有两种表现读出来全是“?”或“???”以及写进去再读就变乱码。前者一般发生在Access文件本身用非UTF-8编码存储的情况下后者则是Java的Unicode字符串和Access内部编码不一致导致的。ucanaccess默认按平台默认字符集来处理文件流如果你的项目跑在Linux上而Access文件是在Windows的GBK环境下建的读出来必乱。处理方法是给连接串加charSet参数显式告诉驱动文件编码格式。GBK编码的旧Access库按下面的方式连String url jdbc:ucanaccess://D:/data/erp.mdb;charSetGBK; Connection conn DriverManager.getConnection(url);有一种情况比乱码更隐蔽只有特定字段乱码其他字段正常。这通常不是驱动问题而是那个字段在Access里本身存的就是UTF-8内容其他字段是GBK内容。一个文件里混两种编码是无解的除非你先把源文件整体清洗一遍。我的习惯是先加charSetGBK试读如果还乱再用十六进制工具直接看几个字段的字节码确认到底是哪种编码不要反复换参数瞎试——乱码这类问题靠盲猜参数是玄学看字节码才靠谱。4.3 列类型映射与数字精度坑Access的自增主键AutoNumber在ucanaccess里读取时经常变成BigDecimal而不是Integer或Long。原因是Access的AUTOINCREMENT字段内部存储结构是NUMERIC类型Jackcess按数值精度映射时选了范围最大的BigDecimal。如果你在Java里面用rs.getInt(id)JDBC规范的getInt会自动做类型转换问题不大但如果你用rs.getObject(id)拿到Object再强转就会在这里翻车。另一个精度坑是Access的货币字段Currency映射到Java是BigDecimal小数保留4位。金额计算时千万不要用Double去接会有浮点误差。列类型映射整体规律可以参考下面的对应关系表。Access字段类型ucanaccess映射到Java类型建议的读取方式AutoNumberBigDecimalgetInt / getLong让JDBC自动转换CurrencyBigDecimal用getBigDecimal避免浮点误差TextStringgetString注意长度截断Memo长文本StringgetString注意是否有乱码Yes/NoBooleangetBooleanOLE对象byte[]getBytes按二进制处理Replication IDStringgetString有一个经验值得分享如果你在做数据迁移尽量在SQL里用CAST或CONVERT把字段显式转为目标类型比如SELECT CAST(id AS INTEGER) FROM t_sku让HSQLDB在内存层完成转换Java侧拿到的类型就稳定了绕过Jackcess那层的类型映射。这个技巧在列很多的老表上尤其有用。5. 避坑实录四类折腾过我的Access驱动问题5.1 程序退出后Access文件被锁死Windows提示文件正在使用现象程序main方法正常跑完进程也结束了但双击Access文件提示“文件正在使用中或已锁定”。重启电脑才恢复。原因连接没有完全关闭。这通常不是ucanaccess的问题而是代码里漏了连接释放。另外一个隐藏前提即使Connection关闭了如果使用memorytrue模式HSQLDB的SHUTDOWN没执行完文件句柄不会释放。正常的mdb打开时Jackcess会独占文件句柄。解决确认所有ResultSet、Statement、Connection都在finally或try-with-resources里关闭。关闭顺序必须是ResultSet→Statement→Connection反向关会报Database already closed。同时把连接串加上shutdowntrue让连接关闭时把HSQLDB的镜像文件清干净并释放句柄。从那以后我每次写完连接代码都强制走一遍“三个close”的检查再也没碰到过文件锁死。5.2 自增ID用Object接收时ClassCastException现象rs.getObject(id)返回的对象强转成Integer时抛ClassCastException日志显示实际运行时类型是java.math.BigDecimal。原因上一章提过ucanaccess对AUTOINCREMENT列的默认映射是BigDecimal强转当然失败。JDBC规范没有强制规定getObject的返回类型必须和Java类型完全一致所以这个错不是驱动bug是调用方的类型假设错误。解决不要用getObject接数值列统一用getInt/getLong。如果你确实需要拿到原始类型去做泛型映射那就针对BigDecimal.class写一行处理逻辑。一句话建议宁可早转换不要晚强转。5.3 写入后立刻查询数据“消失”看不见现象代码里INSERT执行成功executeUpdate返回1紧接着同一个连接SELECT查不到这条记录。换个新连接就能查到。原因这是AutoCommitfalse时最常见的一个误操作插入后忘记commit当前连接还能看到自己事务里的未提交数据但同一个连接里新开的Statement在隔离级别为READ_COMMITTED时只能看到已提交的数据。ucanaccess默认的隔离级别表现和其他数据库不完全一致不明确commit就查很容易遇到这种“薛定谔的数据”。解决插入后调conn.commit()或者直接保持AutoCommit的默认值true不做手动事务。如果你的业务逻辑里确实需要多步写入保证原子性那就必须在代码路径里显式catch异常并rollback同时监控有没有漏commit的分支。列个检查表每个executeUpdate之后要么commit要么rollback不允许“留到最后再提交”。5.4 32位环境正常64位环境读取报“Column not found”现象同一份代码在32位JVM上跑得好好的切到64位JVM后SELECT * FROM t_sku返回的结果集里访问某个字段名时提示“Column not found”。原因问题的本质不是位数而是旧库的表结构里有重复字段名或字段名包含空格。32位时代很多程序用rs.getColumnName()拿到的是实际列名64位环境下驱动版本或HSQLDB引擎版本解析列名时发生了去重和截断导致按原始字段名取值找不到。解决查询时不要用SELECT *把字段名逐个列出来例如SELECT sku_code, sku_name FROM t_sku。这样即使底层列名有变动你的Java代码拿到的结果集列标签是稳定的。另一个排查技巧打印ResultSetMetaData.getColumnLabel()对比实际返回的标签和你代码里写的字段名差异一眼就能看出来。6. 进阶验证用受控写入和bak备份做回归检查6.1 把shutdown参数变成强制刷盘开关上一章提到shutdowntrue能避免文件锁实际上它还有一个容易被忽略的用途作为验证写操作是否落盘的开关。当你往Access库里做了大批量写入想确认数据是不是真的物理写进文件最笨也最可靠的方法是关掉所有连接直接用Access或另一个JDBC连接只读打开文件看记录数。ucanaccess在shutdown时会做一次完整的HSQLDB SHUTDOWN把未刷盘的缓冲区数据强制写入mdb文件。如果shutdown失败会抛出异常这时你至少知道上一次写入可能没有完整落盘。String url jdbc:ucanaccess://D:/data/erp.mdb;shutdowntrue;keepMirrorfalse; try (Connection conn DriverManager.getConnection(url)) { // 执行写入操作 } catch (Exception e) { e.printStackTrace(); } // 这里连接已关闭写入已完成刷盘可以放心做回归检查这段代码没有显式的conn.shutdown()调用但try-with-resources结束时Connection关闭UcanaccessDriver会执行SHUTDOWN逻辑。之前提到的批量写入没有显式commit导致数据丢失的场景加了这个参数后连接关闭时会再次执行一次完整flush相当于一道兜底。6.2 用bak文件做数据回归的锚点Jackcess在打开mdb文件时如果检测到文件头部有被修改过的标记有时会生成一个.bak文件。这个行为在ucanaccess里可以通过jackcessOpener参数控制。利用这个机制可以做一件很有用的事在批量写入前先打开一次库触发bak生成然后执行数据变更写入完成后检查bak文件是否存在如果存在说明底层文件确实被改写过了再对比bak和当前文件的记录数差异就能确认写入数量是否符合预期。那次数据回退事故让我养成一个习惯凡是动Access存量数据先复制一份文件到临时目录再在测试库里跑一遍同样的写入脚本确认结果集正确后才动生产库。同一个脚本跑两遍看起来费时间但避免的是数据不可逆损坏的代价。从那以后我每次批量操作前都会强制走一遍备份、验证、切生产的流程宁可慢三分钟不要赌一次。希望这些从驱动原理到实际排错的记录能帮到你让你在处理Java读Access这条路的时候少走一些弯路。本文还有配套的精品资源点击获取