Bases de données pour bots Discord : SQLite, PostgreSQL, MySQL, MongoDB
Tout ce que votre bot garde dans des variables (paramètres des serveurs, avertissements, historique des tickets, soldes) est effacé au redémarrage du bot ; pour des données persistantes, il faut une base de données. Dans ce guide, vous apprendrez à choisir et à connecter SQLite, PostgreSQL, MySQL ou MongoDB pour votre bot discord.js (Node.js), à garder les informations secrètes dans un fichier .env, ainsi qu'à utiliser les requêtes paramétrées, le pool de connexions, la version du schéma et les sauvegardes. Une mise en œuvre complète avec SQLite figure dans le guide Comment créer un système d'économie et de niveaux (level) avec Discord.js ?.
Avant de commencer
- Un bot fonctionnel : les exemples supposent la structure du guide Comment créer un bot Discord à partir de zéro avec Discord.js v14 :
index.jsà la racine du projet, un dossiercommands/et, pour charger le fichier.envavecnode --env-file=.env index.js, une commandenpm start. - Node.js : les branches LTS (support à long terme) encore maintenues satisfont aux exigences des paquets présentés ici ; l'exigence la plus élevée est celle de better-sqlite3 (Node.js 22 ou plus récent). Pour le bot lui-même, utilisez la version LTS recommandée par le modèle.
- Un serveur de base de données : PostgreSQL, MySQL ou MongoDB doit être installé et en fonctionnement ; l'installation et la création d'un utilisateur distinct pour le bot sont décrites dans le guide Guide d'installation et de gestion des bases de données (MySQL, MariaDB, PostgreSQL) sur les serveurs VDS HanHosting.
- Les ressources : le serveur de base de données partage la RAM et le disque avec le bot sur la même machine. Les offres VDS pour bot Discord sont fournies avec 4 CPU, 2–4 Go de RAM et 30–40 Go de disque NVMe ; suivez la consommation grâce aux graphiques d'utilisation en direct de l'Espace client.
1. Choisir la base de données
La liste de critères de SQLite est courte : si les données sont séparées de l'application par un réseau, s'il y a de nombreuses écritures simultanées ou si les données sont très volumineuses, choisissez une base de données client/serveur ; dans les autres cas, SQLite suffit. SQLite accepte de nombreux lecteurs en même temps, mais un seul processus d'écriture. Pour un bot, cela donne ceci :
- SQLite (better-sqlite3) : le premier choix si le bot tourne sur une seule machine et que seul le bot accède aux données. Aucun serveur séparé n'est à installer, les données tiennent dans un seul fichier et les requêtes s'exécutent de façon synchrone (le résultat revient sans
await). - PostgreSQL (pg) ou MySQL (mysql2) : si plusieurs processus ou machines utilisent les mêmes données : un panel web sur un autre serveur, un second bot, des écritures intensives. Discord impose le sharding (découpage du bot en plusieurs parties) aux bots présents sur 2 500 serveurs ou plus ; les shards que
ShardingManagerlance sur la même machine peuvent partager un même fichier SQLite, mais leurs écritures sont mises en file d'attente. Si les shards doivent être répartis sur plusieurs machines, passez à une base de données serveur. - MongoDB (mongoose) : si vos données correspondent mieux à une structure de documents qu'à des tables, par exemple si chaque serveur Discord a un objet de paramètres avec des champs imbriqués.
Pour quick.db et les simples fichiers JSON, consultez les questions fréquentes ci-dessous.
2. Placer les informations secrètes dans le fichier .env
Comme le token du bot, le mot de passe de la base de données ne s'écrit jamais dans le code. Ajoutez au fichier .env du modèle uniquement les lignes de la base de données que vous utilisez :
DISCORD_TOKEN=votre-token-de-bot
# PostgreSQL
PGHOST=127.0.0.1
PGPORT=5432
PGUSER=botuser
PGPASSWORD=mot-de-passe-solide
PGDATABASE=botdb
# MySQL
MYSQL_HOST=127.0.0.1
MYSQL_USER=botuser
MYSQL_PASSWORD=mot-de-passe-solide
MYSQL_DATABASE=botdb
# MongoDB
MONGODB_URI=mongodb://botuser:[email protected]:27017/botdb
- node-postgres lit, comme
psql, les variables d'environnementPG*; vous n'avez pas besoin de les écrire à nouveau dans le code. - Si le nom d'utilisateur ou le mot de passe de l'adresse MongoDB contient l'un des caractères
$ : / ? # [ ] @, il faut l'encoder (percent encoding) : par exemple,@s'écrit%40. Si vous avez créé l'utilisateur dans la baseadmin, ajoutez?authSource=adminà la fin de l'adresse. - Le fichier
.envdoit figurer dans.gitignore; sous Linux, limitez sa lecture à son propriétaire avecchmod 600 .env.
Dans le bot, n'utilisez pas le compte postgres de PostgreSQL ni le compte root de MySQL, mais un utilisateur distinct qui n'a de droits que sur la base du bot. Si le bot et la base de données sont sur le même VDS, connectez-vous via 127.0.0.1 ; n'ouvrez pas le port de la base de données (PostgreSQL 5432, MySQL 3306, MongoDB 27017) vers l'extérieur dans le pare-feu.
3. Établir la connexion dans un seul module
Créez la connexion (ou le pool) une seule fois au démarrage du bot et partagez-la avec toutes les commandes à partir du module db.js placé à la racine du projet ; n'ouvrez pas une nouvelle connexion dans chaque commande. Installez dans le dossier du projet uniquement le paquet que vous allez utiliser :
npm install better-sqlite3 # SQLite
npm install pg # PostgreSQL
npm install mysql2 # MySQL
npm install mongoose # MongoDB
SQLite
const path = require('node:path');
const Database = require('better-sqlite3');
const db = new Database(path.join(__dirname, 'data.db'));
db.pragma('journal_mode = WAL');
module.exports = { db };
Grâce à __dirname, le même fichier est ouvert quel que soit le dossier à partir duquel le bot est lancé. En mode WAL (journalisation par écriture anticipée), les lectures et les écritures ne s'attendent pas mutuellement. Aucune étape de connexion supplémentaire n'est nécessaire.
PostgreSQL
const { Pool } = require('pg');
// Les informations de connexion sont lues dans les variables PG* du fichier .env
const pool = new Pool({ max: 10, connectionTimeoutMillis: 5000 });
// Si l'erreur d'une connexion inactive n'est pas écoutée, le processus peut planter
pool.on('error', (err) => console.error('PostgreSQL:', err.message));
const connect = () => pool.query('SELECT 1');
module.exports = { pool, connect };
MySQL
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
host: process.env.MYSQL_HOST,
user: process.env.MYSQL_USER,
password: process.env.MYSQL_PASSWORD,
database: process.env.MYSQL_DATABASE,
connectionLimit: 10,
});
const connect = () => pool.query('SELECT 1');
module.exports = { pool, connect };
MongoDB
const mongoose = require('mongoose');
mongoose.set('sanitizeFilter', true);
mongoose.connection.on('error', (err) => console.error('MongoDB:', err.message));
const connect = () =>
mongoose.connect(process.env.MONGODB_URI, { serverSelectionTimeoutMS: 5000 });
module.exports = { mongoose, connect };
Avec les bases de données serveur, ne connectez pas le bot à Discord tant que la connexion n'a pas été vérifiée. Remplacez la dernière ligne de index.js (client.login(...)) par ceci :
const { connect } = require('./db');
connect()
.then(() => client.login(process.env.DISCORD_TOKEN))
.catch((err) => {
console.error('Impossible de se connecter à la base de données :', err.message);
process.exit(1);
});
Mongoose met en attente (buffering) les opérations sur les modèles appelées avant la connexion et renvoie par défaut une erreur d'expiration au bout de 10 secondes ; si la première connexion échoue, il ne réessaie pas de lui-même. PM2 ou systemd redémarre le bot qui s'arrête avec le code de sortie 1 (Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS).
4. Écrire des requêtes paramétrées
Concaténer une valeur fournie par l'utilisateur au texte de la requête ouvre la porte à l'injection SQL (SQL injection) : une entrée spécialement conçue change le sens de la requête. Envoyez toujours la valeur au moyen d'un marqueur de paramètre (placeholder), séparément de la requête :
const title = interaction.options.getString('title');
// INCORRECT : l'entrée est ajoutée au texte de la requête
db.prepare(`SELECT * FROM notes WHERE title = '${title}'`).get();
// better-sqlite3 : ? (ou @name, :name, $name)
db.prepare('SELECT * FROM notes WHERE guild_id = ? AND title = ?')
.get(interaction.guildId, title);
// pg : $1, $2
await pool.query('SELECT * FROM notes WHERE guild_id = $1 AND title = $2',
[interaction.guildId, title]);
// mysql2 : execute avec ? (requête préparée)
const [rows] = await pool.execute(
'SELECT * FROM notes WHERE guild_id = ? AND title = ?',
[interaction.guildId, title]);
// mongoose : objet filtre
await Note.findOne({ guildId: interaction.guildId, title });
- Les marqueurs de paramètre ne servent qu'aux valeurs ; un nom de table ou de colonne ne peut pas être passé en paramètre. Faites correspondre les choix de l'utilisateur, comme un critère de tri, à une liste fixe définie dans le code, et ne placez jamais l'entrée directement dans la requête.
- Dans MongoDB, l'attaque consiste à glisser dans le filtre un opérateur commençant par
$(injection de sélecteur de requête). Le réglagesanitizeFilterde l'étape 3 la neutralise : les objets imbriqués qui contiennent un champ dont le nom commence par$sont encapsulés dans$eq. - Les identifiants Discord (snowflakes) sont des nombres de 64 bits qui ne peuvent pas être représentés exactement par un nombre JavaScript ; c'est pourquoi discord.js les fournit sous forme de texte (string). Déclarez les colonnes en
TEXTouVARCHAR(20), et les champs Mongoose enString.
5. Créer les tables et versionner le schéma
Dans les petits bots, créez les tables au démarrage avec CREATE TABLE IF NOT EXISTS ; si la table existe déjà, la commande ne fait rien. Cet exemple, qui stocke les paramètres des serveurs, fonctionne tel quel avec PostgreSQL et SQLite :
CREATE TABLE IF NOT EXISTS server_settings (
guild_id TEXT PRIMARY KEY,
welcome_channel TEXT,
log_channel TEXT
);
Pour mettre à jour un enregistrement s'il existe ou l'insérer sinon (upsert), on utilise INSERT ... ON CONFLICT (guild_id) DO UPDATE SET ... avec PostgreSQL et SQLite, et INSERT ... ON DUPLICATE KEY UPDATE avec MySQL. MySQL n'accepte pas de TEXT sans longueur dans une clé primaire ; utilisez donc VARCHAR(20) dans ce cas.
Lorsque vous ajoutez des colonnes par la suite, enregistrez la version du schéma pour ne pas retenter la modification à chaque démarrage. Dans SQLite, le nombre user_version de l'en-tête de la base de données est laissé à l'application pour cet usage :
if (db.pragma('user_version', { simple: true }) < 1) {
db.exec('ALTER TABLE server_settings ADD COLUMN language TEXT');
db.pragma('user_version = 1');
}
Avec PostgreSQL et MySQL, vous faites la même chose avec une table schema_version d'une seule ligne. Avec Mongoose, le schéma est défini dans le code :
// models/ServerSetting.js
const { Schema, model } = require('mongoose');
const settingSchema = new Schema({
guildId: { type: String, required: true, unique: true },
welcomeChannel: String,
logChannel: String,
});
module.exports = model('ServerSetting', settingSchema);
// Dans le fichier de commande : const ServerSetting = require('../../models/ServerSetting');
// dans execute
const channel = interaction.options.getChannel('channel');
await ServerSetting.findOneAndUpdate(
{ guildId: interaction.guildId },
{ welcomeChannel: channel.id },
{ upsert: true, returnDocument: 'after' });
Depuis Mongoose 9.2, l'option new: true est obsolète (deprecated) ; pour obtenir le document mis à jour, écrivez returnDocument: 'after'.
6. Gérer le pool de connexions et l'arrêt
Le pool conserve des connexions ouvertes et les répartit entre les requêtes. Dans pg, le maximum par défaut est de 10 connexions (max), une connexion inactive pendant 10 secondes est fermée et l'établissement d'une connexion n'a pas de délai d'expiration (connectionTimeoutMillis: 0) ; c'est pourquoi nous avons indiqué 5 secondes dans l'exemple. La documentation de node-postgres recommande généralement un seul pool par application.
Pour les requêtes qui doivent réussir ensemble (comme un transfert de coins), utilisez une transaction. Dans pg, n'exécutez pas une transaction avec pool.query : d'après la documentation de node-postgres, toutes les requêtes d'une transaction doivent passer par le même client :
const dbClient = await pool.connect();
try {
await dbClient.query('BEGIN');
const debit = await dbClient.query(
'UPDATE members SET balance = balance - $1 WHERE user_id = $2 AND balance >= $1', [amount, sender]);
if (debit.rowCount === 0) throw new Error('INSUFFICIENT'); // le solde ne devient jamais négatif
await dbClient.query('UPDATE members SET balance = balance + $1 WHERE user_id = $2', [amount, recipient]);
await dbClient.query('COMMIT');
} catch (err) {
await dbClient.query('ROLLBACK');
throw err;
} finally {
dbClient.release(); // en cas d'oubli, le pool finit par s'épuiser
}
Avec mysql2, le même schéma se construit avec pool.getConnection(), beginTransaction(), commit(), rollback() et release(). Si une requête est lente, vous risquez de dépasser les 3 secondes que Discord accorde pour la première réponse ; appelez await interaction.deferReply() au début de la commande et envoyez le résultat avec editReply().
Fermez proprement les connexions lorsque le bot s'arrête. PM2 envoie d'abord SIGINT, puis termine le processus avec SIGKILL s'il ne s'est pas arrêté en 1,6 seconde ; systemd envoie SIGTERM par défaut. Remplacez la ligne de index.js par const { pool, connect } = require('./db'); (pour MongoDB, remplacez pool par mongoose ; pour SQLite, utilisez { db }), puis ajoutez ceci à la fin du fichier :
async function shutdown(signal) {
console.log(`${signal} reçu, arrêt du bot`);
await client.destroy();
await pool.end(); // pg et mysql2
// await mongoose.disconnect(); // MongoDB
// db.close(); // SQLite
process.exit(0);
}
process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);
7. Faire des sauvegardes et tester la restauration
Les VDS ne comprennent pas de sauvegardes automatiques ; les sauvegardes sont sous votre responsabilité. Copier simplement les fichiers d'une base de données en fonctionnement peut produire une sauvegarde incohérente ; utilisez l'outil propre à chaque base de données :
# SQLite (outil en ligne de commande ; Debian/Ubuntu : sudo apt install sqlite3)
sqlite3 data.db ".backup backup-data.db"
# PostgreSQL : format personnalisé compressé
pg_dump -h 127.0.0.1 -U botuser -Fc -f botdb.dump botdb
# MySQL : sauvegarde cohérente des tables InnoDB sans bloquer les applications
mysqldump --single-transaction --no-tablespaces botdb > botdb.sql
# MongoDB : l'outil s'installe avec le paquet MongoDB Database Tools
mongodump --config=/home/bot/.mongo-backup.yaml --archive=botdb.gz --gzip --db=botdb
Sans --no-tablespaces, mysqldump exécuté avec un utilisateur de bot qui n'a pas le privilège PROCESS renvoie l'erreur Access denied; you need (at least one of) the PROCESS privilege(s). Les commandes de restauration :
pg_restore -h 127.0.0.1 -U botuser --clean --if-exists -d botdb botdb.dump
mysql botdb < botdb.sql
mongorestore --config=/home/bot/.mongo-backup.yaml --archive=botdb.gz --gzip --drop
Pour SQLite, arrêtez le bot, mettez de côté le fichier data.db avec les fichiers data.db-wal et data.db-shm qui l'accompagnent, puis placez la sauvegarde sous le nom data.db. Le code permettant de faire une sauvegarde depuis le bot (db.backup()) se trouve dans le guide sur l'économie.
N'écrivez pas le mot de passe dans la commande : un mot de passe passé en ligne de commande peut apparaître dans la sortie de ps. Placez les mots de passe dans des fichiers que vous seul pouvez lire (chmod 600) :
- PostgreSQL : dans
~/.pgpass, la ligne127.0.0.1:5432:*:botuser:motdepasse(*correspond à toutes les bases) ; si les droits du fichier sont plus permissifs, il est ignoré. - MySQL : dans le fichier
~/.my.cnf, section[client], les lignesuser=etpassword=. - MongoDB : dans
/home/bot/.mongo-backup.yaml, la ligneuri: mongodb://botuser:[email protected]:27017/botdb; les outils la lisent avec--config.
Sauvegarde automatique quotidienne sous Linux : créez le fichier /home/bot/backup.sh (l'exemple concerne PostgreSQL ; ajoutez les autres lignes de la même manière) :
#!/bin/bash
set -e
TARGET=/home/bot/backups
mkdir -p "$TARGET"
STAMP=$(date +%Y%m%d-%H%M)
pg_dump -h 127.0.0.1 -U botuser -Fc -f "$TARGET/botdb-$STAMP.dump" botdb
find "$TARGET" -type f -mtime +7 -delete # supprime les sauvegardes de plus d'une semaine environ
Rendez-le exécutable avec chmod 700 /home/bot/backup.sh, puis ajoutez avec crontab -e la ligne qui le lancera chaque nuit à 04:30 :
30 4 * * * /home/bot/backup.sh
Sur un VDS Windows : écrivez les mêmes commandes dans un script PowerShell et exécutez-le chaque jour avec le « Task Scheduler » (Planificateur de tâches). Sous Windows, le fichier de mots de passe de PostgreSQL se trouve à l'emplacement %APPDATA%\postgresql\pgpass.conf.
Une sauvegarde stockée sur le même disque ne protège ni contre une panne du disque ni contre une réinstallation (« Réinstaller (formatage) ») lancée depuis l'Espace client, qui efface le disque. Envoyez les copies par SFTP vers votre espace de sauvegarde cloud. De temps en temps, restaurez une sauvegarde dans une base de test pour la vérifier (avec PostgreSQL : sudo -u postgres createdb -O botuser botdb_test, puis pg_restore -h 127.0.0.1 -U botuser -d botdb_test botdb.dump).
Récapitulatif des paquets
| Sujet | better-sqlite3 | pg | mysql2 | mongoose |
|---|---|---|---|---|
| Version actuelle sur npm | 13.0.3 | 8.23.1 | 3.24.6 | 9.11.4 |
| Version de Node.js requise | 22 ou plus récent | 16 ou plus récent | 8 ou plus récent | 20.19.0 ou plus récent |
| Marqueur de paramètre | ?, @name | $1, $2 | ? | Objet filtre + sanitizeFilter |
| Réglage du pool | Aucun (connexion à un fichier) | max (10 par défaut) | connectionLimit (10 par défaut) | maxPoolSize (100 par défaut) |
Erreurs fréquentes
SQLITE_BUSY: database is locked: une autre connexion est en train d'écrire ; par défaut, better-sqlite3 attend le verrou pendant 5 secondes, puis renvoie cette erreur. Le plus souvent, deux copies du bot tournent ou une sessionsqlite3est restée ouverte ; fermez celle qui est en trop.connect ECONNREFUSED 127.0.0.1:5432(3306 pour MySQL, 27017 pour MongoDB) : le service ne tourne pas, ou il écoute sur une autre adresse ou un autre port. Sous Linux, vérifiez avecsystemctl status; le nom du service dépend de l'installation :postgresqlpour PostgreSQL (sous Debian/Ubuntu, le cluster réel estpostgresql@<version>-main),mysqloumysqldpour MySQL,mariadbpour MariaDB etmongodpour MongoDB.password authentication failed for user(PostgreSQL) ouAccess denied for user(MySQL) : le nom d'utilisateur ou le mot de passe indiqué dans.envest incorrect. Si le bot a été lancé sans--env-file(node index.js), les variables ne sont pas lues du tout : pg tente de se connecter sans mot de passe avec le nom d'utilisateur de votre système d'exploitation et renvoie le plus souvent l'erreurSASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string. Utiliseznpm start.buffering timed out after 10000ms(Mongoose) :mongoose.connectn'a pas été appelé ou la connexion n'a pas pu être établie. Lancez le bot après la connexion, comme à l'étape 3 ; si vous voyezMongooseServerSelectionError, vérifiez l'adresse, le port et les identifiants de l'utilisateur.- Au bout d'un moment, le bot reste bloqué sur les commandes : un client obtenu avec
pool.connect()n'est pas libéré et le pool s'épuise. Placezrelease()dansfinally; pour les requêtes isolées, utilisezpool.query. BLOB/TEXT column 'guild_id' used in key specification without a key length(MySQL) : la clé primaire a été déclarée enTEXT; passez-la enVARCHAR(20).
Questions fréquentes
quick.db ou un fichier JSON ne suffisent-ils pas ?
Nous ne les recommandons pas pour un bot destiné à durer. Un simple fichier JSON n'offre ni transactions, ni verrous, ni requêtes ; si le bot plante pendant l'écriture du fichier ou si deux commandes écrivent en même temps, les données peuvent être corrompues ou perdues. Le dépôt de quick.db a été archivé, et quick.db fonctionne de toute façon par-dessus better-sqlite3 ; les détails se trouvent dans le guide sur l'économie.
Faut-il faire tourner la base de données sur le même VDS que le bot ?
Pour un seul bot, généralement oui : la connexion passe par 127.0.0.1 et le port n'est pas ouvert vers l'extérieur. Si votre panel web se trouve sur un autre serveur, n'ouvrez le port dans le pare-feu que pour l'adresse IP de ce serveur.
Que faire si le mot de passe de la base de données a fuité ?
Changez le mot de passe : avec PostgreSQL, dans psql, utilisez \password botuser (la commande demande le mot de passe, alors que ALTER ROLE ... PASSWORD peut laisser le mot de passe dans l'historique des commandes ou dans le journal du serveur) ; avec MySQL, ALTER USER 'botuser'@'localhost' IDENTIFIED BY 'nouveau-mot-de-passe'; (avec la partie hôte indiquée lors de la création de l'utilisateur) ; avec MongoDB, dans mongosh, passez sur la base où vous avez créé l'utilisateur (use botdb ou use admin), puis exécutez db.changeUserPassword('botuser', passwordPrompt()). Mettez ensuite à jour le fichier .env et les fichiers de mots de passe des sauvegardes, puis redémarrez le bot. Si le fichier qui a fuité contenait aussi le token du bot, réinitialisez-le dans le Developer Portal.
Guides associés
- Comment créer un système d'économie et de niveaux (level) avec Discord.js ?
- Comment créer un bot Discord à partir de zéro avec Discord.js v14
- Comment créer un bot de support (tickets) avec Discord.js v14 ?
- Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS : PM2, systemd et NSSM
- Guide d'installation et de gestion des bases de données (MySQL, MariaDB, PostgreSQL) sur les serveurs VDS HanHosting
Les autres guides sur les bots se trouvent sur la page Guides bot Discord.
Commentaires0
Pas encore de commentaire
Soyez le premier à partager votre avis.
Veuillez vous connecter ou vous inscrire pour laisser un commentaire.