La base de données sans douleur

ESX, QBCore et Qbox stockent tout dans une base de données : personnages, argent, véhicules, inventaires. Sans base, pas de ville. Sur TeamKit, la base existe déjà quand tu reçois ton serveur. Ce chapitre t'explique ce que tu as, comment y mettre les tables de ton framework, comment la relier au serveur, et comment ne jamais la perdre.

Ce que TeamKit te fournit #

Chaque serveur reçoit une base et un utilisateur, sur une instance partagée avec les autres serveurs. Tu ne vois que ta base, les autres ne voient pas la tienne.

Ton tableau de bord teamkit.fr affiche tout ce qu'il te faut, dans le bloc base de données :

Deux conséquences pratiques : si tu changes ton mot de passe AMP, la chaîne de connexion change aussi ; et tu n'as rien à créer (base, utilisateur, droits), l'interface web suffit pour tout ce chapitre.

✅ À retenir : hôte local + port de l'instance + utilisateur + nom de base sont sur le tableau de bord ; le mot de passe est celui d'AMP.

MariaDB ou MySQL 8.4 : lequel tu as, et pourquoi ça compte #

TeamKit fait tourner deux moteurs. Le premier, MySQL 8.4, est l'historique. Le second, MariaDB, est celui recommandé pour FiveM. Ton tableau de bord indique lequel porte ta base.

La raison n'est pas une préférence : les fichiers .sql livrés avec les packs FiveM sont écrits pour MariaDB, et MySQL 8.4 refuse quatre constructions qu'on y trouve partout.

Ce ne sont pas des bugs des packs. Qbox est explicite : MySQL n'est pas supporté, MariaDB 10.9 minimum (https://docs.qbox.re/installation). oxmysql dit la même chose : MariaDB est « fortement recommandé » pour la compatibilité et les performances (https://overextended.dev/oxmysql).

Selon ton cas :

1. Ta base est en MariaDB : continue.
2. Ta base est en MySQL 8.4 et tu n'as rien importé : demande au staff une base MariaDB avant de commencer.
3. Ta base est en MySQL 8.4 et ta ville tourne déjà : ne change rien tant que ça marche. Le jour où un import échoue sur l'une des quatre constructions, tu sauras pourquoi.

✅ À retenir : MariaDB pour FiveM. Un import qui échoue sur DEFAULT, IF NOT EXISTS ou STORED vient du moteur, pas du pack.

Ouvrir l'interface web #

L'interface web est Adminer, sur https://db.teamkit.fr. Le tableau de bord t'y envoie avec un lien pré-rempli : le serveur (hôte local et port), ton utilisateur et ta base sont déjà dans le formulaire.

1. Clique sur le lien « interface web » du bloc base de données.
2. Vérifie que le champ Serveur contient bien l'hôte local et le port de ton instance, puis tape ton mot de passe (celui d'AMP). Ne touche pas aux autres champs.
3. Sélectionne ta base dans la colonne de gauche. Elle est vide au début : c'est normal.

Adminer est plus sobre que phpMyAdmin, mais tu y trouves la même chose : la liste des tables, un onglet Importer (« Importer » dans la colonne de gauche), un onglet Exporter, et un champ « Requête SQL » pour taper une commande.

Importer un fichier .sql #

Un .sql est la liste des tables à créer. Tu l'importes une fois, avant le premier démarrage de la ressource.

1. Ouvre l'interface web et sélectionne ta base.
2. Clique sur l'onglet Importer.
3. Choisis le fichier .sql sur ton PC (par exemple qbx_core.sql, ou es_extended.sql pour ESX).
4. Laisse le jeu de caractères sur utf8mb4 ou utf-8.
5. Lance l'import et lis le message de fin : il doit indiquer que l'import s'est terminé sans erreur.
6. Vérifie dans la colonne de gauche que les tables attendues sont apparues (players, bans… pour Qbox ; users, owned_vehicles… pour ESX).

Deux règles d'ordre :

• Le .sql du framework en premier : les tables des autres ressources pointent souvent vers players ou users par une clé étrangère.
• Le .sql d'une ressource quand tu installes la ressource, pas tous d'un coup : tu ne saurais plus lesquels sont passés.

Si le fichier est gros #

L'interface web a une limite de taille par envoi, affichée sur l'onglet Importer. Un .sql de framework passe toujours ; un export complet de ville peut dépasser. Dans ce cas :

1. Ouvre le .sql dans un éditeur capable de gérer les gros fichiers (Notepad++ ou VS Code, pas le Bloc-notes).
2. Découpe-le en plusieurs fichiers, entre deux instructions : juste après un ; en fin de ligne, jamais au milieu d'un INSERT.
3. Importe les morceaux dans l'ordre : d'abord les CREATE TABLE, puis les INSERT.

Si tu importes deux fois le même fichier, tu obtiens « Table 'players' already exists » (erreur 1050). Sans gravité : le premier import a réussi, le second ne fait rien.

✅ À retenir : onglet Importer, le framework d'abord, un .sql par ressource au moment où tu l'installes.

Exporter et sauvegarder régulièrement #

Rappel du chapitre 01 : un serveur inactif est libéré et son instance supprimée. Ta base part avec. Les sauvegardes sont ton affaire. Le Backups d'AMP sauvegarde les fichiers de l'instance, pas la base : la base vit sur une autre instance.

1. Ouvre l'interface web et sélectionne ta base.
2. Clique sur l'onglet Exporter.
3. Choisis la méthode rapide, format SQL, toutes les tables.
4. Lance l'export : ton navigateur télécharge un fichier .sql.
5. Renomme-le avec la date : tk_ville_2026-09-07.sql.
6. Range-le hors de ton serveur : sur ton PC et, en plus, sur un stockage en ligne. Jamais dans un dossier de ressource.

Ce fichier suffit à recréer ta ville sur n'importe quelle base MariaDB vide : un import, et tout revient.

✅ À retenir : Exporter → SQL → toutes les tables → fichier daté, rangé sur ton PC et en ligne. Backups AMP ne couvre pas la base.

La chaîne de connexion et ses paramètres #

C'est la ligne qui dit à oxmysql où est ta base. Elle va dans Configuration → FiveM → Additional Server Settings :

set mysql_connection_string "mysql://UTILISATEUR:MOT_DE_PASSE@HOTE:PORT/BASE?charset=utf8mb4"

Chaque morceau, dans l'ordre :

Le tableau de bord te donne la chaîne prête, sans le mot de passe et sans ?charset=utf8mb4. Complète-la.

Si ton mot de passe contient un caractère spécial #

Dans la forme mysql://…, oxmysql ne sait pas lire les caractères ; , / ? : @ & = + $ # dans un mot de passe (source : https://overextended.dev/oxmysql). Ton mot de passe est celui d'AMP : si tu ne peux pas le changer, utilise la seconde forme, à points-virgules, qui accepte tout sauf le point-virgule :

set mysql_connection_string "user=UTILISATEUR;password=MOT_DE_PASSE;host=HOTE;port=PORT;database=BASE;charset=utf8mb4"

Les deux formes sont équivalentes. Choisis-en une, pas les deux.

Où placer la ligne #

AMP écrit Additional Server Settings après les ensure (chapitre 07, section 4). Pour oxmysql, la ligne y fonctionne sur les serveurs TeamKit existants. Si malgré une chaîne juste la console parle de localhost:3306, oxmysql a démarré sans lire ta ligne : déplace-la en tête de Starting Resources, avant le premier ensure, et redémarre.

✅ À retenir : cinq valeurs du tableau de bord + ton mot de passe AMP + ?charset=utf8mb4. Caractère spécial dans le mot de passe = forme à points-virgules.

oxmysql : les réglages utiles #

oxmysql exécute les requêtes pour ESX Legacy, QBCore et Qbox. Elle démarre en premier (ensure oxmysql avant ox_lib et le framework). Quand tout va bien, elle écrit une seule ligne :

[oxmysql] Database server connection established!

Elle se règle par des convars, à placer avec les autres en tête de Starting Resources (source : https://overextended.dev/oxmysql et le code de la ressource) :

Exemple pour diagnostiquer un script lent, sans noyer la console :

set mysql_slow_query_warning 100
set mysql_debug ["qbx_garages"]

Tu peux aussi changer le débogage à chaud, dans la console AMP, sans redémarrer :

oxmysql_debug add qbx_garages
oxmysql_debug remove qbx_garages

Remets mysql_debug à false (ou retire la ligne) quand tu as fini : en production, ça remplit la console pour rien.

✅ À retenir : mysql_slow_query_warning pour repérer un script lourd, mysql_debug avec une liste de ressources pour voir ses requêtes, et on l'éteint après.

Les erreurs et leur cause exacte #

Ces lignes apparaissent dans la console AMP au démarrage d'oxmysql. Chacune a une cause précise, et une seule.

Après chaque correction : redémarre l'instance. server.cfg est réécrit au démarrage ; un ensure oxmysql seul ne relit pas la nouvelle chaîne.

✅ À retenir : 1045 = identifiants ou hôte, ECONNREFUSED = hôte ou port, localhost:3306 = chaîne pas lue, 1049 = nom de base, 1146 = .sql pas importé.

Un plan de sauvegarde qui tient #

Une sauvegarde de base prend une minute. Une ville perdue, des semaines. Le plan minimal :

1. Avant chaque gros changement (migration d'inventaire, gros script économique, mise à jour de qbx_core ou es_extended) : exporte. Si le changement casse quelque chose, tu reviens en arrière par un import.
2. Avant un wipe (remise à zéro de la ville) : exporte, puis vérifie que le fichier s'ouvre et contient tes tables, avant de vider quoi que ce soit.
3. Une fois par semaine tant que la ville est ouverte : exporte, date, range. Garde les quatre dernières.
4. Dès l'avertissement d'inactivité TeamKit (7 jours, 14 pour une communauté vérifiée) : exporte. Si le serveur est libéré, tu repartiras de là.
5. Après un import de sauvegarde : redémarre, connecte-toi, vérifie qu'un personnage retrouve son argent et ses véhicules.

Pour restaurer : vide la base (sélectionne toutes les tables, supprime), importe le fichier daté, redémarre l'instance. Ne mélange jamais un import de sauvegarde avec des tables déjà pleines : tu aurais des doublons de clés.

Deux erreurs à éviter : ranger le .sql sur le serveur (il partirait avec l'instance à sa suppression), et tester une restauration pour la première fois le jour où tu en as besoin.

✅ À retenir : export avant chaque gros changement, avant chaque wipe, chaque semaine, et dès l'avertissement d'inactivité. Fichier daté, rangé sur ton PC et en ligne.

✅ Checklist du chapitre #

• Tu as relevé sur le tableau de bord : hôte local, port, utilisateur, nom de base.
• Tu sais que ton mot de passe de base est celui d'AMP.
• Tu as vérifié le moteur : MariaDB (sinon, demande faite au staff avant tout import).
• L'interface web s'ouvre et montre ta base, vide ou avec tes tables.
• Le .sql du framework est importé, puis ceux des ressources installées.
• mysql_connection_string est dans Additional Server Settings, avec le port de l'instance et ?charset=utf8mb4.
• La console affiche « Database server connection established! ».
• Tu as fait un premier export et rangé le fichier daté hors du serveur.
• Tu as noté les quatre moments où tu exportes : gros changement, wipe, chaque semaine, avertissement d'inactivité.

❓ Si ça ne marche pas #

« Access denied for user » (1045) alors que tu as recopié le tableau de bord : le mot de passe a changé côté AMP, ou tu as collé un espace en fin de ligne. Retape la ligne entière à la main, sans copier-coller le mot de passe depuis un gestionnaire qui ajoute un retour à la ligne.

« ECONNREFUSED » alors que l'hôte est bon : tu as mis 3306 par réflexe. Le port est celui de ton instance, sur le tableau de bord.

L'import s'arrête sur une erreur 1064 à la ligne d'un DEFAULT ou d'un IF NOT EXISTS : tu es sur MySQL 8.4. Demande une base MariaDB au staff, puis importe sur celle-ci. Ne corrige pas le fichier à la main : le prochain pack refera la même erreur.

Le serveur démarre, la base répond, mais les personnages ne se sauvegardent pas : ER_NO_SUCH_TABLE plus haut dans la console. Le .sql du framework n'est pas importé, ou importé dans une autre base.

Tu as importé une sauvegarde et tout est en double : tu as importé par-dessus des tables pleines. Vide la base, réimporte le seul fichier de sauvegarde, redémarre.

Pour tout le reste, chapitre 08 : Dépannage.