Schema evolution : corriger sans réécrire l'histoire

Soit le scénario suivant : six mois après le déploiement, le régulateur impose un champ reason obligatoire sur tous les retraits. On ouvre MoneyWithdrawn, on ajoute le champ, on déploie.

Au rebuild suivant, TransactionHistoryProjection casse. Les anciens événements MoneyWithdrawn n'ont pas de reason, le handler accède à event.reason.toUpperCase() et lève TypeError: Cannot read properties of undefined. Si le runner de projection attrape l'erreur sans la remonter, la projection reste dans un état partiel sans qu'aucune alerte ne parte.

La tentation est alors de modifier les événements historiques pour leur donner un reason. Ce serait détruire ce que l'Event Sourcing vous a apporté, puisque c'est la contrainte append-only qui rend le système auditable.

Les événements persistés sont des faits

Un événement dans l'EventStore décrit ce qui s'est produit, au moment où ça s'est produit. MoneyWithdrawn { amount: 300, accountId: "alice" } persisté en 2023 est un fait : 300 € ont été retirés du compte alice à cette date. Le modifier rétroactivement changerait l'histoire.

Une modification directe a des conséquences en cascade :

• tous les snapshots et projections construits depuis cet événement deviennent potentiellement incorrects ;
• l'audit trail ne peut plus être considéré comme fiable ;
• si le store chaîne les événements par hash ou les signe, la modification casse la vérification.

Les changements de schéma d'un événement n'ont pas tous le même profil de risque ; le tableau en fin d'article les range un par un. Deux cas suffisent à poser le problème.

Nouveau champ avec valeur par défaut. C'est le changement le moins risqué : event.reason ?? 'unspecified' dans le handler suffit, rétrocompatible immédiatement et sans migration.

Champ renommé. Les bugs silencieux apparaissent avec lui. Renommer amount en amountCents dans la classe TypeScript sans migration produit des événements historiques avec amount et des nouveaux avec amountCents, et les handlers voient undefined sur tous les événements antérieurs. Je ne fais donc jamais un renommage en place : il passe par un upcaster, qui ajoute le nouveau nom et retire l'ancien à la lecture.