Minecraft 的 SQLite JDBC

这是对已停更的 Minecraft SQLite JDBC 模组的一个维护分支，现已跟踪最新的 Xerial sqlite-jdbc 版本，并在上游发布新版本时自动升级。

该模组本身不执行任何操作——它将 SQLite JDBC 驱动程序部署到服务器的类路径上，这样其他希望透过 JDBC 读取或写入 .db/.sqlite 文件的插件/模组就无需各自捆绑一份副本。

典型使用者：Dynmap、Plan、LuckPerms、Grim Anti-Cheat，以及任何希望嵌入 SQLite 而不想自行重新分发 10MB 原生二进制文件的插件。

JAR 中包含的内容

org.xerial:sqlite-jdbc:3.53.0.0 加上用于 Spigot、Forge 1.12、Forge 1.13–1.16、Forge 1.17–1.20、NeoForge 1.21+ 和 Fabric 的最小化加载器存根。驱动类保持其规范的 org.sqlite.* 路径——未进行重定位——因此使用者可以通过简单的 Class.forName("org.sqlite.JDBC") 找到它们。META-INF/services/java.sql.Driver 已被保留，以便驱动程序通过 DriverManager 自动注册。

Xerial 驱动程序为每个常见平台/架构（linux x64/aarch64、macos x64/arm64、windows x64）捆绑了原生 SQLite 二进制文件。它们在首次使用时会被提取到 JVM 的临时目录中。

兼容性

加载器	MC 版本	备注
Bukkit / Spigot / Paper / Folia / Purpur	1.8 → 当前	放入 `plugins/` 目录
Fabric	1.16.1 → 当前	需要 Fabric Loader 0.14+
Forge	1.12 → 1.20	通用 JAR，无需 Mixins
NeoForge	1.21 → 当前	放入 `mods/` 目录

需要 Java 8+。没有 Java 8 的普通 BukkitAPI 服务器（任何早于 ~1.8.8 的版本）将无法加载任何现代 Xerial 版本；这是上游的限制，而非本模组的问题。

何时真正需要此模组

CraftBukkit/Spigot/Paper 自 1.4 时代的 ebeans 提交以来，一直在服务器的父类加载器中附带 sqlite-jdbc。插件类加载器采用父优先委托机制，因此对于默认 JDBC 路径（Class.forName("org.sqlite.JDBC") / DriverManager.getConnection）， bundled 驱动程序始终胜出，无论 plugins/ 中有什么。已在 Paper 1.12.2 和 1.21.11 上进行实证测试。

您在以下情况需要此模组：

您使用的是 Fabric 或 NeoForge —— 原版 Minecraft 完全不附带任何 JDBC 驱动程序
您使用的是剥离了 bundled 驱动程序的 Bukkit 分支（这种情况很少见，但在精简版服务器构建中会发生）
您想要比服务器 bundled 版本更新的 SQLite 引擎版本 —— 以便在 1.8–1.12 服务器上支持 RETURNING、STRICT 表、现代 UPSERT，或者仅仅是为了跟踪最新的 Xerial 版本。请参阅下方的通过公共 API 使用更新的引擎。

通过公共 API 使用更新的引擎

默认路径使用 bundled 驱动程序。若要改用本模组的驱动程序，您的插件应软依赖于此持有者并直接调用 MinecraftSqliteJdbc.connect(url)：

// 在您的 plugin.yml 中
softdepend: [sqlite-jdbc]

// 在您的插件代码中
Connection c;
try {
    c = MinecraftSqliteJdbc.connect("jdbc:sqlite:foo.db");
} catch (NoClassDefFoundError | ClassNotFoundException notInstalled) {
    // 未安装持有者 — 回退到 bundled 驱动程序
    c = DriverManager.getConnection("jdbc:sqlite:foo.db");
}

MinecraftSqliteJdbc 包装了一个子优先的 URLClassLoader，指向此 JAR 的 URL，其父加载器为平台类加载器，因此 org.sqlite.* 必须来自此 JAR（而非 bundled 链）。返回的 Connection 是标准的 java.sql.Connection —— 请保持您的强制类型转换为 java.sql.* 接口；实现类 org.sqlite.SQLiteConnection 位于子优先类加载器中，无法跨边界向下转型。

已在 Paper 1.12.2（bundled 引擎 3.21.0）上验证 —— 同一 JVM，同一启动过程：

基准 DriverManager.getConnection → 引擎 3.21.0
MinecraftSqliteJdbc.connect()        → 引擎 3.53.0

API 表面（全部为静态方法）：

方法	返回值
`connect(String url)`	通过此驱动程序打开 `Connection`
`connect(String url, Properties props)`	同上，带属性
`driver()`	`java.sql.Driver` 实例
`engineVersion()`	SQLite 引擎版本（例如 `"3.53.0"`）
`driverVersion()`	驱动程序版本字符串（例如 `"3.53.0.0"`）
`eagerInit()`	在插件启用时预热类加载器
`shutdown()`	在插件禁用时释放文件句柄 + JNI

当安装此持有者且其提供的引擎版本新于 bundled 版本时，Grim Anti-Cheat 的 SQLite 后端会自动使用此 API —— 请参阅 Grim 的数据库维基页面。

常见 Bukkit 系列上的 Bundled SQLite 引擎版本

如果您想知道您的服务器实际附带了什么引擎版本，可参考下表：

CraftBukkit / Paper 系列	Bundled SQLite 引擎
1.8 – 1.10	3.7.2
1.11	3.16.1
1.12	3.21.0.1
1.13	3.25.2
1.14	3.28.0
1.15	3.30.1
1.16 – 1.17	3.34.0
1.20.6	3.45.3.0
Paper 1.21.4	3.47.0.0
Paper 1.21.5 – 1.21.11	3.49.1.0
master / 26.x	3.51.3.0

本模组附带引擎 3.53.0.0（或最新的 xerial 版本），但这对 Bukkit 系列服务器无关紧要 —— 实际运行您查询的是 bundled 引擎。如果您需要更新的引擎以支持诸如 RETURNING（3.35+）或 STRICT 表（3.37+）等功能，请升级到 bundled 了足够新驱动程序的 Paper 版本，或者将该工作负载迁移到 Fabric/NeoForge，在那里您可以控制驱动程序。

从插件或模组中使用

将 sqlite-jdbc 声明为 compileOnly：

compileOnly("org.xerial:sqlite-jdbc:3.53.0.0")

在启动时探测：

try {
    Class.forName("org.sqlite.JDBC");
} catch (ClassNotFoundException e) {
    getLogger().warning("SQLite 后端已禁用 — 请安装 minecraft-sqlite-jdbc");
    return;
}
try (Connection c = DriverManager.getConnection("jdbc:sqlite:" + dataDir.resolve("data.db"))) {
    // ...
}

在 Paper 1.17+ 上，每个插件的类加载器都是隔离的。将此模组添加到您的 plugin.yml 的 softdepend 中，以便您的插件可以看到驱动程序类：

softdepend: [minecraft-sqlite-jdbc]

Fabric 和 NeoForge 将所有模组统一在一个类加载器上，因此在那里不需要等效的声明。

版本控制

JAR 版本与 Xerial 的 sqlite-jdbc 版本一一对应。3.53.0.0+2026-04-14 附带引擎 3.53.0.0；后缀是构建日期。一个预定的 GitHub Action 每天检查 Maven Central —— 当 xerial 发布新版本时，此处会自动开启一个合并 PR，并且 Modrinth 版本会自动发布。

许可证

Apache 2.0 (Xerial / Taro L. Saito)。重新打包未添加任何功能更改，并继承该许可证。完整文本见 LICENSE。

问题与源码：GitHub。

Minecraft SQLite JDBC