Sauvegarder et restaurer la base de données MySQL d'un serveur FiveM

Sur un serveur FiveM, la base de données contient ce qu'aucune archive de fichiers ne remplacera : les comptes joueurs, les personnages, l'argent, les véhicules, les propriétés et l'historique laissé par vos scripts. Une copie régulière reste la seule protection contre une migration de schéma ratée, un plugin qui vide une table ou une mise à jour d'ESX Legacy ou d'ox_core qui tourne mal. Ce tutoriel détaille la sauvegarde de la base MySQL ou MariaDB d'un serveur FiveM en ligne de commande, le contrôle du fichier produit, puis la restauration complète des données.

Ce que la sauvegarde doit réellement couvrir

Avant de lancer la moindre commande, identifiez le périmètre. Sauvegarder la base de données du jeu ne remplace pas la sauvegarde des fichiers du serveur. MariaDB est un SGBDR, un système de gestion de base de données relationnelles, et c'est lui qui héberge les données du jeu : comptes et identifiants de connexion, personnages et apparences, inventaires, argent en banque et en liquide, véhicules possédés, propriétés, entreprises, sanctions et journaux de modération. Les scripts et les plugins ESX qui écrivent dans ces tables sont nombreux, et une seule table incohérente suffit à bloquer le démarrage du serveur.

Les ressources (scripts, mappings, configuration) se sauvegardent séparément, tout comme la couche propre au panneau d'administration. Si vous utilisez Pterodactyl, les bases de données du panneau et du jeu sont deux objets distincts : notre guide sur les sauvegardes Pterodactyl et la restauration d'un serveur traite cette couche-là, tandis que cette page se concentre sur la base utilisée par vos ressources de jeu.

Choisir un moteur de base de données compatible

La documentation d'oxmysql, le pilote MySQL utilisé par la majorité des serveurs FiveM modernes, recommande MariaDB plutôt que MySQL 8. Deux raisons concrètes y sont citées : MySQL 8 introduit davantage de mots réservés, comme stored ou group, et il refuse les valeurs par défaut sur les colonnes de type longtext ou JSON. Des ressources écrites à l'origine pour MySQL 5.7 peuvent donc échouer sur MySQL 8 alors qu'elles fonctionnent sans modification sur MariaDB.

Sur un VPS ou un serveur dédié sous Ubuntu ou Debian, MariaDB s'installe depuis les paquets (packages) de la distribution, ce qui facilite ensuite les mises à jour de sécurité. Autre point souvent mal compris : n'installez pas XAMPP uniquement pour faire tourner la base d'un serveur en production. La documentation d'oxmysql est explicite, XAMPP est une pile destinée au développement local, et l'installation directe de MariaDB est la solution prévue.

Se connecter au serveur de la base de données

La plupart des opérations d'administration se font en SSH, directement sur la machine qui héberge la base, depuis un shell sur votre poste ou depuis le terminal intégré de votre panneau de contrôle. Connectez-vous avec votre compte, puis passez en root ou utilisez sudo uniquement pour les commandes qui en ont réellement besoin. Pour ouvrir une session SQL en tant qu'administrateur de la base, la commande habituelle est mariadb -u root -p : le mot de passe root de MariaDB est distinct de celui de votre compte système, et il ne doit pas être confondu avec les identifiants utilisés par le serveur de jeu.

Depuis cette session, deux vérifications sont immédiates : SHOW DATABASES; pour retrouver le nom exact de la base, puis SHOW TABLES; pour compter les tables avant et après une restauration. Si vous préférez une interface graphique, une solution comme phpMyAdmin, installée sur la même machine et accessible seulement en local, permet d'administrer la base, de parcourir les tables, d'exporter une table isolée et de contrôler un import sans écrire de requête. Ces gestes relèvent de la gestion de bases de données au quotidien, et les administrateurs qui débutent sur FiveM y gagnent un moyen simple de vérifier l'état réel des données.

Pour la tâche de sauvegarde elle-même, créez un compte MySQL dédié plutôt que d'utiliser root : un compte dédié doté des seuls droits de lecture, sur les tables de la base du jeu, limite les dégâts en cas de fuite d'identifiants. L'authentification de ce compte se fait avec un nom d'utilisateur et un mot de passe stockés dans le fichier de configuration de la tâche, avec des droits restreints sur le fichier.

Retrouver le nom de la base et les identifiants

Le serveur de jeu lit ses identifiants dans son fichier de configuration. La directive attendue par oxmysql prend l'une de ces deux formes :

set mysql_connection_string "mysql://utilisateur:motdepasse@localhost:3306/nom_de_la_base"
set mysql_connection_string "user=utilisateur;password=motdepasse;host=localhost;port=3306;database=nom_de_la_base"

Deux règles sont rappelées par la documentation : utilisez toujours la directive set, et déclarez la chaîne de connexion avant le démarrage des ressources qui en dépendent. La ressource oxmysql doit elle aussi être démarrée en haut de la liste, avant les scripts qui l'appellent. Notez le nom exact de la base, le nom d'utilisateur et le mot de passe : ce sont les mêmes informations que la restauration devra reproduire.

Pendant un diagnostic, la journalisation des requêtes lentes aide à comprendre ce qui charge la base. La documentation d'oxmysql documente le réglage set mysql_slow_query_warning 150, exprimé en millisecondes, qui fait apparaître un avertissement lorsqu'une requête dépasse ce seuil. Une requête lente n'indique pas forcément un problème de base de données, mais elle oriente le diagnostic.

Produire un dump avec mariadb-dump

L'outil de référence est mariadb-dump. Il génère un fichier contenant les instructions SQL nécessaires pour recréer la base, ses tables et leurs données. Sur les installations anciennes, le même binaire reste accessible sous le nom mysqldump grâce à un lien symbolique, mais ce lien est déprécié depuis MariaDB 11.0 et a été retiré de l'image Docker officielle : sur une installation récente, utilisez mariadb-dump et vérifiez la liste des options disponibles avec mariadb-dump --help.

La commande suivante produit le dump d'une base unique :

mariadb-dump --single-transaction --routines --events --triggers \
  -u utilisateur -p nom_de_la_base > /var/sauvegardes/fivem-backup-$(date +%F-%H%M).sql

Chaque option répond à un besoin précis, documenté par MariaDB :

• --single-transaction envoie une transaction avant la lecture des données et produit un état cohérent de la base sans bloquer les applications, à condition que les tables soient transactionnelles, ce qui est le cas du moteur InnoDB utilisé par défaut.
• --routines et --events sont nécessaires parce que les procédures stockées, les vues et les événements ne sont pas inclus par défaut dans le dump, contrairement aux déclencheurs qui font partie de la définition des tables.
• --triggers rend explicite l'inclusion de ces déclencheurs, option désactivable si vous préférez un dump limité aux tables et aux données.

Pour configurer l'opération, rien de compliqué : la commande s'écrit dans un fichier de script, avec les identifiants du compte dédié, et c'est ce fichier que le planificateur appellera. Vérifiez la config une fois, puis n'y touchez plus.

Cohérence et performance du dump

Un dump n'est utile que s'il représente un instant unique. Si le serveur continue d'écrire pendant la copie, un joueur peut perdre de l'argent dans une table et le récupérer dans une autre. MariaDB documente justement --single-transaction comme la solution adaptée aux tables InnoDB, parce qu'elle évite de verrouiller les tables comme le ferait --lock-tables.

Deux réglages complémentaires figurent dans la documentation de mariadb-dump. D'une part, l'option --quick, activée par défaut via --opt, lit les tables ligne par ligne au lieu de charger une table entière en mémoire : c'est indispensable sur les grosses tables d'inventaires ou de véhicules, et cela limite la consommation de RAM sur un VPS modeste. D'autre part, l'outil travaille sur un seul thread et sollicite peu le processeur, mais écrire le fichier sur le même disque que la base ajoute des entrées et sorties aléatoires. Écrire la sauvegarde ailleurs, sur un volume distinct ou vers un serveur de base de données dédié, limite cet effet.

Vérifier un dump avant de compter dessus

Un fichier de taille correcte n'est pas une preuve. Deux contrôles rapides suffisent : regardez la fin du fichier, un dump complet se termine par la remise en état des privilèges et non au milieu d'une insertion, puis comparez le nombre de tables annoncées dans l'en-tête avec la liste obtenue par un SHOW TABLES; sur la base en production. Une seconde vérification consiste à importer le dump dans une base de test placée sur une autre machine : c'est le seul contrôle qui prouve que le fichier est réellement exploitable.

Planifier la sauvegarde sans saturer le serveur

Une tâche planifiée quotidienne, complétée par un export manuel avant chaque mise à jour majeure de ressources, couvre la majorité des incidents. Écrivez le script dans un fichier dédié, appelez-le par cron à une heure creuse, et conservez plusieurs générations : les points récents pour revenir en arrière vite, un point hebdomadaire pour les erreurs découvertes tardivement. La règle importante reste de ne pas laisser la seule copie sur la machine qu'elle protège.

Chaque exécution doit produire une trace lisible. Redirigez la sortie du script vers un fichier de log, par exemple dans le même dossier que la sauvegarde, et vérifiez le contenu de ce journal plutôt que le seul code de retour. Les logs de MariaDB restent utiles de leur côté pour comprendre un échec côté serveur : journalctl -u mariadb affiche les messages du service et permet de repérer un espace disque saturé ou une coupure pendant le dump. Une sauvegarde silencieusement vide est plus dangereuse qu'une absence de sauvegarde, parce qu'elle donne une fausse assurance. Notre article sur les sauvegardes et la haute disponibilité d'un serveur dédié détaille cette logique de copies multiples et de conservation hors site.

Restaurer la base de données

La restauration rejoue le contenu du dump sur un serveur MariaDB. Le client en ligne de commande, nommé mariadb avec mysql conservé comme lien symbolique sur les systèmes Unix, sait exécuter un fichier de script :

mariadb -u utilisateur -p nom_de_la_base < /var/sauvegardes/fivem-backup-2026-09-20-0400.sql

Trois précautions évitent d'aggraver l'incident. Arrêtez d'abord le serveur de jeu, sinon les ressources et leurs connexions continuent d'écrire pendant la restauration. Faites ensuite une copie de l'état actuel avant d'écraser quoi que ce soit : si l'import est interrompu, vous conservez de quoi analyser la cause. Restaurez enfin sur une base de test quand c'est possible, surtout si la structure du schéma a changé entre la date de la sauvegarde et le moment de la restauration.

Si la base n'existe plus du tout, il faut d'abord créer une base de données vide, puis attribuer les droits au compte utilisé par le serveur de jeu avant de rejouer le dump :

CREATE DATABASE nom_de_la_base CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON nom_de_la_base.* TO 'utilisateur'@'localhost';
FLUSH PRIVILEGES;

Sur une base volumineuse, l'import sollicite le disque et la RAM pendant plusieurs minutes, en particulier lorsque le dump contient des tables d'inventaires très larges : lancez l'opération à un moment calme et évitez un restart du service MariaDB au milieu de l'import. Si un redémarrage est nécessaire après l'opération, systemctl restart mariadb suffit à repartir sur une base propre. Une fois la restauration terminée, contrôlez que les tables et les comptes joueurs sont présents, puis pensez à redémarrer le serveur de jeu. Ce démarrage constitue le dernier contrôle : les ressources qui accèdent à la base doivent se connecter sans erreur et sans avertissement de requête lente anormal.

Restauration et migration vers un autre hébergeur

Le même dump sert à changer de machine. Vous pouvez alors restaurer la base sur le nouveau serveur, reprendre le fichier de configuration avec la nouvelle adresse, et valider la connexion avant d'annoncer le transfert aux joueurs. Notre guide pour migrer un serveur FiveM d'un hébergeur à un autre détaille les étapes de bascule, et la page sauvegarde et réversibilité rappelle ce que vous êtes en droit d'exporter de votre hébergement.

Erreurs fréquentes

• Confondre la sauvegarde du panneau d'administration et celle de la base du jeu FiveM, puis restaurer la mauvaise archive.
• Sauvegarder sans jamais tester une restauration, et découvrir un dump inutilisable le jour de l'incident.
• Oublier --routines ou --events, et perdre des procédures stockées ou des événements planifiés.
• Laisser la seule copie sur le disque qui héberge la base.
• Restaurer sur une version de MariaDB ou de MySQL incompatible sans vérifier les prérequis du schéma.
• Utiliser un moteur MySQL 8 avec des ressources conçues pour MySQL 5.7 ou MariaDB, puis chercher l'origine des erreurs ailleurs.
• Confondre le mot de passe root de la base et le mot de passe de votre compte système, puis verrouiller l'accès administrateur.

Checklist avant remise en ligne

1. Le serveur de jeu est arrêté pendant toute l'opération.
2. La base restaurée contient les tables attendues et les comptes joueurs.
3. Le fichier de configuration pointe vers la bonne base et le bon nom d'utilisateur.
4. Les ressources démarrent sans erreur de connexion et la connexion des joueurs est testée.
5. La tâche de sauvegarde suivante s'exécute et son log est lu, pas seulement son code de retour.

À voir aussi

Une base saine ne dispense pas d'un serveur correctement dimensionné. Le guide sur l'optimisation des performances d'un serveur FiveM traite cette partie, et l'installation d'ESX Legacy montre comment le schéma initial est créé et peuplé.