FR

Serveurs de jeux

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.

7 min de lecture, mis à jour le 18 novembre 2026

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 fivem et l'utilisateur fivem créé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 :

Terminal
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 :

Terminal
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)"
exit

Notez 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 :

Terminal
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivem

Dans 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 :

Terminal
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"
exit

Le 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 :

Texte
set mysql_connection_string "mysql://fivem:MOT_DE_PASSE_GENERE@127.0.0.1/fivem?charset=utf8mb4"

ensure oxmysql

Placez 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 :

Texte
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 :

Terminal
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 :

Terminal
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.log

Si vous avez seulement modifié server.cfg, redémarrez plutôt le serveur depuis txAdmin. Vérifiez enfin que la ressource est active :

Terminal
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 :

Texte
oxmysql_debug add es_extended
oxmysql_debug remove es_extended

N'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

Terminal
sudo systemctl stop fivem.service
sudo -iu fivem
Terminal
BASE=/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"
exit
Terminal
sudo systemctl start fivem.service

En 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 :

Terminal
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.log

Unable 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, remplacez localhost par 127.0.0.1 dans 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 commande mariadb.
  • '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'écrit set mysql_connection_string, qu'elle n'est pas commentée, et qu'elle se trouve avant ensure oxmysql.
  • 'fivem'@'127.0.0.1' : MariaDB ne rattache pas cette adresse au compte localhost, ce qui arrive notamment avec l'option skip_name_resolve. Créez un compte pour cette adresse dans sudo mariadb :
SQL
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 :

SQL
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 :

SQL
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 :

Terminal
sudo mariadb fivem < /chemin/vers/fichier.sql

took 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.