Connecter la base de données (oxmysql)

Dès que votre serveur FiveM doit se souvenir de quelque chose — un personnage, de l’argent, un véhicule garé — il lui faut une base de données MySQL. Cette page vous accompagne de la création de la base jusqu’à la première ligne enregistrée, et liste les erreurs qui bloquent le démarrage. Elle suppose que votre serveur démarre déjà : sinon, voyez Installer un serveur FiveM.

La ressource qui fait le lien s’appelle oxmysql. C’est elle qui lit la chaîne de connexion et qui exécute les requêtes de tous vos scripts. Le nombre de bases de données incluses dépend de votre palier FiveM, de deux à quatre selon l’offre ; le détail figure sur la page FiveM.

Créer la base et l’utilisateur

Les bases se créent depuis le panel, dans la section dédiée de votre serveur. La procédure complète, commune à tous les jeux, est décrite dans Créer et gérer une base de données ; voici ce qu’il faut en retenir pour FiveM.

1. Connectez-vous à panel.cloudfive.xyz et ouvrez votre serveur FiveM.

2. Allez dans la section qui gère les bases de données et créez-en une. Un nom simple suffit : fivem, ou le nom de votre framework.

3. Relevez les cinq informations affichées sur la fiche de la base : l’hôte, le port, le nom de la base, le nom d’utilisateur et le mot de passe.

4. Notez le nom complet de la base et de l’utilisateur tels qu’ils apparaissent après création. Le panel y ajoute un préfixe : ce n’est pas le nom que vous avez tapé qui compte, c’est celui qui est affiché.

5. Gardez ces informations de côté : vous allez les recopier dans server.cfg, et le mot de passe n’est pas toujours réaffiché ensuite.

Une base par serveur

Ne partagez pas une même base entre deux serveurs FiveM. Les frameworks écrivent dans les mêmes tables sans se concerter : vous obtiendrez des personnages qui disparaissent et des soldes incohérents.

Construire la chaîne de connexion mysql_connection_string

Tout tient dans une ligne de server.cfg, à placer avant le ensure oxmysql. Le format recommandé est une URL :

server.cfg

set mysql_connection_string "mysql://utilisateur:motdepasse@hote:3306/nom_de_la_base?charset=utf8mb4"

ensure oxmysql

Un format à points-virgules existe aussi, accepté par oxmysql, et parfois plus simple quand le mot de passe contient des caractères inhabituels :

server.cfg — variante

set mysql_connection_string "server=hote;port=3306;uid=utilisateur;password=motdepasse;database=nom_de_la_base;charset=utf8mb4"

Remplacez chaque élément par ce que le panel affiche. Trois pièges :

• l’hôte n’est pas localhost. Recopiez l’adresse indiquée sur la fiche de la base, même si elle vous paraît étrange. localhost fonctionne par hasard sur certaines installations et jamais sur les autres ;
• les caractères spéciaux du mot de passe cassent le format URL. Un @, un :, un / ou un # dans le mot de passe doit être encodé (@ devient %40). Si vous n’êtes pas sûr, utilisez la variante à points-virgules, ou régénérez un mot de passe sans ces caractères ;
• ?charset=utf8mb4 n’est pas décoratif : sans lui, les accents et les emojis deviennent des caractères illisibles dans les noms de personnages et les messages.

Cette ligne contient un mot de passe

server.cfg est lisible par tous ceux qui ont accès à vos fichiers. Si vous partagez l’administration, donnez des accès nominatifs plutôt que votre compte — voir Gérer les sous-utilisateurs — et masquez cette ligne quand vous publiez votre configuration pour demander de l’aide.

Importer le fichier .sql du framework

Un framework (ESX, QBCore, VORP et les autres) livre un ou plusieurs fichiers .sql qui créent les tables. Sans cet import, le serveur démarre, oxmysql se connecte, et aucun joueur ne peut créer de personnage.

1. Repérez les fichiers .sql fournis. Ils sont souvent à la racine de la ressource du framework, dans un dossier sql ou database.

2. Lisez l’ordre d’import indiqué par l’auteur. Certains frameworks demandent un fichier de base puis des compléments, et l’ordre compte.

3. Importez le contenu dans la base que vous venez de créer, avec l’outil d’administration proposé depuis la fiche de la base dans le panel, ou avec un client MySQL depuis votre machine (HeidiSQL, DBeaver, ou la commande mysql) en utilisant l’hôte et le port affichés.

4. Vérifiez que des tables sont apparues. Une base vide après import signifie que l’import a échoué ou qu’il est parti dans une autre base.

5. Redémarrez le serveur et relisez la console.

Un import écrase les tables existantes

Les fichiers .sql de framework commencent souvent par supprimer les tables avant de les recréer. Lancé sur une base en production, l’import efface tous vos joueurs sans confirmation et sans retour possible. Exportez la base avant, systématiquement, et vérifiez deux fois sur quelle base vous êtes connecté.

Les accès distants ne sont pas toujours ouverts

Si votre client MySQL n’arrive pas à joindre l’hôte depuis votre ordinateur, ce n’est pas forcément une erreur de mot de passe. Passez par l’outil d’administration du panel, ou demandez l’ouverture de l’accès par ticket en précisant votre adresse IP.

Vérifier la connexion au démarrage

Au démarrage, oxmysql annonce son état dans la console. Trois lectures possibles :

Ce que vous voyez	Ce que ça veut dire
Une ligne de connexion réussie mentionnant la base et la version de MySQL	C’est bon, passez au framework
Une erreur d’accès ou de connexion refusée	Identifiants ou hôte faux — voir plus bas
Rien du tout au sujet d’oxmysql	La ressource n’est pas déclarée, ou set mysql_connection_string est écrit après le ensure oxmysql

La vérification qui compte vraiment, elle, se fait en jeu : connectez-vous, créez un personnage, déconnectez-vous, reconnectez-vous. Si votre personnage est toujours là, la chaîne complète fonctionne. txAdmin vous évite de passer par le jeu pour relire les derniers messages du serveur.

Erreurs fréquentes et sauvegardes

« Access denied for user ». Le couple utilisateur / mot de passe ne passe pas. Recopiez-les depuis la fiche de la base plutôt que de les retaper, et vérifiez qu’aucun espace ne s’est glissé au début ou à la fin.

« Unknown database ». Le nom de la base est incomplet : vous avez écrit le nom choisi au lieu du nom réel avec son préfixe.

« ECONNREFUSED » ou une erreur de délai dépassé. L’hôte ou le port sont faux. C’est quasi toujours un localhost laissé dans la chaîne de connexion.

« Table … doesn’t exist ». La connexion fonctionne, mais le .sql n’a pas été importé, ou il a été importé dans une autre base. Reprenez la section d’import.

Des ? ou des caractères bizarres à la place des accents. Le charset=utf8mb4 manque. Ajoutez-le ; les données déjà enregistrées de travers, elles, resteront abîmées.

« Too many connections » ou des requêtes qui ralentissent avec le monde. Un script interroge la base en boucle. C’est un problème de performance plus que de configuration : voyez Optimiser les performances de son serveur FiveM.

Sauvegarder la base

Point important et souvent découvert trop tard : les sauvegardes du panel archivent les fichiers de votre serveur, pas le contenu de votre base MySQL. Une restauration vous rendra vos ressources et votre server.cfg, pas vos joueurs.

Prenez donc l’habitude d’exporter la base vous-même : avant chaque mise à jour de framework, avant chaque import .sql, et à intervalle régulier le reste du temps. Un export est un fichier .sql que vous conservez ailleurs que sur le serveur — un disque perdu emporte les deux sinon. Gardez au moins les deux ou trois derniers exports : une base corrompue depuis une semaine ne se répare pas avec une sauvegarde de la veille.