Minecraft 用 MySQL Connector/J
Oracle 官方 MySQL Connector/J 的重新打包版本,作为 Bukkit/Spigot/Paper 插件以及 Fabric/Forge/NeoForge 模组提供。
注意: CraftBukkit/Spigot/Paper 自 1.4(“ebeans”时代)起已将 MySQL Connector/J 内置于服务器的父类加载器中。对于默认 JDBC 路径(Class.forName("com.mysql.cj.jdbc.Driver") / DriverManager.getConnection),内置驱动优先——安装此模组不会改变这一情况。此模组主要适用于 Fabric、NeoForge 以及移除了内置驱动的 Bukkit 分支。如果您特别希望使用此模组的连接器而非内置的(例如为了获取更新版本的连接器),请使用公共 API —— 参见下方的通过公共 API 使用此模组的连接器。
Jar 包内容
包含 com.mysql:mysql-connector-j:9.1.0 以及针对 Spigot、Forge 1.12、Forge 1.13–1.16、Forge 1.17–1.20、NeoForge 1.21+ 和 Fabric 的最小化加载器存根。未进行重定位 —— com.mysql.cj.* 类保持在其规范路径下,以便 Class.forName("com.mysql.cj.jdbc.Driver") 能够找到它们。META-INF/services/java.sql.Driver 得以保留,使驱动能自动向 DriverManager 注册。
mysql:mysql-connector-java → com.mysql:mysql-connector-j 的重命名发生在 connector-j 8.x 版本中。类名 com.mysql.cj.jdbc.Driver 在旧的和新的构件坐标下均有效,因此运行时探测是稳定的。
兼容性
| 加载器 |
MC 版本 |
备注 |
| Bukkit / Spigot / Paper / Folia / Purpur |
1.8 → current |
通常不需要 —— 服务器已内置驱动 |
| Fabric |
1.16.1 → current |
需要 Fabric Loader 0.14+ |
| Forge |
1.12 → 1.20 |
通用 jar,无 Mixins |
| NeoForge |
1.21 → current |
放入 mods/ 目录 |
需要 Java 8+。
值得了解的连接字符串注意事项
5.1.x 和 8+ 驱动程序默认的行为在真实部署中几乎总是需要覆盖:
useSSL=true 是默认值 —— 对于任何没有公共 CA 签名证书的 MySQL 服务器都会失败。设置 useSSL=false 以启用明文传输,或者如果您拥有自签名证书,请添加 verifyServerCertificate=false。
caching_sha2_password(MySQL 8 默认)对于非加密通道认证需要 allowPublicKeyRetrieval=true,否则握手将因 Public Key Retrieval is not allowed 而失败。
rewriteBatchedStatements=true 会在网络层面将 JDBC 批量 INSERT 折叠为多行形式。如果没有它,批量操作仍然是 N 次往返。
典型 URL:
jdbc:mysql://host:3306/db?useSSL=false&allowPublicKeyRetrieval=true&rewriteBatchedStatements=true
MariaDB 在网络层使用 MySQL 协议,因此此驱动也能用于 MariaDB。如果您想要 MariaDB 原生连接器,它是一个单独的驱动,不在本文范围内。
版本控制
Jar 包版本与 connector-j 一对一追踪。9.1.0+2026-04-25 携带了 connector-j 9.1.0;后缀为构建日期。计划中的 GitHub Action 每天检查 Maven Central 并自动提升版本。
通过公共 API 使用此模组的连接器
如果您特别希望使用此模组的连接器而非内置的 —— 例如为了超越陈旧分支内置驱动的过旧版本,或测试更新版本的连接器 —— 您的插件对此持有者软依赖,并调用 MinecraftMysqlJdbc.connect(url, props):
# in your plugin.yml
softdepend: [mysql-jdbc]
Properties props = new Properties();
props.setProperty("user", "grim");
props.setProperty("password", "...");
Connection c;
try {
c = MinecraftMysqlJdbc.connect("jdbc:mysql://host:3306/db?useSSL=false", props);
} catch (NoClassDefFoundError | ClassNotFoundException notInstalled) {
c = DriverManager.getConnection("jdbc:mysql://host:3306/db?useSSL=false", props);
}
MinecraftMysqlJdbc 包装了一个指向此 jar 的子优先 URLClassLoader,其父类加载器为平台类加载器,因此 com.mysql.cj.* 必须来自此 jar(而非内置链)。返回的 Connection 是标准的 java.sql.Connection —— 请保持对 java.sql.* 接口的转换;实现类位于子优先类加载器中,不会跨越边界进行向下转换。
API 表面(全部为静态方法):
| 方法 |
返回 |
connect(String url) |
通过此驱动打开 Connection |
connect(String url, Properties props) |
同上,带属性 |
driver() |
java.sql.Driver 实例 |
driverVersion() |
connector-j 版本(例如 "9.1") |
eagerInit() |
在插件启用时预热类加载器 |
shutdown() |
在插件禁用时释放文件句柄 |
Grim Anti-Cheat 的 MySQL 后端在此持有者安装时会自动使用此 API。
许可证
GPL-2.0 配合 Universal FOSS Exception 1.0。该异常使驱动程序兼容任何采用 FOSS 许可的 Minecraft 插件或模组(这与 Oracle 随 Connector/J 二进制文件提供的许可证相同)。Modrinth 的许可证标签显示为 GPL-2.0-only,因为 SPDX 列表中没有单个标识符来代表 GPL-2 + FOSS Exception 组合 —— 完整文本见 LICENSE。
问题反馈、源码:GitHub。
MySQL Connector/J for Minecraft
Oracle's official MySQL Connector/J repackaged as a Bukkit/Spigot/Paper plugin and a Fabric/Forge/NeoForge mod.
Heads up: CraftBukkit/Spigot/Paper have shipped MySQL Connector/J on the server's parent classloader since 1.4 (the "ebeans" era). For the default JDBC path (Class.forName("com.mysql.cj.jdbc.Driver") / DriverManager.getConnection) the bundled driver wins — installing this mod doesn't change that. This mod is primarily useful on Fabric, NeoForge, and Bukkit forks that strip the bundled driver. If you specifically want this mod's connector instead of the bundled one (e.g. for a newer connector version), use the public API — see Using this mod's connector via the public API below.
What's in the jar
com.mysql:mysql-connector-j:9.1.0 plus minimal loader stubs for Spigot, Forge 1.12, Forge 1.13–1.16, Forge 1.17–1.20, NeoForge 1.21+, and Fabric. No relocation — com.mysql.cj.* classes stay at canonical paths so Class.forName("com.mysql.cj.jdbc.Driver") finds them. META-INF/services/java.sql.Driver is preserved so the driver auto-registers with DriverManager.
The mysql:mysql-connector-java → com.mysql:mysql-connector-j rename happened in connector-j 8.x. The class name com.mysql.cj.jdbc.Driver works across both old and new artifact coords, so the runtime probe is stable.
Compatibility
| Loader |
MC versions |
Notes |
| Bukkit / Spigot / Paper / Folia / Purpur |
1.8 → current |
usually unnecessary — driver is server-bundled |
| Fabric |
1.16.1 → current |
needs Fabric Loader 0.14+ |
| Forge |
1.12 → 1.20 |
universal jar, no Mixins |
| NeoForge |
1.21 → current |
drop into mods/ |
Java 8+ required.
Connection-string gotchas worth knowing
The 5.1.x and 8+ drivers default to behaviours that almost always need overriding for real deployments:
useSSL=true is the default — fails against any MySQL server without a public CA-signed cert. Set useSSL=false for plaintext, or add verifyServerCertificate=false if you have a self-signed cert.
caching_sha2_password (MySQL 8 default) needs allowPublicKeyRetrieval=true for unencrypted-channel auth, otherwise the handshake fails with Public Key Retrieval is not allowed.
rewriteBatchedStatements=true folds JDBC batch INSERTs into multi-row form on the wire. Without it, batch operations are still N round-trips.
Typical URL:
jdbc:mysql://host:3306/db?useSSL=false&allowPublicKeyRetrieval=true&rewriteBatchedStatements=true
MariaDB speaks the MySQL protocol on the wire, so this driver works against MariaDB too. If you want the MariaDB-native connector instead, it's a separate driver and not in scope here.
Versioning
The jar version tracks connector-j one-to-one. 9.1.0+2026-04-25 ships connector-j 9.1.0; the suffix is the build date. A scheduled GitHub Action checks Maven Central daily and bumps automatically.
Using this mod's connector via the public API
If you specifically want this mod's connector instead of the bundled one — to upgrade past a stale fork's bundled driver, or to test a newer connector version — your plugin softdepends on this holder and calls MinecraftMysqlJdbc.connect(url, props):
# in your plugin.yml
softdepend: [mysql-jdbc]
Properties props = new Properties();
props.setProperty("user", "grim");
props.setProperty("password", "...");
Connection c;
try {
c = MinecraftMysqlJdbc.connect("jdbc:mysql://host:3306/db?useSSL=false", props);
} catch (NoClassDefFoundError | ClassNotFoundException notInstalled) {
c = DriverManager.getConnection("jdbc:mysql://host:3306/db?useSSL=false", props);
}
MinecraftMysqlJdbc wraps a child-first URLClassLoader pointing at this jar, parented to the platform classloader so com.mysql.cj.* must come from this jar (not the bundled chain). The returned Connection is a standard java.sql.Connection — keep your casts to java.sql.* interfaces; the impl class lives in the child-first classloader and won't down-cast across the boundary.
API surface (all static):
| Method |
Returns |
connect(String url) |
open Connection through this driver |
connect(String url, Properties props) |
as above with props |
driver() |
the java.sql.Driver instance |
driverVersion() |
connector-j version (e.g. "9.1") |
eagerInit() |
warm the classloader at plugin enable |
shutdown() |
release file handles on plugin disable |
Grim Anti-Cheat's MySQL backend uses this API automatically when this holder is installed.
License
GPL-2.0 with the Universal FOSS Exception 1.0. The exception makes the driver compatible with any FOSS-licensed Minecraft plugin or mod (it's the same license Oracle ships with the Connector/J binary). Modrinth's license tag shows GPL-2.0-only because the SPDX list doesn't have a single identifier for the GPL-2 + FOSS Exception combo — full text in LICENSE.
Issues, source: GitHub.
评论 0
登录后参与评分
还没有评论,来抢沙发吧