Connecter MySQL à un serveur FiveM avec oxmysql

Un serveur FiveM en roleplay ne tient pas sans base de données : joueurs, véhicules, inventaires, argent, tout y est stocké. oxmysql est la ressource qui fait le lien entre vos scripts et MySQL. Ce guide couvre l'installation, la chaîne de connexion et l'ordre de démarrage - les trois points où tout se joue.

⚙️ Prérequis

• Un serveur FiveM Lordhosting, accessible depuis le panel
• Une base MySQL ou MariaDB avec son utilisateur et son mot de passe
• Un framework installé : ESX ou QBCore - voir ESX ou QBCore
• Un accès SFTP ou le gestionnaire de fichiers du panel

⚙️ 1. Installer oxmysql

Téléchargez la dernière version depuis le dépôt overextended/oxmysql (le fichier oxmysql.zip de la page Releases, pas l'archive du code source). Décompressez-la, puis déposez le dossier dans resources/ :

resources/
  ├── [standalone]/
  │     └── oxmysql/
  ├── [core]/
  └── [scripts]/

Le nom du dossier doit rester exactement oxmysql : les autres ressources l'appellent par ce nom.

⚙️ 2. Écrire la chaîne de connexion

Dans server.cfg, ajoutez la ligne suivante avant tout ensure :

set mysql_connection_string "mysql://utilisateur:motdepasse@127.0.0.1:3306/fivem?charset=utf8mb4"

La syntaxe par paires est également acceptée, plus lisible quand le mot de passe contient des caractères spéciaux :

set mysql_connection_string "server=127.0.0.1;database=fivem;userid=utilisateur;password=motdepasse;charset=utf8mb4"

⚙️ 3. Respecter l'ordre de démarrage

oxmysql doit être chargé avant le framework, qui doit l'être avant les scripts :

ensure oxmysql
ensure es_extended      # ou qb-core
ensure votre-script

Un ensure oxmysql placé après le framework produit l'erreur oxmysql was not found, même si la ressource est bien installée. C'est de loin la cause la plus fréquente.

⚙️ 4. Importer le schéma du framework

Chaque framework fournit ses fichiers .sql. Importez-les dans l'ordre indiqué par sa documentation, avec phpMyAdmin ou en ligne de commande :

mysql -u utilisateur -p fivem < es_extended.sql

Vérifiez ensuite que les tables sont bien là :

SHOW TABLES;
SELECT COUNT(*) FROM users;

Une base vide au démarrage du framework produit des erreurs Unknown column à la première connexion d'un joueur.

⚙️ 5. Vérifier la connexion

Démarrez le serveur et lisez la console. oxmysql annonce clairement son état :

[oxmysql] Database server connection established

Depuis la console serveur, deux commandes utiles :

set mysql_debug true

Le mode debug journalise chaque requête avec sa durée - précieux pour repérer un script qui interroge la base en boucle. Désactivez-le en production, il remplit les journaux.

⚙️ 6. Résoudre les erreurs courantes

• Unable to establish a connection to the database : identifiants ou nom de base erronés. Testez-les avec un client MySQL depuis la même machine.
• oxmysql was not found : ordre de démarrage, ou dossier mal nommé.
• ER_NOT_SUPPORTED_AUTH_MODE : l'utilisateur MySQL 8 utilise caching_sha2_password. Basculez-le en mysql_native_password.
• Too many connections : une ressource ouvre des connexions sans les rendre. Le mode debug identifie la coupable.
• Accents cassés en jeu : charset=utf8mb4 absent de la chaîne de connexion.

⚙️ Configuration prête à copier-coller

Trois blocs : la base, la ressource, le contrôle.

1. Créer la base, sur le serveur MySQL - remplacez le mot de passe par un mot de passe généré (openssl rand -base64 24) :

CREATE DATABASE IF NOT EXISTS fivem
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'fivem'@'localhost' IDENTIFIED BY 'MON_MOT_DE_PASSE';
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;

2. Le bloc server.cfg, dans cet ordre exact - la chaîne de connexion avant tout ensure, oxmysql avant le framework, le framework avant les scripts :

# ---- Base de données ------------------------------------------------------
# Forme par paires : préférable dès que le mot de passe contient @ : / ou #
set mysql_connection_string "server=127.0.0.1;database=fivem;userid=fivem;password=MON_MOT_DE_PASSE;charset=utf8mb4"

# ---- Ordre de démarrage --------------------------------------------------
ensure oxmysql          # toujours en premier
ensure es_extended      # ou qb-core
ensure votre-script     # vos ressources ensuite

3. Le contrôle, console serveur au démarrage :

# La ligne attendue dans la console
[oxmysql] Database server connection established

# Mesurer les requêtes lentes le temps d'un diagnostic
set mysql_debug true

Et le test hors du jeu, qui distingue un problème d'identifiants d'un problème de ressource :

# Si cette commande passe, la base et le compte sont bons :
# le reste est un problème de server.cfg ou d'ordre de démarrage
mysql -u fivem -p -h 127.0.0.1 fivem -e "SELECT COUNT(*) FROM users;"

✅ Conclusion

Votre base est reliée à FiveM, le schéma est importé et l'ordre de démarrage est correct. Poursuivez avec la configuration de server.cfg et l'installation de txAdmin pour l'administration au quotidien.

Nos serveurs FiveM incluent une base MySQL sur la même infrastructure : la latence entre le serveur de jeu et la base reste sous la milliseconde.