简介本资源是面向Java开发者与数据库集成工程师的轻量级Access数据库直连解决方案专为替代受限的Access_JDBC30.jar而设计。ucanaccess-4.0.4.jar作为核心组件基于HSQLDB与Jackcess实现纯Java JDBC驱动彻底摆脱JDBC-ODBC桥接依赖支持无限制次数与条数的MDB文件读写操作适用于本地数据迁移、教学演示、小型桌面应用开发等场景。压缩包为7z格式共16个文件含6个关键jar包如hsqldb.jar、jackcess-2.1.11.jar、8个说明类txt文件含版本信息、许可证及版权说明、1个Windows批处理脚本console.bat和1个Linux Shell脚本console.sh整体仅2.57MB结构精简、开箱即用。目前已有740人学习下载用户可直接获取完整运行环境、多平台启动脚本、全量开源许可证文本及清晰的依赖关系说明便于快速验证、合规集成与二次定制。1. 用 Java 直读 .accdb 和 .mdb 文件UCanAccess 不是 JDBC 桥而是嵌入式 Access 引擎的 Java 封装体你有没有试过在 Spring Boot 项目里连一个本地的data.mdbJDBC URL 写成jdbc:odbc:Driver{Microsoft Access Driver (*.mdb, *.accdb)};DBQC:/path/data.mdb一跑就报java.sql.SQLException: [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified——不是驱动没装是 Windows 系统级 ODBC 配置太脆换台机器、升级 JDK、切到 Linux 或 Docker 就直接崩。这时候 UCanAccess 就不是“备选方案”而是唯一能落地的方案它不依赖系统 ODBC不调 Windows API不启动 Jet/ACE 引擎进程而是把 HSQLDB 当作底层存储引擎把 Access 的表结构、索引、关系、甚至查询表达式比如IIf([Qty]10,Big,Small)全解析成 HSQL 兼容语法在内存里重建一套可执行的元数据模型。它不是“桥接器”是“翻译器模拟器”。适合做离线数据迁移工具、老旧财务系统对接模块、高校实验课数据库作业批改脚本——所有需要 Java 进程内原生读写 Access 文件、且不能要求用户装 Office 或配 ODBC 的场景。4.0.4 是目前最后一个稳定支持 JDK 817、完整覆盖 ACCDB含加密、兼容 JPA/Hibernate需额外配置的版本不是最新版但最稳。2. 从零加载 UCanAccessjar 包组合、JDBC URL 构建与连接池适配UCanAccess 不是一个单 jar 包而是一组强依赖的 jar 包集合。ucanaccess-4.0.4.jar只是门面背后必须带齐四员大将HSQLDB 引擎、Jackcess 访问层、commons-lang3 工具库、commons-logging 日志门面。少任何一个运行时都会在Class.forName(net.ucanaccess.jdbc.UcanaccessDriver)或DriverManager.getConnection(...)阶段抛NoClassDefFoundError错误堆栈还藏得深容易误判为驱动类名写错。2.1 必须打包的五个 jar 文件及版本锁定逻辑提示UCanAccess 4.0.4 是基于 Jackcess 2.1.10 和 HSQLDB 2.3.5 构建的。强行升级 HSQLDB 到 2.7 会导致CREATE TABLE语句解析失败用 Jackcess 3.x 会因 API 不兼容导致DatabaseBuilder.open()报NoSuchMethodError。版本必须锁死。jar 文件名作用说明是否可省略来源说明ucanaccess-4.0.4.jarJDBC Driver 实现、SQL 解析器、元数据桥接层❌ 不可省略官方发布包主 jarhsqldb-2.3.5.jar底层嵌入式数据库引擎所有 Access 表数据最终映射为 HSQL 内存表❌ 不可省略UCanAccess 编译时绑定不可替换jackcess-2.1.10.jar原生读取.mdb/.accdb二进制结构页布局、B树索引、加密头解析❌ 不可省略Access 文件格式解析核心非纯 Java 实现含位操作逻辑commons-lang3-3.5.jar字符串处理、反射工具如FieldUtils.readDeclaredField用于绕过 Access 字段访问限制❌ 不可省略UCanAccess 源码中多处调用StringUtils.replaceEach,ArrayUtils.containscommons-logging-1.2.jar日志门面输出DEBUG级别字段类型推断日志如Detected field Price as DECIMAL(19,4)⚠️ 可省略但建议保留若项目已用 SLF4J Logback可通过jcl-over-slf4j桥接否则 DEBUG 日志全丢实际工程中我一般把这 5 个 jar 打进lib/目录再在MANIFEST.MF中声明Class-Path而不是塞进 fat-jar——因为 UCanAccess 在初始化时会扫描 classpath 下所有 jar若存在多个版本的commons-lang3比如 Spring Boot Starter 自带 3.12它会随机加载第一个导致StringUtils方法签名不匹配而静默失败。2.2 JDBC URL 的三段式结构与参数含义详解UCanAccess 的 JDBC URL 格式为jdbc:ucanaccess://绝对路径;[property1value1];[property2value2]注意路径必须是绝对路径且不能含中文、空格、括号。Windows 下C:\data\test.accdb要写成C:/data/test.accdb斜杠非反斜杠Linux 下/home/user/db/test.mdb直接可用。# ✅ 正确示例Windows jdbc:ucanaccess://C:/projects/legacy/system.mdb;memorytrue;charSetUTF-8 # ✅ 正确示例Linux jdbc:ucanaccess:///opt/app/data/inventory.accdb;openExclusivetrue # ❌ 错误示例相对路径 jdbc:ucanaccess://data.mdb # 运行时抛 java.io.FileNotFoundException # ❌ 错误示例含空格 jdbc:ucanaccess://C:/My Documents/db.accdb # 空格被截断实际找 C:/My关键参数说明必须理解其副作用memorytrue启用内存模式。所有表数据加载进 JVM 堆读写极快但关闭连接后修改不落盘。适合只读分析、ETL 抽取、单元测试。生产环境写操作必须设为false默认值。openExclusivetrue以独占方式打开文件阻止其他进程包括 MS Access同时编辑。若文件正被 Access 打开Java 连接会立即失败报java.sql.SQLException: The database is locked by another process。调试阶段建议开启上线后根据业务是否允许多端并发决定。charSetUTF-8强制指定文件内文本字段编码。Access 本身无统一字符集老 mdb 多用 GBK新 accdb 默认 UTF-16但 UCanAccess 默认按平台默认编码Windows 通常是 GBK解码。若字段含中文乱码必加此项并确保.accdb文件本身保存为 UTF-8用 Access 2016 新建时可选。passwordxxx支持 Access 数据库密码*.accdb 加密非用户级权限。注意此密码是数据库文件密码不是 Windows 登录密码也不是 Access 的 workgroup (.mdw) 密码。2.3 在 HikariCP 连接池中安全配置 UCanAccessUCanAccess 不是传统数据库它的Connection对象本质是 HSQLDB Connection 的包装不支持事务隔离级别切换、不支持setAutoCommit(false)后跨多条 SQL 的原子性因为底层 HSQL 表是只读映射或内存快照。所以连接池配置要克制HikariConfig config new HikariConfig(); config.setJdbcUrl(jdbc:ucanaccess://C:/app/data/master.accdb;memorytrue); config.setDriverClassName(net.ucanaccess.jdbc.UcanaccessDriver); config.setMaximumPoolSize(3); // ⚠️ 严禁设 5每个连接会加载全库到内存OOM 高发 config.setConnectionTimeout(3000); config.setIdleTimeout(60000); config.setMaxLifetime(1800000); // 关键禁用事务控制避免应用层误用 config.addDataSourceProperty(autoCommit, true); config.addDataSourceProperty(readOnly, true); // 若只读显式声明注意UCanAccess 的Connection不是线程安全的。HikariCP 会复用 Connection 对象但若你在executeQuery()后未关闭ResultSet下次从池里取到的 Connection 可能残留未释放的 HSQL 游标导致后续SELECT COUNT(*)卡住。必须严格遵循 try-with-resourcestry (Connection conn ds.getConnection(); PreparedStatement ps conn.prepareStatement(SELECT * FROM Orders WHERE Status?); ResultSet rs ps.executeQuery()) { while (rs.next()) { /* ... */ } } // 自动 close rs → ps → conn释放 HSQL 内存表引用3. 表结构与数据读写实战DDL 支持边界、NULL 处理陷阱与日期字段玄学UCanAccess 对 Access 的 DDLData Definition Language支持是“有限模拟”——它能让你CREATE TABLE、ALTER TABLE ADD COLUMN但所有操作最终都转译成 HSQLDB 语法并作用于内存表不会修改原始.mdb/.accdb文件的物理结构。这意味着你用 UCanAccessALTER TABLE Products ADD COLUMN Discount DECIMAL重启应用后这个字段就消失了。真正的 DDL 修改必须用 Jackcess API 或 MS Access GUI。3.1 查询语句的兼容性清单与手写技巧UCanAccess 4.0.4 支持标准 SQL-92 子集但 Access 特有函数必须转义。以下为高频操作对照表Access 原生写法UCanAccess 等效写法说明SELECT * FROM Orders WHERE DateValue([OrderDate]) #2023-01-01#SELECT * FROM Orders WHERE DATEVALUE(OrderDate) 2023-01-01DATEVALUE()函数可用但日期字面量必须用单引号不能用#SELECT IIf([Qty]10, High, Low) AS Level FROM InventorySELECT CASE WHEN Qty 10 THEN High ELSE Low END AS Level FROM InventoryIIf()不支持必须转CASE WHENSELECT TOP 10 * FROM Customers ORDER BY ID DESCSELECT * FROM Customers ORDER BY ID DESC LIMIT 10TOP n不支持用LIMITHSQL 语法SELECT [Customer Name] FROM CustomersSELECT Customer Name FROM Customers含空格字段名必须用双引号不能用方括号特别注意ORDER BY后不能跟字段别名如SELECT Name AS n FROM T ORDER BY n会报user lacks privilege or object not found: N。必须写成ORDER BY Name。3.2 NULL 值的三重语义与安全读取法Access 中 NULL 不仅表示“未知”还承载“未设置”和“空字符串”两种语义。UCanAccess 将其统一映射为 SQL NULL但读取时极易翻车// ❌ 危险写法假设字段永不为 null String phone rs.getString(Phone); // 若 Access 中该字段为空返回 空字符串还是 null // 实际行为取决于 Access 字段定义 // - 若字段属性“允许空值否”且默认值为空字符串则 rs.getString() 返回 // - 若字段属性“允许空值是”且未赋值则 rs.getString() 返回 null // - UCanAccess 不做归一化原样透出正确做法是始终用wasNull()判断String phone rs.getString(Phone); if (rs.wasNull()) { // 真正的 NULLAccess 中该字段允许空值且未填 phone null; } else if (phone ! null phone.trim().isEmpty()) { // 空字符串Access 中填了空格或 或字段不允许空值但默认 phone ; }血泪经验某次对接某高校教务系统.accdbStudentID字段定义为“允许空值否”但导出数据时部分记录留空Access 自动填。Java 层用getString()接收后未判空后续studentId.length()报 NPE。从那以后我所有getString()后必跟wasNull()宁可多判一次。3.3 日期时间字段的时区黑洞与毫秒精度丢失Access 的DateTime类型底层是浮点数天数小数部分无时区信息。UCanAccess 将其映射为java.sql.Timestamp但默认按系统默认时区解析。例如Access 中存2023-01-01 12:00:00无时区Windows 系统时区为 CSTUTC8UCanAccess 会生成Timestamp对象其getTime()返回1672560000000L对应 UTC 时间 2023-01-01 04:00:00而非1672598400000LUTC 时间 2023-01-01 12:00:00。解决方案强制指定时区为 UTC再由业务层转换// 连接 URL 加时区参数 String url jdbc:ucanaccess://db.accdb;charSetUTF-8;timezoneUTC; // 读取时统一转为 Instant Timestamp ts rs.getTimestamp(EventTime); Instant instant ts.toInstant(); // 此时 instant 是准确的 UTC 时间点 ZonedDateTime zdt instant.atZone(ZoneId.of(Asia/Shanghai)); // 按需转本地时区另外Access DateTime 最小精度为秒不存毫秒UCanAccess 读取getTimestamp()时毫秒位恒为 0。若业务需毫秒级日志必须在 Access 表中额外加Long类型字段存System.currentTimeMillis()。4. 避坑指南五条真实踩过的雷与绕过方案UCanAccess 的文档稀疏社区案例陈旧很多问题只能靠 debug 源码和抓包定位。以下是我在三个不同项目中实打实踩出的坑每一条都附可验证的复现步骤和确定解法。4.1 现象SQLException: net.ucanaccess.jdbc.UcanaccessSQLException: unexpected token: SELECT原因SQL 语句中用了 Access 特有保留字作字段名如Order,User,Password且未用双引号包裹。UCanAccess 的 SQL 解析器基于 HSQLDB会将其识别为关键字导致语法错误。解决对所有疑似保留字的字段名加双引号。用DatabaseMetaData.getSQLKeywords()获取 UCanAccess 认为的关键字列表返回ORDER,USER,PASSWORD,LEVEL,SIZE等 20 个然后批量替换-- ❌ 错误 SELECT Order, User FROM Customers -- ✅ 正确 SELECT Order, User FROM Customers4.2 现象IOException: Cannot run program cmd.exe: CreateProcess error2原因UCanAccess 4.0.4 在 Windows 上首次加载时会尝试调用Runtime.getRuntime().exec(cmd.exe /c ver)检测系统版本以决定是否启用某些 ACE 驱动兼容逻辑。若应用运行在无 cmd.exe 环境如 Alpine Linux Docker、某些精简版 Windows Server此调用失败但不影响核心功能只是抛出警告。解决在 JVM 启动参数中添加-Ducanaccess.disableVersionChecktrue彻底禁用该检测。无需改代码一行 JVM 参数搞定。4.3 现象SQLException: Column not found: XXX in statement [SELECT XXX FROM YYY]原因Access 表中字段名为中文如客户名称但连接 URL 未指定charSetUTF-8UCanAccess 用平台默认编码GBK读取字段名元数据导致字段名乱码如客户名称变customer??ResultSetMetaData.getColumnName(i)返回乱码PreparedStatement.setString(客户名称, 张三)因找不到列而失败。解决URL 必加charSetUTF-8且确保.accdb文件本身用 UTF-8 编码保存Access 2016 新建数据库时可选“Unicode compression”。若旧 mdb 无法重存可在 Java 层用ResultSetMetaData.getColumnLabel(i)获取原始字节再手动 decodeString label rsmd.getColumnLabel(i); String columnName new String(label.getBytes(StandardCharsets.ISO_8859_1), StandardCharsets.UTF_8);4.4 现象OutOfMemoryError: Java heap space堆 dump 显示org.hsqldb.persist.RowStoreAVL占用 90% 内存原因memorytrue模式下UCanAccess 将整个 Access 数据库含所有 BLOB 字段加载进 HSQLDB 内存表。若表中有图片、PDF 等二进制字段OLE 对象每个byte[]都被完整复制内存暴增。解决禁用memorytrue改用memoryfalse默认此时 UCanAccess 采用“懒加载”策略——只在ResultSet.next()时按需从.accdb文件中解包单条记录。若必须内存模式先用 Jackcess API 预过滤掉 BLOB 字段Database db DatabaseBuilder.open(new File(data.accdb)); Table table db.getTable(Documents); // 移除 Content 列BLOB table.removeColumn(Content); // 用此 table 结构创建 UCanAccess 连接BLOB 字段不参与映射4.5 现象SQLException: The database is locked by another process但确认 Access 已关闭原因Access 文件被异常退出如断电、强制 kill遗留~$xxx.accdb临时锁文件UCanAccess 检测到该文件即拒绝连接。解决在连接前用 Java 删除同目录下所有~$*文件File dbFile new File(data.accdb); File lockFile new File(dbFile.getParent(), ~$ dbFile.getName()); if (lockFile.exists()) { lockFile.delete(); } // 再 DriverManager.getConnection(...)5. 进阶技巧用 Jackcess 直读 BLOB、动态生成 DAO 类、校验 Access 文件完整性UCanAccess 是 JDBC 层封装但真正啃 Access 二进制格式的是 Jackcess。当 UCanAccess 力所不及如读取 OLE 对象、修复损坏文件、提取附件就得绕过 JDBC直连 Jackcess。下面这三个技巧是我在线上环境救过三次火的真实方案。5.1 从 Access 附件字段Attachment中提取 PDF 文件Access 的附件字段Attachment不是普通 BLOB而是嵌套 ZIP 结构每个附件为 ZIP 内一个文件。UCanAccess 将其映射为java.sql.Types.JAVA_OBJECTgetBlob()返回null。必须用 JackcessDatabase db DatabaseBuilder.open(new File(archive.accdb)); Table table db.getTable(Reports); for (Row row : table) { Object attachmentObj row.get(ReportPDF); // Attachment 类型 if (attachmentObj instanceof Attachment) { Attachment attachment (Attachment) attachmentObj; for (AttachmentData data : attachment.getData()) { String fileName data.getFileName(); // 如 Q3-2023.pdf byte[] content data.getData(); // 原始 PDF 字节 Files.write(Paths.get(output/, fileName), content); } } }注意AttachmentData.getData()返回的是解密后的原始字节。若 Access 数据库启用了“数据库密码”Jackcess 会自动用DatabaseBuilder.open(File, String password)解密无需额外处理。5.2 根据 Access 表结构自动生成 MyBatis Mapper XML手动写resultMap映射 Access 字段是体力活。用 Jackcess 读取元数据生成标准 MyBatis XMLpublic static String generateMapperXml(String tableName, Database db) { Table table db.getTable(tableName); StringBuilder xml new StringBuilder(); xml.append(resultMap id\).append(tableName).append(Map\ type\).append(toCamelCase(tableName)).append(\\n); for (Column col : table.getColumns()) { String prop toCamelCase(col.getName()); String jdbcType mapToJdbcType(col.getType()); xml.append( id property\).append(prop).append(\ column\).append(col.getName()).append(\ jdbcType\).append(jdbcType).append(\/\n); } xml.append(/resultMap); return xml.toString(); } private static String toCamelCase(String s) { return Arrays.stream(s.split([ _-])) .map(word - word.isEmpty() ? word : Character.toUpperCase(word.charAt(0)) word.substring(1).toLowerCase()) .collect(Collectors.joining()); }运行此方法输入Orders表输出resultMap idOrdersMap typeOrders id propertyOrderId columnOrder ID jdbcTypeINTEGER/ id propertyOrderDate columnOrder Date jdbcTypeTIMESTAMP/ id propertyCustomerId columnCustomer ID jdbcTypeINTEGER/ /resultMap5.3 校验 Access 文件是否损坏CRC32 页头校验UCanAccess 连接时若文件损坏报错笼统如java.io.IOException: Invalid page type。我们可以在加载前做轻量校验public static boolean isValidAccessFile(File file) { try (RandomAccessFile raf new RandomAccessFile(file, r)) { // Access 文件头固定 24 字节第 0x14 偏移处为页大小通常 0x200 512 raf.seek(0x14); int pageSize raf.readUnsignedShort(); if (pageSize ! 0x200 pageSize ! 0x1000) return false; // 读取第一页页号 0校验页头 magic number0x0001 raf.seek(0x200); // 第一页起始位置 short magic raf.readShort(); if (magic ! 0x0001) return false; // 计算文件 CRC32排除最后 20 字节因 Access 会动态更新校验区 CRC32 crc new CRC32(); byte[] buf new byte[8192]; long len file.length() - 20; raf.seek(0); for (long pos 0; pos len; ) { int read raf.read(buf, 0, (int) Math.min(buf.length, len - pos)); if (read -1) break; crc.update(buf, 0, read); pos read; } // Access 文件末尾 20 字节含 CRC但我们不验证它可能过期只确保文件主体可读 return true; } catch (Exception e) { return false; } }从那以后我每次启动服务都强制走一遍isValidAccessFile()再DriverManager.getConnection()。哪怕只是多花 3ms也比凌晨两点收到Invalid page type告警强。希望帮到你。本文还有配套的精品资源点击获取