简介：本资源是面向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.mdb？JDBC URL 写成jdbc:odbc:Driver={Microsoft Access Driver (*.mdb, *.accdb)};DBQ=C:/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 8～17、完整覆盖 ACCDB（含加密）、兼容 JPA/Hibernate（需额外配置）的版本，不是最新版，但最稳。

2. 从零加载 UCanAccess：jar 包组合、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。版本必须锁死。

实际工程中，我一般把这 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://<绝对路径>;[property1=value1];[property2=value2]

注意：路径必须是绝对路径，且不能含中文、空格、括号。Windows 下C:\data\test.accdb要写成C:/data/test.accdb（斜杠，非反斜杠），Linux 下/home/user/db/test.mdb直接可用。

# ✅ 正确示例（Windows） jdbc:ucanaccess://C:/projects/legacy/system.mdb;memory=true;charSet=UTF-8 # ✅ 正确示例（Linux） jdbc:ucanaccess:///opt/app/data/inventory.accdb;openExclusive=true # ❌ 错误示例（相对路径） jdbc:ucanaccess://data.mdb # 运行时抛 java.io.FileNotFoundException # ❌ 错误示例（含空格） jdbc:ucanaccess://C:/My Documents/db.accdb # 空格被截断，实际找 C:/My

关键参数说明（必须理解其副作用）：

• memory=true：启用内存模式。所有表数据加载进 JVM 堆，读写极快，但关闭连接后修改不落盘。适合只读分析、ETL 抽取、单元测试。生产环境写操作必须设为false（默认值）。
• openExclusive=true：以独占方式打开文件，阻止其他进程（包括 MS Access）同时编辑。若文件正被 Access 打开，Java 连接会立即失败，报java.sql.SQLException: The database is locked by another process。调试阶段建议开启，上线后根据业务是否允许多端并发决定。
• charSet=UTF-8：强制指定文件内文本字段编码。Access 本身无统一字符集，老 mdb 多用 GBK，新 accdb 默认 UTF-16，但 UCanAccess 默认按平台默认编码（Windows 通常是 GBK）解码。若字段含中文乱码，必加此项，并确保.accdb文件本身保存为 UTF-8（用 Access 2016+ 新建时可选）。
• password=xxx：支持 Access 数据库密码（*.accdb 加密，非用户级权限）。注意：此密码是数据库文件密码，不是 Windows 登录密码，也不是 Access 的 workgroup (.mdw) 密码。

2.3 在 HikariCP 连接池中安全配置 UCanAccess

UCanAccess 不是传统数据库，它的Connection对象本质是 HSQLDB Connection 的包装，不支持事务隔离级别切换、不支持setAutoCommit(false)后跨多条 SQL 的原子性（因为底层 HSQL 表是只读映射或内存快照）。所以连接池配置要克制：

HikariConfig config = new HikariConfig(); config.setJdbcUrl("jdbc:ucanaccess://C:/app/data/master.accdb;memory=true"); 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-resources：

try (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 的 DDL（Data 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 特有函数必须转义。以下为高频操作对照表：

特别注意：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()) { // 真正的 NULL：Access 中该字段允许空值且未填 phone = null; } else if (phone != null && phone.trim().isEmpty()) { // 空字符串：Access 中填了空格或 ""，或字段不允许空值但默认 "" phone = ""; }

血泪经验：某次对接某高校教务系统.accdb，StudentID字段定义为“允许空值=否”，但导出数据时部分记录留空，Access 自动填""。Java 层用getString()接收后未判空，后续studentId.length()报 NPE。从那以后，我所有getString()后必跟wasNull()，宁可多判一次。

3.3 日期时间字段的时区黑洞与毫秒精度丢失

Access 的DateTime类型底层是浮点数（天数+小数部分），无时区信息。UCanAccess 将其映射为java.sql.Timestamp，但默认按系统默认时区解析。例如：Access 中存2023-01-01 12:00:00（无时区），Windows 系统时区为 CST（UTC+8），UCanAccess 会生成Timestamp对象，其getTime()返回1672560000000L（对应 UTC 时间 2023-01-01 04:00:00），而非1672598400000L（UTC 时间 2023-01-01 12:00:00）。

解决方案：强制指定时区为 UTC，再由业务层转换：

// 连接 URL 加时区参数 String url = "jdbc:ucanaccess://db.accdb;charSet=UTF-8;timezone=UTC"; // 读取时统一转为 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 Customers

4.2 现象：IOException: Cannot run program "cmd.exe": CreateProcess error=2

原因：UCanAccess 4.0.4 在 Windows 上首次加载时，会尝试调用Runtime.getRuntime().exec("cmd.exe /c ver")检测系统版本，以决定是否启用某些 ACE 驱动兼容逻辑。若应用运行在无 cmd.exe 环境（如 Alpine Linux Docker、某些精简版 Windows Server），此调用失败，但不影响核心功能，只是抛出警告。
解决：在 JVM 启动参数中添加-Ducanaccess.disableVersionCheck=true，彻底禁用该检测。无需改代码，一行 JVM 参数搞定。

4.3 现象：SQLException: Column not found: XXX in statement [SELECT XXX FROM YYY]

原因：Access 表中字段名为中文（如客户名称），但连接 URL 未指定charSet=UTF-8，UCanAccess 用平台默认编码（GBK）读取字段名元数据，导致字段名乱码（如客户名称变customer??），ResultSetMetaData.getColumnName(i)返回乱码，PreparedStatement.setString("客户名称", "张三")因找不到列而失败。
解决：URL 必加charSet=UTF-8，且确保.accdb文件本身用 UTF-8 编码保存（Access 2016+ 新建数据库时可选“Unicode compression”）。若旧 mdb 无法重存，可在 Java 层用ResultSetMetaData.getColumnLabel(i)获取原始字节再手动 decode：

String 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% 内存

原因：memory=true模式下，UCanAccess 将整个 Access 数据库（含所有 BLOB 字段）加载进 HSQLDB 内存表。若表中有图片、PDF 等二进制字段（OLE 对象），每个byte[]都被完整复制，内存暴增。
解决：禁用memory=true，改用memory=false（默认），此时 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_OBJECT，getBlob()返回null。必须用 Jackcess：

Database 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 XML：

public 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 id="OrdersMap" type="Orders"> <id property="OrderId" column="Order ID" jdbcType="INTEGER"/> <id property="OrderDate" column="Order Date" jdbcType="TIMESTAMP"/> <id property="CustomerId" column="Customer ID" jdbcType="INTEGER"/> </resultMap>

5.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 number（0x0001） 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告警强。希望帮到你。

本文还有配套的精品资源，点击获取