Comment relier une base MySQL à un serveur FiveM avec oxmysql ?
Créer la base dans le panel, installer oxmysql, écrire mysql_connection_string dans server.cfg, importer le SQL d’ESX ou de QBCore et corriger les erreurs
oxmysql est la ressource qui relie un serveur FiveM ou RedM à une base MySQL ou MariaDB. ESX Legacy, QBCore et Qbox en dépendent : sans connexion à la base, le framework ne démarre pas. Sur ACLClouds, la base est hébergée sur un serveur MariaDB à part et incluse dans l’offre : 1 base avec Dev, 2 avec City, 3 avec Empire.
Procédure étape par étape
-
Créer la base
Dans « Bases de données », cliquez sur « Nouvelle base de données », donnez-lui un nom court comme esx ou qbcore et laissez « Connexions depuis » vide pour autoriser le serveur de jeu et votre PC. Le panel préfixe le nom : la base s’appelle par exemple s12345_esx.
-
Relever les identifiants
Ouvrez la base dans la liste : le panel affiche le « Point de terminaison » (hôte et port), le « Nom d’utilisateur », le « Mot de passe » et une chaîne de connexion JDBC. L’hôte est l’adresse du serveur de bases de données, jamais localhost ni 127.0.0.1.
-
Installer oxmysql
Téléchargez oxmysql.zip dans la dernière version publiée sur la page Releases du dépôt GitHub overextended/oxmysql, et non le code source : seule l’archive publiée contient les fichiers compilés. Décompressez-la dans resources/[standalone]/oxmysql avec « Fichiers ». Les recettes ESX et QBCore de txAdmin l’installent déjà.
-
Écrire la connexion dans server.cfg
Ajoutez set mysql_connection_string avec l’utilisateur, le mot de passe, l’hôte, le port et le nom de la base, puis ensure oxmysql avant le framework et avant toutes les ressources qui utilisent la base.
-
Importer les tables
Les frameworks et beaucoup de scripts fournissent un fichier .sql. Importez-le depuis votre PC avec HeidiSQL, DBeaver ou le client mariadb, avec les identifiants du panel. Une recette txAdmin crée elle-même ses tables.
-
Redémarrer et lire la console
Au démarrage, oxmysql indique dans la console qu’il est connecté à la base, avec la version de MariaDB. Une erreur nomme presque toujours sa cause : hôte, mot de passe ou nom de base.
Connexion dans server.cfg (format URL)
set mysql_connection_string "mysql://u12345_AbCdEf:PASSWORD@HOST:3306/s12345_esx?charset=utf8mb4"
ensure oxmysql
ensure es_extended
Autre format accepté par oxmysql
set mysql_connection_string "host=HOST;port=3306;user=u12345_AbCdEf;password=PASSWORD;database=s12345_esx"
Options utiles d’oxmysql
set mysql_slow_query_warning 150
set mysql_ui true
Importer et exporter depuis un PC
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
Avant de commencer
Les bases de données sont incluses dans les offres FiveM payantes, dans la limite affichée en haut de « Bases de données ». Chaque base a son propre utilisateur et ses propres droits. Tous les scripts d’un même serveur partagent en général la même base.
- Arrêtez le serveur avant de modifier server.cfg.
- Avec txAdmin, modifiez le server.cfg de la recette, dans le dossier txData, et non celui de la racine.
- Ne lancez pas mysql-async ou ghmattimysql en même temps : oxmysql reprend leurs fonctions pour les anciens scripts.
Caractères spéciaux dans le mot de passe
Dans le format URL, les caractères @, :, /, #, ? et % du mot de passe cassent la chaîne. Encodez-les (@ devient %40), utilisez le format key=value, ou reprenez la chaîne JDBC du panel, où le mot de passe est déjà encodé, en retirant le préfixe jdbc:.
Le bouton de rotation du mot de passe en génère un nouveau : mettez server.cfg à jour aussitôt, sinon oxmysql ne se connecte plus au démarrage suivant.
Sauvegarder la base
Les sauvegardes du panel copient les fichiers du serveur, pas la base de données. Exportez-la régulièrement avec mariadb-dump ou l’export de HeidiSQL, en particulier avant chaque mise à jour du framework, et gardez une copie hors du serveur.
Erreurs courantes et solutions
oxmysql écrit la cause de l’échec dans la console, au démarrage du serveur.
- ECONNREFUSED ou ETIMEDOUT : mauvais hôte ou mauvais port. Recopiez le « Point de terminaison » ; localhost ne fonctionne pas, la base n’est pas dans le conteneur du jeu.
- ER_ACCESS_DENIED_ERROR : utilisateur ou mot de passe faux, souvent à cause d’un caractère spécial non encodé, ou une valeur de « Connexions depuis » qui exclut le serveur de jeu.
- ER_BAD_DB_ERROR : nom de base inconnu. Indiquez le nom complet avec son préfixe, par exemple s12345_esx.
- ER_NO_SUCH_TABLE : la base est vide ou incomplète. Importez le fichier .sql du framework ou du script concerné.
- No such export sur oxmysql au chargement d’un script : oxmysql démarre trop tard. Placez ensure oxmysql avant le framework.
Vérification rapide
- La console affiche la connexion d’oxmysql à la base, sans erreur.
- ensure oxmysql est placé avant le framework.
- Les tables du framework apparaissent dans HeidiSQL ou DBeaver.
- Un export .sql récent est stocké hors du serveur.
Questions fréquentes
Faut-il installer MySQL sur le serveur FiveM ?
Non. La base est hébergée sur un serveur MariaDB séparé, inclus dans l’offre : vous la créez dans « Bases de données » et oxmysql s’y connecte par le réseau. MariaDB est compatible avec MySQL pour ESX, QBCore et Qbox.
Comment voir et modifier les tables ?
Connectez-vous depuis votre PC avec HeidiSQL ou DBeaver, en utilisant l’hôte, le port, l’utilisateur et le mot de passe affichés dans le panel. Faites un export avant toute modification à la main.
Peut-on utiliser une base de données externe ?
Oui. oxmysql se connecte à tout serveur MySQL ou MariaDB joignable depuis le serveur de jeu : indiquez son hôte et ses identifiants dans mysql_connection_string. Une base proche du serveur de jeu répond plus vite, ce qui compte pour les scripts qui l’interrogent souvent.
La console parle de requêtes lentes, que faire ?
oxmysql signale les requêtes plus longues que mysql_slow_query_warning (200 ms par défaut) et nomme la ressource en cause. Ajoutez un index sur la colonne qu’elle filtre, ou remplacez le script : une ressource qui interroge la base en boucle ralentit tout le serveur.