FiveM: проблема с подключением к базе данных MySQL

MAATRIX GAMES

Стартуешь FiveM-сервер, а в консоли вместо привычного списка загруженных ресурсов — красная простыня про MySQL, и сервер либо не поднимается вообще, либо падает через пару минут под первыми игроками. Это одна из самых частых причин, по которой RP-сервер на ESX или QBCore просто не оживает после установки — и почти всегда дело не в самом FiveM, а в том, как база данных настроена и как к ней подключается oxmysql. Разберём по шагам, где искать причину и как её закрыть, не переустанавливая всё с нуля.

Как быстро понять, что дело именно в MySQL, а не в самом FiveM

Первое, что нужно сделать — открыть консоль сервера (напрямую в терминале или через txAdmin) и найти момент, когда падает загрузка. Если ресурсы вроде oxmysql, es_extended или qb-core не стартуют и следом идёт стектрейс с упоминанием mysql, ER_ACCESS_DENIED_ERROR, ECONNREFUSED или Unknown database — причина почти наверняка в подключении к БД, а не в скриптах фреймворка.

Стоит отличать два разных сценария, потому что лечатся они по-разному:

• Сервер не стартует вообще — падает сразу при загрузке oxmysql, ещё до того как игроки успевают зайти. Обычно это неверная connection string, отсутствующая база или проблема с правами пользователя.
• Сервер стартует, но падает или тормозит под нагрузкой — первые минуты всё нормально, а потом начинаются обрывы соединения, таймауты запросов, лаги при сохранении данных игрока. Это чаще пул соединений, лимиты MySQL по max_connections или банально нехватка ресурсов у самой базы.

Если у тебя ещё нет базового сервера FiveM — сначала пройди установку сервера FiveM, там же описана структура server.cfg, к которой мы будем возвращаться ниже.

Типичные причины ошибки подключения и как их различить

В 90% случаев проблема укладывается в один из четырёх сценариев:

1. Неверная connection string в server.cfg — опечатка в логине, пароле, хосте или имени базы.
2. База данных не создана — ты прописал в конфиге имя базы, которой физически не существует на сервере MySQL.
3. У пользователя MySQL нет прав на эту базу, либо он не может подключаться с нужного хоста.
4. MySQL-сервер недоступен — не запущен, слушает не тот порт, либо файрвол режет соединение (актуально, если база стоит на отдельной машине, а не локально с игровым сервером).

Дальше разбираем каждый по отдельности — вместе с конкретными командами для диагностики.

"Access denied for user" — неверные учётные данные или права

Самая частая ошибка в логе выглядит примерно так:

[oxmysql] Error: Access denied for user 'fivem_user'@'localhost' (using password: YES)

Это значит, что MySQL получил запрос на подключение, но отказал по логину/паролю или правам. Первым делом проверь саму connection string в server.cfg. Для oxmysql (актуальный ресурс, если ты недавно поднимал сервер) строка задаётся так:

set mysql_connection_string "mysql://fivem_user:StrongPassword123@localhost/fivem_db?charset=utf8mb4"

Для более старого mysql-async (часто встречается на легаси-конфигах ESX) формат чуть другой:

set mysql_connection_string "server=localhost;database=fivem_db;userid=fivem_user;password=StrongPassword123;charset=utf8mb4"

Частая грабля — спецсимволы в пароле (@, #, :, /), которые ломают парсинг URL-формата у oxmysql. Если пароль содержит такие символы, либо экранируй их URL-кодированием, либо (проще) смени пароль на буквенно-цифровой без спецсимволов.

Дальше проверь права пользователя напрямую в MySQL/MariaDB — зайди под root и посмотри, что реально выдано:

SHOW GRANTS FOR 'fivem_user'@'localhost';

Если строка пустая или там нет нужной базы — выдай права заново:

CREATE USER IF NOT EXISTS 'fivem_user'@'localhost' IDENTIFIED BY 'StrongPassword123';
GRANT ALL PRIVILEGES ON fivem_db.* TO 'fivem_user'@'localhost';
FLUSH PRIVILEGES;

Обрати внимание на хост в кавычках — 'fivem_user'@'localhost' и 'fivem_user'@'%' для MySQL это два разных пользователя. Если игровой сервер и MySQL стоят на одной машине, но в конфиге почему-то указан IP вместо localhost (или наоборот), подключение может упереться именно в это несовпадение хоста. На VPS с MAATRIX GAMES это не проблема — база разворачивается локально вместе с игровым сервером, но если ты переносишь конфиги со старого хостинга, первым делом сверь именно этот момент.

Основы настройки пользователей и прав для игровых плагинов подробно разобраны в статье про настройку MySQL для игровых плагинов — пригодится, если база настраивается с нуля.

База не существует или указана не та схема

Ошибка выглядит примерно так:

[oxmysql] Error: Unknown database 'fivem_db'

Тут всё просто: в connection string указано имя базы, которой физически нет. Проверь список существующих баз:

SHOW DATABASES;

Если нужной базы нет — создай её и не забудь про кодировку, от которой зависит корректное сохранение никнеймов и текста в инвентаре:

CREATE DATABASE fivem_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

После создания базы фреймворк (ESX или QBCore) сам накатит таблицы при первом запуске — но только если у пользователя есть права CREATE, ALTER, INDEX на эту базу, а не только SELECT/INSERT/UPDATE. Если видишь в логах, что часть таблиц создалась, а часть — нет, почти наверняка упёрлись именно в урезанные права, а не в отсутствие самой базы.

Отдельная грабля — когда SQL-дамп для фреймворка (например, es_extended.sql или дамп из шаблона QBCore) импортировался в другую базу по ошибке, и в итоге таблицы есть, но не там, куда смотрит server.cfg. Сверь имя базы в дампе/консоли и в mysql_connection_string — они должны совпадать один в один, включая регистр букв на Linux (MySQL на Linux регистрозависим к именам баз и таблиц, в отличие от Windows).

Таймауты и обрывы при большом числе одновременных запросов

Если сервер запускается нормально, но через какое-то время после захода игроков консоль начинает сыпать чем-то вроде:

[oxmysql] Error: Pool queue is full
[oxmysql] Error: Too many connections

— дело в пуле соединений, а не в логине/пароле. У oxmysql пул настраивается через convar в server.cfg:

set mysql_slow_query_warning 150
set mysql_debug_sql false

Но куда важнее — лимит самой MySQL/MariaDB на количество одновременных подключений. Посмотреть текущий лимит и фактическую загрузку:

SHOW VARIABLES LIKE 'max_connections';
SHOW STATUS LIKE 'Threads_connected';

Если Threads_connected регулярно упирается в потолок max_connections — либо подними лимит в конфиге MySQL (/etc/mysql/mariadb.conf.d/50-server.cnf, параметр max_connections), либо, что чаще правильнее, поищи ресурс, который открывает соединения без пула — например, кастомный скрипт с прямыми SQL-запросами мимо oxmysql. Каждое избыточное подключение съедает лимит впустую.

Второй частый источник таймаутов — тяжёлые запросы без индексов на активно растущих таблицах (лог действий игроков, инвентарь, банковские транзакции). Если у тебя настроены регулярные автобэкапы базы, заодно проверь, не совпадает ли просадка производительности по времени с окном бэкапа — полный дамп большой базы во время пиковой нагрузки игроков тоже может выглядеть как "таймауты подключения", хотя причина внешняя.

oxmysql vs mysql-async: разница в диагностике

Если сервер собран по устаревшему гайду или мигрировал со старого проекта, там может стоять mysql-async (или его форк ghmattimysql) вместо актуального oxmysql. Это не критично само по себе — оба ресурса решают одну задачу, — но диагностика отличается:

• oxmysql пишет в консоль более развёрнутые сообщения об ошибках с указанием SQL-запроса, который упал, и поддерживает mysql_debug_sql для подробного лога всех запросов при отладке.
• mysql-async менее многословен, и часть ошибок подключения там можно спутать с общим креша ресурса — стоит смотреть не только последнюю строку стектрейса, а на 15-20 строк выше.

Если ты используешь ESX или QBCore, оба фреймворка в актуальных версиях ожидают именно oxmysql как зависимость — при желании перейти проще всего заменить ресурс в resources и один раз проверить, что имя экспортов (exports.oxmysql) совпадает с тем, что дёргают скрипты фреймворка. Разница между фреймворками и их зависимостями от MySQL-ресурсов подробнее разобрана в статье ESX и QBCore: сравнение фреймворков.

Убедись также, что ресурс с MySQL-клиентом стоит в server.cfg строго до строки ensure es_extended или ensure qb-core — порядок загрузки ресурсов в FiveM важен, и если фреймворк стартует раньше подключения к базе, он получит ту же ошибку подключения, даже если конфиг абсолютно верный.

Когда проблема не в конфиге, а в самом MySQL-сервере

Если логин, пароль, права и имя базы трижды перепроверены и всё сходится, а ошибка сохраняется — стоит проверить, жив ли вообще процесс MySQL/MariaDB:

systemctl status mariadb
# или
systemctl status mysql

Если сервис не запущен — подними его (systemctl start mariadb) и посмотри journalctl -u mariadb -n 50 на предмет причины падения: часто это нехватка места на диске под /var/lib/mysql или битые файлы после аварийного выключения.

Если база на отдельной машине (не локально с игровым сервером), проверь, что порт 3306 действительно открыт и слушает нужный интерфейс:

mysql -h DB_HOST -u fivem_user -p -e "SELECT 1;"

Эта команда — быстрый способ проверить подключение в обход самого FiveM: если она тоже падает с Access denied или Connection refused, значит проблема гарантированно на стороне MySQL или сети, а не в конфиге ресурса. Если команда отрабатывает успешно, а FiveM всё равно не подключается — возвращайся к connection string, скорее всего опечатка именно там.

Отдельно: если после нескольких попыток диагностики база выдаёт ошибки повреждения таблиц (InnoDB corruption, Table is marked as crashed) — не пытайся чинить это вручную через REPAIR TABLE вслепую на проде. Сначала сними бэкап того, что есть, а по восстановлению из копии — отдельный разбор в статье про восстановление сервера из бэкапа. Если своей резервной копии нет и данные важны — это тот случай, когда разумнее написать в поддержку хостинга, чем экспериментировать на живой базе с игроками.

Частые вопросы