Transactions MongoDB : quand et comment les utiliser

Une transaction MongoDB regroupe plusieurs opérations, sur un ou plusieurs documents et collections, pour qu'elles soient appliquées toutes ou aucune : si l'une échoue, MongoDB annule les autres. MongoDB offre ces transactions ACID multi-documents depuis la version 4.0, à condition que la base tourne en replica set (ou en cluster réparti). Ce chapitre explique pourquoi on en a moins souvent besoin qu'en SQL, puis comment les écrire dans mongosh, avec le driver et avec Mongoose, sans tomber dans le piège de la session oubliée.

Un document est déjà atomique

En SQL, enregistrer une fiche et ses lignes touche trois tables : il faut une transaction pour que la fiche n'existe jamais sans ses lignes (transactions SQL). En MongoDB, la fiche et ses lignes sont un seul document, et toute écriture sur un document est atomique : un updateOne qui ajoute une ligne et change dateModif est appliqué en entier ou pas du tout, même si le serveur tombe au milieu, et aucun autre client ne voit un état intermédiaire.

C'est l'un des intérêts de l'imbrication (chapitre 6) : la plupart des opérations d'AppliFrais (saisir une ligne, clôturer une fiche, la valider) ne touchent qu'un document et n'ont besoin d'aucune transaction. La technique du chapitre 4 complète cette garantie : mettre la condition métier dans le filtre ({ _id, etat: 'CR' }) rend l'opération sûre même si deux requêtes arrivent en même temps.

Quand une transaction devient nécessaire

Une transaction s'impose quand plusieurs documents doivent changer ensemble et qu'un état intermédiaire serait faux. Dans AppliFrais, la mise en paiement en est un exemple : le comptable passe la fiche à l'état MP et crée un document dans une collection paiements, que le service de paie lit pour faire le virement. Sans transaction, une panne entre les deux écritures laisserait une fiche « mise en paiement » sans ordre de paiement : le visiteur ne serait jamais remboursé, et personne ne le verrait.

La condition : un replica set

MongoDB n'accepte les transactions que sur un replica set (un groupe de serveurs qui se répliquent, réplication des données) ou un cluster réparti. Sur un serveur isolé (standalone), toute transaction échoue avec l'erreur Transaction numbers are only allowed on a replica set member or mongos.

• Atlas : toutes les bases, y compris l'offre gratuite, sont des replica sets de trois serveurs. Rien à faire.
• Installation locale : lance mongod avec l'option --replSet rs0 (ou replication.replSetName: rs0 dans mongod.conf), puis, une seule fois, dans mongosh : rs.initiate(). Un replica set d'un seul membre suffit pour développer.
• Docker : l'image démarre MongoDB seul. Pour le développement local, cette variante du compose.yaml démarre un replica set d'un membre et l'initialise grâce au test de santé :

services:
  mongo:
    image: mongo:9
    command: ["--replSet", "rs0", "--bind_ip_all"]
    ports:
      - "127.0.0.1:27017:27017"
    volumes:
      - mongo-data:/data/db
    healthcheck:
      test: ["CMD", "mongosh", "--quiet", "--eval",
             "try { rs.status().ok } catch (e) { rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: 'localhost:27017' }] }).ok }"]
      interval: 5s
      start_period: 10s
volumes:
  mongo-data:

Cette variante n'active pas l'authentification (un replica set authentifié exige en plus un fichier de clé partagé entre les membres) : réserve-la à ton poste, avec le port publié sur 127.0.0.1 seulement. Connecte-toi avec mongodb://localhost:27017/appli_frais?directConnection=true.

Une transaction dans mongosh

Une transaction vit dans une session. Dans mongosh, on démarre une session, on récupère la base à travers la session, puis on encadre les opérations par startTransaction et commitTransaction (ou abortTransaction) :

const session = db.getMongo().startSession();
const base = session.getDatabase('appli_frais');     // les opérations passent par la session

session.startTransaction();
base.fiches.updateOne(
  { visiteur: ObjectId('6a0000000000000000000002'), mois: '2026-09' },
  { $set: { etat: 'VA', montantValide: 1394.8 } }
);
base.journal.insertOne({ action: 'validation', mois: '2026-09',
                         visiteur: ObjectId('6a0000000000000000000002'), le: new Date() });

base.fiches.findOne({ visiteur: ObjectId('6a0000000000000000000002'), mois: '2026-09' }).etat  // 'VA'
db.fiches.findOne({ visiteur: ObjectId('6a0000000000000000000002'), mois: '2026-09' }).etat    // 'CL'

session.abortTransaction();      // ou session.commitTransaction()
session.endSession();

Pendant la transaction, la fiche est déjà VA dans la session, mais toujours CL pour les autres clients (db, hors session) : c'est l'isolation. Après abortTransaction(), la fiche est restée CL et le journal est vide ; avec commitTransaction(), les deux écritures deviennent visibles en même temps.

Avec le driver : withTransaction

Dans une application, on n'appelle pas startTransaction et commitTransaction à la main : session.withTransaction() les gère, réessaie automatiquement la transaction en cas d'erreur passagère (un conflit d'écriture avec une autre transaction, une élection de serveur principal) et l'annule si ta fonction lance une erreur.

const session = client.startSession();
try {
  await session.withTransaction(async () => {
    const fiche = await fiches.findOneAndUpdate(
      { _id: idFiche, etat: 'VA' },
      { $set: { etat: 'MP' } },
      { session, returnDocument: 'after' }          // { session } sur CHAQUE opération
    );
    if (!fiche) throw new Error("Fiche introuvable ou pas à l'état VA");
    await paiements.insertOne(
      { fiche: fiche._id, visiteur: fiche.visiteur, montant: fiche.montantValide, ordonneLe: new Date() },
      { session }
    );
  });
} finally {
  await session.endSession();
}

Avec Mongoose : connection.transaction

Mongoose ajoute connection.transaction(), qui crée la session, appelle withTransaction, et remet les documents Mongoose dans leur état d'origine si la transaction est rejouée.

// src/services/paiement.service.js
import mongoose from 'mongoose';
import { Fiche } from '../models/Fiche.js';
import { Paiement } from '../models/Paiement.js';   // fiche (unique), visiteur, montant, ordonnePar

export function mettreEnPaiement(idFiche, idComptable) {
  return mongoose.connection.transaction(async (session) => {
    const fiche = await Fiche.findOneAndUpdate(
      { _id: idFiche, etat: 'VA' },
      { $set: { etat: 'MP' } },
      { session, returnDocument: 'after' },
    );
    if (!fiche) throw new Error("Fiche introuvable ou pas à l'état VA");

    const [paiement] = await Paiement.create(
      [{ fiche: fiche._id, visiteur: fiche.visiteur, montant: fiche.montantValide, ordonnePar: idComptable }],
      { session },          // avec une session, create prend un TABLEAU de documents
    );
    return paiement;
  });
}

Ce qui se passe sur le jeu de données, quand le comptable met en paiement la fiche de septembre de Lucas Martin (898,90 €) :

Les règles d'une bonne transaction

• Courte. Une transaction est annulée si elle dure plus de 60 secondes (paramètre transactionLifetimeLimitSeconds). Ne fais jamais d'appel réseau extérieur (un service de paiement, l'envoi d'un courriel) dans une transaction : fais-le après la validation.
• Rare. Une transaction bloque les documents qu'elle modifie pour les autres transactions et consomme des ressources ; MongoDB 9.0 limite par défaut à 10 000 le nombre de transactions ouvertes en même temps (erreur TooManyOpenTransactions au-delà).
• Rejouable. withTransaction peut exécuter ta fonction plusieurs fois : elle ne doit avoir aucun effet hors de la base (pas de compteur en mémoire, pas de journal écrit dans un fichier) avant la validation.
• Avec des garanties fortes. Toutes les lectures d'une transaction voient le même état des données. Avec la confirmation d'écriture w: 'majority', le réglage par défaut depuis MongoDB 5.0, la validation n'est confirmée que lorsque la majorité des membres du replica set l'ont enregistrée : un serveur qui tombe juste après ne la fait pas disparaître.

Exercices

export function transfererVehicule(immat, idAncien, idNouveau) {
  return mongoose.connection.transaction(async (session) => {
    await Visiteur.updateOne({ _id: idNouveau, vehicule: null }, { $set: { vehicule: immat } });
    const r = await Visiteur.updateOne({ _id: idAncien, vehicule: immat }, { $set: { vehicule: null } }, { session });
    if (r.modifiedCount !== 1) throw new Error("L'ancien utilisateur n'a pas ce véhicule");
  });
}

export function transfererVehicule(immat, idAncien, idNouveau) {
  return mongoose.connection.transaction(async (session) => {
    const r1 = await Visiteur.updateOne(
      { _id: idNouveau, vehicule: null }, { $set: { vehicule: immat } }, { session });
    if (r1.modifiedCount !== 1) throw new Error('Le nouvel utilisateur a déjà un véhicule');
    const r2 = await Visiteur.updateOne(
      { _id: idAncien, vehicule: immat }, { $set: { vehicule: null } }, { session });
    if (r2.modifiedCount !== 1) throw new Error("L'ancien utilisateur n'a pas ce véhicule");
  });
}