Minecraft MySQL JDBC

Minecraft MySQL JDBC - это небольшой, но очень полезный проект для разработчиков и админов серверов. По сути это официальный коннектор MySQL Connector/J от Oracle, завёрнутый сразу в два формата: плагин для Bukkit/Spigot/Paper и мод для Fabric, Forge и NeoForge. Скачать Minecraft MySQL JDBC стоит тем, кто пишет свои плагины или ставит что-то вроде Grim Anti-Cheat с хранением данных в базе.

Зачем это вообще нужно? Многие серверные плагины хранят статистику игроков, баны, варны, экономику и прочие данные в MySQL или MariaDB. Для подключения к базе в Java используется JDBC-драйвер. Проблема в том, что встроенный в сервер драйвер часто устаревший, а на Fabric и NeoForge его вообще нет. Этот проект решает вопрос одной установкой: закинул jar в нужную папку - и свежий коннектор версии 9.1.0 уже на месте.

Важный нюанс для владельцев Bukkit-серверов

Тут есть момент, о котором многие не знают. CraftBukkit, Spigot и Paper таскают MySQL Connector/J в родительском загрузчике классов ещё с версии 1.4, со времён ebeans. Поэтому при стандартном подключении через Class.forName("com.mysql.cj.jdbc.Driver") или DriverManager.getConnection всегда побеждает встроенный драйвер сервера. Установка этого плагина сама по себе ничего не поменяет.

Реальная польза проекта раскрывается на Fabric и NeoForge, где драйвера нет вообще, а также на форках Bukkit, которые вырезали встроенный коннектор. Если же вам нужен именно этот свежий драйвер вместо серверного - например, чтобы обновиться с протухшей версии - используйте публичный 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 случилось ещё в ветке 8.x. Имя класса com.mysql.cj.jdbc.Driver работает и на старых, и на новых координатах, так что проверка наличия драйвера в рантайме стабильна.

Совместимость

Загрузчик	Версии Minecraft	Примечание
Bukkit / Spigot / Paper / Folia / Purpur	1.8 и новее	обычно не нужен - драйвер встроен в сервер
Fabric	1.16.1 и новее	требуется Fabric Loader 0.14+
Forge	1.12 - 1.20	универсальный jar, без миксинов
NeoForge	1.21 и новее	просто закинуть в mods/

Нужна Java 8 или новее. Проект живой и обновляется под свежие версии Майнкрафт и Java, так что не придётся искать отдельный JDBC-jar под каждый релиз сервера.

Подводные камни строки подключения

Драйверы 5.1.x и 8+ имеют дефолты, которые почти всегда приходится переопределять для реальной работы. Вот что стоит знать:

• useSSL=true включён по умолчанию - и падает на любом MySQL-сервере без публичного сертификата от CA. Для открытого соединения ставьте useSSL=false, а если сертификат самоподписанный, добавьте verifyServerCertificate=false.
• caching_sha2_password (дефолт в MySQL 8) требует allowPublicKeyRetrieval=true для авторизации по незашифрованному каналу, иначе рукопожатие падает с ошибкой Public Key Retrieval is not allowed.
• rewriteBatchedStatements=true склеивает пакетные INSERT-запросы JDBC в многострочный формат. Без этого параметра пакетные операции идут как N отдельных запросов - а это N обращений к базе вместо одного.

Типичная строка подключения выглядит так:

jdbc:mysql://host:3306/db?useSSL=false&allowPublicKeyRetrieval=true&rewriteBatchedStatements=true

MariaDB говорит по протоколу MySQL, так что этот драйвер работает и с ней. Если нужен именно нативный коннектор MariaDB - это отдельный драйвер, сюда он не входит.

Версионирование

Версия jar повторяет версию коннектора один в один. Например, 9.1.0+2026-04-25 содержит connector-j 9.1.0, а суффикс - это дата сборки. Автоматика ежедневно проверяет Maven Central и подтягивает обновления, так что драйвер всегда свежий.

Подключение через публичный API

Если нужен именно этот коннектор вместо встроенного - чтобы перепрыгнуть через устаревший драйвер форка или протестировать новую версию - ваш плагин делает softdepend на этот держатель и вызывает MinecraftMysqlJdbc.connect(url, props):

# в 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()	версия коннектора, например "9.1"
eagerInit()	прогрев загрузчика при включении плагина
shutdown()	освобождение файловых дескрипторов при выключении

Grim Anti-Cheat с MySQL-бэкендом использует этот API автоматически, если держатель установлен. Так что для владельцев серверов с Гримом это прямо must-have.

Лицензия

GPL-2.0 с Universal FOSS Exception 1.0. Исключение делает драйвер совместимым с любым FOSS-лицензированным плагином или модом для Minecraft - это та же лицензия, под которой Oracle распространяет бинарник Connector/J. На Modrinth стоит тег GPL-2.0-only просто потому, что в списке SPDX нет отдельного идентификатора для связки GPL-2 + FOSS Exception. Полный текст лежит в файле LICENSE.

Кому реально пригодится

Если вы разработчик плагинов и хотите хранить данные игроков, статистику или конфиги в SQL-базе без возни с отдельной библиотекой - это ваш вариант. Админам с Grim Anti-Cheat и MySQL-хранилищем тоже стоит поставить. А вот обычным игрокам и тем, кто просто держит ванильный сервер на Paper, этот проект, скорее всего, не нужен - драйвер уже встроен. Скачать Minecraft MySQL JDBC можно для Minecraft 1.8 и новее на Bukkit-платформах, а для Fabric, Forge и NeoForge - начиная с версий из таблицы выше.