Mongoose : installation et connexion

Mongoose est la bibliothèque Node.js qui modélise les données de MongoDB : schémas, validation, requêtes et relations. Cette rubrique décrit Mongoose 8 avec des modules ES ; les exemples utilisent des noms génériques (boutique, app, modèles Client et Commande).

Prérequis

Node.js récent (voir Node.js : installation).
Un serveur MongoDB accessible (voir MongoDB : installation), avec un utilisateur dédié à l’application (voir MongoDB : utilisateurs et droits).

node --version
mongosh --version

Installer

mkdir monapi && cd monapi
npm init -y
npm install mongoose
npm ls mongoose

Dans package.json, activer les modules ES : "type": "module".

Se connecter

src/db.js :

import mongoose from 'mongoose';

export async function connecter() {
  const uri = process.env.MONGODB_URI;
  if (!uri) throw new Error('MONGODB_URI manquante');

  await mongoose.connect(uri, {
    serverSelectionTimeoutMS: 5000,
    maxPoolSize: 10,
  });
  console.log('MongoDB connecté :', mongoose.connection.name);
}

export async function deconnecter() {
  await mongoose.disconnect();
}

Chaîne de connexion dans l’environnement (jamais dans le code) :

export MONGODB_URI='mongodb://app:<mot-de-passe>@127.0.0.1:27017/boutique?authSource=boutique'

Élément	Rôle
`app:<mot-de-passe>`	Compte de l’application
`127.0.0.1:27017`	Serveur et port
`/boutique`	Base de données
`authSource=boutique`	Base où le compte a été créé

Essai :

import { connecter, deconnecter } from './db.js';

await connecter();
await deconnecter();

node --env-file=.env src/essai.js

Options utiles

Option	Rôle
`serverSelectionTimeoutMS`	Délai avant d’échouer si le serveur est injoignable (30 s par défaut : le réduire)
`maxPoolSize`	Connexions simultanées maximales (100 par défaut)
`minPoolSize`	Connexions maintenues ouvertes
`socketTimeoutMS`	Délai d’inactivité d’une connexion
`autoIndex`	Création automatique des index (voir Performances et production)
`dbName`	Nom de la base si absent de l’URI
`appName`	Nom visible dans les journaux de MongoDB

Événements

mongoose.connection.on('connected', () => console.log('mongo : connecté'));
mongoose.connection.on('error', (err) =>
  console.error('mongo : erreur', err.message),
);
mongoose.connection.on('disconnected', () =>
  console.warn('mongo : déconnecté'),
);

Mongoose se reconnecte automatiquement après une coupure ; ces événements aident à le suivre.

Une connexion par processus

Appeler mongoose.connect() une seule fois au démarrage de l’application, pas dans chaque requête. Les modèles utilisent ensuite cette connexion partagée. Attendre la connexion avant d’écouter :

import express from 'express';
import { connecter } from './db.js';

const app = express();
await connecter();
app.listen(3000, '127.0.0.1');

Voir Express : installation.

Fermeture propre

process.on('SIGTERM', async () => {
  await mongoose.disconnect();
  process.exit(0);
});

Fichier d’environnement

.env :

MONGODB_URI=mongodb://app:<mot-de-passe>@127.0.0.1:27017/boutique?authSource=boutique
NODE_ENV=development

.gitignore :

node_modules/
.env

Dépannage

Symptôme	Piste
`MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017`	MongoDB arrêté ou mauvaise adresse : `sudo systemctl status mongod`
`MongoServerError: Authentication failed`	Mot de passe, utilisateur, ou `authSource` erroné
`MongoParseError: Invalid scheme` / `URI malformed`	Caractères spéciaux non encodés dans le mot de passe
`Operation … buffering timed out after 10000ms`	Requête lancée avant la connexion, ou connexion échouée : attendre `await connecter()`
`Cannot use import statement outside a module`	`"type": "module"` absent
`MongooseError: The` uri`parameter to`openUri() `must be a string`	Variable `MONGODB_URI` non définie

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : Mongoose dépend de Node.js et de la version de MongoDB. Vérifier la compatibilité entre la version de Mongoose et celle du serveur MongoDB avant une montée de version (page de compatibilité de la documentation de Mongoose).

Pour aller plus loin

Documentation : mongoosejs.com
Suite : Schémas et modèles