1. C'est quoi MongoDB ?

MongoDB est une base de données NoSQL orientée documents : au lieu de tableaux aux colonnes fixes, elle stocke des documents au format JSON, et chaque document peut avoir ses propres champs. On l'interroge avec des fonctions JavaScript plutôt qu'avec du SQL.

MongoDB est un bon choix quand vos données changent souvent de forme ou s'imbriquent naturellement : profils de joueurs avec inventaire, configurations par serveur Discord, journaux d'événements, catalogues de produits aux caractéristiques variées.

💡

MongoDB ou MariaDB ? Pour des données très structurées et liées entre elles (factures, comptabilité, WordPress), MariaDB reste plus adapté. Pour des données souples et imbriquées, MongoDB est plus naturel.

2. Les notions de base

Une instance MongoDB contient des bases, chaque base contient des collections, et chaque collection contient des documents. Si vous connaissez SQL, une collection correspond à une table et un document à une ligne.

Notion Ce que c'est Équivalent SQL Exemple
Instance Le serveur MongoDB que vous louez Instance Votre offre CroustyCloud
Base de données Un ensemble de collections pour un projet Base monbot
Collection Un groupe de documents du même type Table joueurs, serveurs
Document Un enregistrement au format JSON Ligne Un joueur précis
Champ Une information dans un document Colonne pseudo, niveau
_id L'identifiant unique de chaque document, créé automatiquement Clé primaire ObjectId("...")
Utilisateur Un compte qui peut se connecter, avec des rôles précis Utilisateur monbot

Un document ressemble à ceci :

json
{ "_id": "6713a1f2c4e8b5a9d0f12345", "pseudo": "Alex", "niveau": 12, "inventaire": ["épée", "bouclier"], "stats": { "victoires": 30, "defaites": 8 } }

Un document peut contenir des listes et d'autres documents imbriqués. Pas besoin de créer la collection ou de déclarer les champs à l'avance : MongoDB les crée au premier enregistrement.

3. Se connecter à votre instance

Tout passe par la chaîne de connexion affichée dans CroustyPanel, sur la page de votre service. Elle regroupe en une ligne l'utilisateur, le mot de passe, l'hôte et le port :

bash
mongodb://admin:MOT_DE_PASSE@HOTE:PORT/?authSource=admin

authSource=admin indique où se trouve le compte utilisé pour se connecter.

⚠️

Gardez cette chaîne précieusement. Elle contient votre mot de passe et donne un accès complet à vos données. Ne la publiez jamais dans un dépôt Git ou un message public.

Deux outils pour vous connecter :

MongoDB Compass, l'application graphique officielle et gratuite (Windows, macOS, Linux). Collez la chaîne de connexion, cliquez sur Connect : vous voyez vos bases, vos collections et vos documents, et pouvez les modifier directement.

mongosh, l'outil en ligne de commande officiel :

bash
mongosh "mongodb://admin:MOT_DE_PASSE@HOTE:PORT/?authSource=admin"

Dans votre application, la même chaîne suffit. Par exemple en Node.js avec Mongoose :

javascript
const mongoose = require("mongoose"); await mongoose.connect("mongodb://monbot:MOT_DE_PASSE@HOTE:PORT/monbot?authSource=monbot");

Cette chaîne utilise l'utilisateur dédié créé à l'étape suivante, jamais le compte administrateur.

4. Créer une base et un utilisateur dédié

Le compte administrateur peut tout faire sur votre instance. L'utiliser directement dans vos applications est risqué : si l'une d'elles est compromise, toutes vos bases sont exposées.

La bonne pratique : créer une base et un utilisateur par projet, avec des droits limités à cette base.

Connecté avec le compte administrateur dans mongosh (ou l'onglet mongosh en bas de Compass), exécutez :

javascript
use monbot db.createUser({ user: "monbot", pwd: "un_mot_de_passe_long_et_unique", roles: [{ role: "readWrite", db: "monbot" }] })

Que font ces commandes ?

  • use monbot : sélectionne la base. Elle sera réellement créée au premier document enregistré
  • createUser : crée l'utilisateur dans cette base
  • readWrite : lui permet de lire et d'écrire, mais uniquement dans monbot

Vérifiez que tout est en place :

javascript
show dbs db.getUsers()

5. Les opérations essentielles

Quatre opérations couvrent l'essentiel du quotidien. Les exemples utilisent la collection joueurs dans la base monbot.

Ajouter des documents

javascript
db.joueurs.insertOne({ pseudo: "Alex", niveau: 1, inventaire: [] }) db.joueurs.insertMany([{ pseudo: "Sam", niveau: 3 }, { pseudo: "Lou", niveau: 7 }])

Lire des documents

javascript
db.joueurs.find() // tous les documents db.joueurs.findOne({ pseudo: "Alex" }) // le premier qui correspond db.joueurs.find({ niveau: { $gte: 5 } }) // niveau supérieur ou égal à 5 db.joueurs.find().sort({ niveau: -1 }).limit(10) // top 10 par niveau

Les opérateurs de comparaison commencent par $ :

  • $gt et $lt : plus grand, plus petit
  • $gte et $lte : plus grand ou égal, plus petit ou égal
  • $ne : différent
  • $in : présent dans une liste

Modifier des documents

javascript
db.joueurs.updateOne({ pseudo: "Alex" }, { $set: { niveau: 2 } }) db.joueurs.updateOne({ pseudo: "Alex" }, { $inc: { niveau: 1 } }) db.joueurs.updateOne({ pseudo: "Alex" }, { $push: { inventaire: "épée" } })
  • $set : change la valeur d'un champ
  • $inc : ajoute une valeur à un nombre
  • $push : ajoute un élément à une liste

Supprimer des documents

javascript
db.joueurs.deleteOne({ pseudo: "Alex" })
🚨

updateMany({}, ...) et deleteMany({}) avec un filtre vide s'appliquent à tous les documents de la collection. Lancez d'abord un find avec le même filtre pour voir ce qui sera touché.

6. Sauvegarder et restaurer vos données

Votre instance est sauvegardée automatiquement chaque jour par CroustyCloud. Faites quand même votre propre export avant toute opération risquée : une mise à jour de votre application, une migration ou une grosse suppression.

Depuis Compass : ouvrez une collection, bouton Export Data, format JSON. Pour restaurer, bouton Import Data et choisissez le fichier. Pratique pour une collection, moins pour une base entière.

En ligne de commande, avec les MongoDB Database Tools :

bash
# Exporter une base entière dans un dossier mongodump --uri="mongodb://monbot:MOT_DE_PASSE@HOTE:PORT/monbot?authSource=monbot" --out=sauvegarde # Restaurer ce dossier dans la base mongorestore --uri="mongodb://monbot:MOT_DE_PASSE@HOTE:PORT/?authSource=monbot" sauvegarde
💡

Conservez vos exports en dehors de l'instance, sur votre ordinateur ou un stockage en ligne. Une sauvegarde stockée au même endroit que les données ne protège pas contre tout.

7. Bonnes pratiques et sécurité

  • Un utilisateur par application, avec le rôle readWrite limité à sa base
  • Stockez la chaîne de connexion dans une variable d'environnement ou un fichier .env exclu de Git, jamais directement dans le code
  • Attention aux caractères spéciaux : dans une chaîne de connexion, les caractères @, : et / du mot de passe doivent être encodés (%40, %3A, %2F)
  • Ajoutez des index sur les champs que vous recherchez souvent, par exemple db.joueurs.createIndex({ pseudo: 1 })
  • Gardez des documents raisonnables : un document est limité à 16 Mo. Une liste qui grossit sans fin gagne à être placée dans sa propre collection
  • Surveillez la RAM et l'espace disque dans CroustyPanel : MongoDB utilise beaucoup de mémoire pour rester rapide

8. Récapitulatif : ce que vous avez fait

  • ✅ Connexion à votre instance MongoDB
  • ✅ Base et utilisateur dédiés créés
  • ✅ Premiers documents ajoutés et manipulés
  • ✅ Sauvegarde maîtrisée
✅

Votre base MongoDB est prête. Vous pouvez maintenant y connecter votre bot ou votre application. Une question ou un blocage ? Ouvrez un ticket depuis CroustyPanel ou passez sur notre Discord.