Comment installer et configurer oxmysql sur FiveM
Installez ou mettez à jour oxmysql sur votre serveur FiveM Linux, écrivez une chaîne de connexion MariaDB correcte, vérifiez la connexion et corrigez les erreurs les plus courantes.
Sur cette page
oxmysql est la ressource qui relie votre serveur FiveM à sa base de données. ESX Legacy, QBCore et de nombreux scripts en dépendent. Ce guide vous explique comment l'installer ou la mettre à jour, écrire la chaîne de connexion, vérifier qu'elle fonctionne et résoudre les erreurs fréquentes.
Prérequis
- Un serveur installé avec le guide Créer un serveur FiveM
- MariaDB installée, avec la base
fivemet l'utilisateurfivemcréés dans ce guide - Un accès à txAdmin, pour CFG Editor et Live Console
Vérifier ce qui est déjà installé
Les recettes ESX Legacy et QBCore installent déjà oxmysql. Repérez d'abord le dossier de votre serveur, dont le nom se termine par .base :
sudo find /home/fivem/txData -maxdepth 1 -type d -name '*.base'Si plusieurs dossiers apparaissent, le bon est celui de Server Data Folder, dans Settings, onglet FXServer. Ouvrez ensuite une session fivem et cherchez la ressource, en remplaçant NOM_DU_DOSSIER :
sudo -iu fivem
BASE=/home/fivem/txData/NOM_DU_DOSSIER.base
find "$BASE/resources" -type d -name oxmysql
grep -E "^version" "$(find "$BASE/resources" -type f -path '*/oxmysql/fxmanifest.lua' | head -n 1)"
exitNotez le chemin affiché. Sur les recettes ESX Legacy et QBCore, il s'agit de resources/[standalone]/oxmysql. Si find ne renvoie aucun chemin, oxmysql n'est pas installé et grep signale une erreur sans conséquence.
Installer ou mettre à jour oxmysql
Sauvegardez le serveur, installez unzip, puis arrêtez le service :
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivemDans la session fivem, téléchargez la dernière version et remplacez l'ancienne. Adaptez TARGET si le chemin relevé plus haut est différent :
BASE=/home/fivem/txData/NOM_DU_DOSSIER.base
TARGET="$BASE/resources/[standalone]/oxmysql"
TMP=$(mktemp -d "$HOME/oxmysql.XXXXXX")
curl -fL -o "$TMP/oxmysql.zip" https://github.com/overextended/oxmysql/releases/latest/download/oxmysql.zip
unzip -q "$TMP/oxmysql.zip" -d "$TMP"
grep -E "^version" "$TMP/oxmysql/fxmanifest.lua"
rm -rf "$HOME/oxmysql.previous"
[ -d "$TARGET" ] && mv "$TARGET" "$HOME/oxmysql.previous"
mkdir -p "$(dirname "$TARGET")"
mv "$TMP/oxmysql" "$TARGET"
rm -rf "$TMP"
ls "$TARGET"
exitLe dossier doit contenir fxmanifest.lua, dist et lib. L'ancienne version reste dans /home/fivem/oxmysql.previous, hors de resources pour que FXServer ne la charge pas.
Configurer server.cfg
Dans txAdmin, ouvrez CFG Editor. La chaîne de connexion doit être définie avant le démarrage des ressources :
set mysql_connection_string "mysql://fivem:MOT_DE_PASSE_GENERE@127.0.0.1/fivem?charset=utf8mb4"
ensure oxmysqlPlacez ensure oxmysql avant le framework et les ressources qui utilisent la base. La recette QBCore n'a pas cette ligne : elle démarre tout le dossier [standalone], et qb-core lance oxmysql comme dépendance. Inutile de l'ajouter dans ce cas.
Les deux formats de chaîne
oxmysql accepte deux écritures équivalentes :
set mysql_connection_string "mysql://fivem:MOT_DE_PASSE_GENERE@127.0.0.1:3306/fivem?charset=utf8mb4"
set mysql_connection_string "user=fivem;password=MOT_DE_PASSE_GENERE;host=127.0.0.1;port=3306;database=fivem;charset=utf8mb4"Ne gardez qu'une seule de ces lignes.
| Élément | Valeur | Remarque |
|---|---|---|
| Utilisateur | fivem |
N'utilisez pas root |
| Mot de passe | Valeur générée | Lettres et chiffres uniquement, avec openssl rand -hex 16 |
| Hôte | 127.0.0.1 |
Évite que localhost soit résolu en IPv6 alors que MariaDB écoute en IPv4 |
| Port | 3306 |
Facultatif si c'est le port par défaut |
| Base | fivem |
Ou fivem_rp si vous en avez créé une autre |
charset |
utf8mb4 |
Conserve les accents et les emojis |
La documentation d'oxmysql déconseille ces caractères dans les valeurs : ; , / ? : @ & = + $ #. Le plus simple est de ne pas en mettre dans le mot de passe.
Vérifier la connexion
Testez d'abord les identifiants directement avec MariaDB. La commande demande le mot de passe :
mariadb -h 127.0.0.1 -P 3306 -u fivem -p fivem -e "SELECT VERSION();"Si la version s'affiche, démarrez le serveur et cherchez le message de réussite d'oxmysql :
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.logSi vous avez seulement modifié server.cfg, redémarrez plutôt le serveur depuis txAdmin. Vérifiez enfin que la ressource est active :
curl -fsS http://127.0.0.1:30120/info.json | grep -o '"oxmysql"'Réglages utiles
Ces variables se placent dans server.cfg, avant ensure oxmysql, toujours avec set :
| Variable | Effet | Valeur par défaut |
|---|---|---|
mysql_slow_query_warning |
Seuil, en millisecondes, au-delà duquel une requête est signalée comme lente | 200 |
mysql_debug |
Affiche les requêtes dans la console | false |
mysql_ui |
Active l'interface de suivi en jeu, ouverte avec la commande /mysql |
false |
L'interface /mysql demande en plus la permission command.mysql : consultez Gérer les permissions ACE. La documentation d'oxmysql la réserve au développement ou aux serveurs avec peu de joueurs.
Pour suivre une seule ressource sans redémarrer, tapez dans Live Console, puis retirez-la une fois l'analyse finie :
oxmysql_debug add es_extended
oxmysql_debug remove es_extendedN'activez pas mysql_debug en permanence : les requêtes affichées peuvent contenir des données de joueurs et remplissent les journaux.
Revenir à la version précédente
sudo systemctl stop fivem.service
sudo -iu fivemBASE=/home/fivem/txData/NOM_DU_DOSSIER.base
TARGET="$BASE/resources/[standalone]/oxmysql"
rm -rf "$HOME/oxmysql.failed"
mv "$TARGET" "$HOME/oxmysql.failed"
mv "$HOME/oxmysql.previous" "$TARGET"
exitsudo systemctl start fivem.serviceEn cas de problème
Quand la connexion échoue, oxmysql affiche Unable to establish a connection to the database, suivi d'un code entre parenthèses. Retrouvez-le avec :
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.logUnable to establish a connection to the database (ECONNREFUSED)
MariaDB ne répond pas à l'adresse indiquée.
- Vérifiez le service avec
sudo systemctl status mariadb. - Vérifiez le port d'écoute avec
sudo ss -ltnp | grep ':3306'. - Si l'erreur mentionne
::1, remplacezlocalhostpar127.0.0.1dans la chaîne.
ER_ACCESS_DENIED_ERROR
Lisez bien le compte cité dans le message :
'fivem'@'localhost' (using password: YES): le mot de passe est incorrect. Comparez-le avec celui testé par la commandemariadb.'root'@'localhost' (using password: NO): oxmysql n'a pas lu votre chaîne et utilise sa valeur de repli. Vérifiez que la ligne s'écritset mysql_connection_string, qu'elle n'est pas commentée, et qu'elle se trouve avantensure oxmysql.'fivem'@'127.0.0.1': MariaDB ne rattache pas cette adresse au comptelocalhost, ce qui arrive notamment avec l'optionskip_name_resolve. Créez un compte pour cette adresse danssudo mariadb:
CREATE USER 'fivem'@'127.0.0.1' IDENTIFIED BY 'MOT_DE_PASSE_GENERE';
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'127.0.0.1';
FLUSH PRIVILEGES;ER_BAD_DB_ERROR
Le message Unknown database indique que la base n'existe pas. Comparez le nom de la chaîne avec la liste renvoyée par sudo mariadb -e "SHOW DATABASES;".
ER_DBACCESS_DENIED_ERROR
L'utilisateur existe mais n'a pas de droits sur cette base. Accordez-les dans sudo mariadb :
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;Le mot de passe contient des caractères spéciaux
Un : ou un / dans le mot de passe coupe la chaîne au mauvais endroit, et l'erreur annonce alors un hôte ou un utilisateur inattendu. Générez un nouveau mot de passe avec openssl rand -hex 16, appliquez-le dans sudo mariadb, puis mettez à jour server.cfg :
ALTER USER 'fivem'@'localhost' IDENTIFIED BY 'MOT_DE_PASSE_GENERE';Could not find dependency oxmysql for resource
La ressource citée a besoin d'oxmysql, qui est introuvable. Vérifiez que le dossier contient bien fxmanifest.lua directement, et non un sous-dossier oxmysql/oxmysql. Tapez ensuite refresh puis ensure oxmysql dans Live Console.
Resource 'oxmysql' can't run
Si la ligne suivante indique server needs to be 12913 or higher, mettez à jour FXServer, ou revenez à la version précédente d'oxmysql en attendant.
Table 'fivem.xxx' doesn't exist
Une ressource attend une table qui n'a pas été créée. Importez le fichier .sql fourni avec cette ressource, après une sauvegarde :
sudo mariadb fivem < /chemin/vers/fichier.sqltook 350.0000ms to execute a query
Ce message signale une requête lente, avec le nom de la ressource qui l'a lancée. Il est normal au démarrage et peut aussi venir d'un ralentissement général du serveur. S'il revient souvent en jeu pour la même ressource, suivez Diagnostiquer les crashs et lenteurs d'un serveur FiveM.
Conflit avec mysql-async ou ghmattimysql
oxmysql remplace ces deux ressources et répond à leur place. Retirez leur ligne ensure et supprimez leur dossier, après une sauvegarde.