ACLClouds
ACLClouds

Как подключить базу MySQL к серверу FiveM через oxmysql?

Создать базу в панели, установить oxmysql, прописать mysql_connection_string в server.cfg, импортировать SQL ESX или QBCore и исправить типичные ошибки

oxmysql — это ресурс, который подключает сервер FiveM или RedM к базе MySQL или MariaDB. От него зависят ESX Legacy, QBCore и Qbox: без подключения к базе фреймворк не запускается. В ACLClouds база размещается на отдельном сервере MariaDB и входит в тариф: 1 база в Dev, 2 в City, 3 в Empire.

Пошаговая инструкция

  1. Создать базу

    В разделе «Базы данных» нажмите «Новая база данных», задайте короткое имя, например esx или qbcore, и оставьте поле «Подключения из» пустым, чтобы разрешить доступ и игровому серверу, и вашему ПК. Панель добавляет к имени префикс: база будет называться, например, s12345_esx.

  2. Собирайте идентификаторы

    Откройте базу в списке: панель покажет «Конечную точку» (хост и порт), «Имя пользователя», «Пароль» и строку подключения JDBC. Хост — это адрес сервера баз данных, а не localhost и не 127.0.0.1.

  3. Установить oxmysql

    Скачайте oxmysql.zip из последнего релиза на странице Releases репозитория GitHub overextended/oxmysql, а не исходный код: скомпилированные файлы есть только в архиве релиза. Распакуйте его в resources/[standalone]/oxmysql через «Файлы». Рецепты ESX и QBCore в txAdmin уже устанавливают его.

  4. Прописать подключение в server.cfg

    Добавьте set mysql_connection_string с пользователем, паролем, хостом, портом и именем базы, затем ensure oxmysql перед фреймворком и всеми ресурсами, которые используют базу.

  5. Импортировать таблицы

    Фреймворки и многие скрипты поставляются с файлом .sql. Импортируйте его со своего ПК через HeidiSQL, DBeaver или клиент mariadb, используя данные из панели. Рецепт txAdmin создаёт свои таблицы сам.

  6. Перезапустите сервер и проверьте консоль

    При запуске oxmysql сообщает в консоли о подключении к базе и версии MariaDB. Ошибка почти всегда называет причину: хост, пароль или имя базы.

Подключение в server.cfg (формат URL)

set mysql_connection_string "mysql://u12345_AbCdEf:PASSWORD@HOST:3306/s12345_esx?charset=utf8mb4"

ensure oxmysql
ensure es_extended

Другой формат, который принимает oxmysql

set mysql_connection_string "host=HOST;port=3306;user=u12345_AbCdEf;password=PASSWORD;database=s12345_esx"

Полезные параметры oxmysql

set mysql_slow_query_warning 150
set mysql_ui true

Импорт и экспорт с ПК

mariadb -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx < es_extended.sql
mariadb-dump -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx > backup.sql

Перед началом

Базы данных входят в платные тарифы FiveM в пределах лимита, указанного вверху раздела «Базы данных». У каждой базы свой пользователь и свои права. Все скрипты одного сервера обычно используют одну и ту же базу.

  • Остановите сервер перед изменением server.cfg.
  • С txAdmin редактируйте server.cfg рецепта в папке txData, а не файл в корне.
  • Не запускайте одновременно mysql-async или ghmattimysql: oxmysql сам предоставляет их функции старым скриптам.

Специальные символы в пароле

В формате URL символы @, :, /, #, ? и % в пароле ломают строку. Закодируйте их (@ превращается в %40), используйте формат key=value или возьмите строку JDBC из панели, где пароль уже закодирован, убрав префикс jdbc:.

Кнопка смены пароля создаёт новый пароль: сразу обновите server.cfg, иначе при следующем запуске oxmysql не подключится.

Резервное копирование базы

Резервные копии панели сохраняют файлы сервера, но не базу данных. Регулярно экспортируйте её через mariadb-dump или экспорт HeidiSQL, особенно перед каждым обновлением фреймворка, и храните копию вне сервера.

Частые ошибки и их решение

oxmysql пишет причину сбоя в консоль при запуске сервера.

  • ECONNREFUSED или ETIMEDOUT: неверный хост или порт. Скопируйте «Конечную точку» заново; localhost не работает, потому что база находится не в контейнере игры.
  • ER_ACCESS_DENIED_ERROR: неверный пользователь или пароль, часто из-за незакодированного спецсимвола, либо значение «Подключения из», которое не пускает игровой сервер.
  • ER_BAD_DB_ERROR: неизвестное имя базы. Укажите полное имя с префиксом, например s12345_esx.
  • ER_NO_SUCH_TABLE: база пуста или неполна. Импортируйте файл .sql нужного фреймворка или скрипта.
  • No such export для oxmysql при загрузке скрипта: oxmysql запускается слишком поздно. Поставьте ensure oxmysql перед фреймворком.

Быстрая проверка

  • Консоль показывает подключение oxmysql к базе без ошибок.
  • ensure oxmysql стоит перед фреймворком.
  • Таблицы фреймворка видны в HeidiSQL или DBeaver.
  • Свежий экспорт .sql хранится вне сервера.

Часто задаваемые вопросы

Нужно ли устанавливать MySQL на сервер FiveM?

Нет. База размещается на отдельном сервере MariaDB, который входит в тариф: вы создаёте её в разделе «Базы данных», и oxmysql подключается к ней по сети. MariaDB совместима с MySQL для ESX, QBCore и Qbox.

Как просматривать и изменять таблицы?

Подключитесь со своего ПК через HeidiSQL или DBeaver, используя хост, порт, пользователя и пароль из панели. Перед любыми ручными изменениями сделайте экспорт.

Можно ли использовать внешнюю базу данных?

Да. oxmysql подключается к любому серверу MySQL или MariaDB, доступному с игрового сервера: укажите его хост и учётные данные в mysql_connection_string. База рядом с игровым сервером отвечает быстрее, что важно для скриптов с частыми запросами.

Консоль сообщает о медленных запросах, что делать?

oxmysql отмечает запросы дольше mysql_slow_query_warning (по умолчанию 200 мс) и называет виновный ресурс. Добавьте индекс на столбец, по которому он фильтрует, или замените скрипт: ресурс, который опрашивает базу в цикле, тормозит весь сервер.