Minecraft MySQL JDBC

Oracle 官方的 MySQL Connector/J 重新打包为 Bukkit/Spigot/Paper 插件以及 Fabric/Forge/NeoForge 模组。

请注意： 自 1.4（“ebeans”时代）起，CraftBukkit/Spigot/Paper 就在服务端的父类加载器上附带了 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 → 当前 | 通常不必要——驱动由服务端内置 |
| Fabric | 1.16.1 → 当前 | 需要 Fabric Loader 0.14+ |
| Forge | 1.12 → 1.20 | 通用 jar，无 Mixins |
| NeoForge | 1.21 → 当前 | 放入 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 使用此模组的连接器

如果你特别想使用此模组的连接器而非内置连接器——为了升级过时分支的内置驱动，或测试更新的连接器版本——你的插件需软依赖此 holder 并调用 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会包装一个子优先（child-first）的 URLClassLoader，指向这个 jar，并将其父级设为平台类加载器，因此 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() | 在插件禁用时释放文件句柄 |

当安装此 holder 时，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。