Database Evolution¶

Status: CONTRACT

Rôle¶

Cette page décrit comment faire évoluer la persistance de CMonChoix Platform sans transformer une modification de schéma en refonte incontrôlable.

Une évolution Database peut concerner :

le schéma ;
une table ou une colonne ;
un index ;
une projection persistée ;
une migration de données ;
une structure technique ;
une stratégie de reconstruction.

Elle ne doit jamais servir à déplacer discrètement une règle métier dans SQL.

Principe directeur¶

Une évolution sûre suit ce cycle :

Observation
   ↓
Conception
   ↓
Validation du contrat
   ↓
Simulation / dry-run lorsque possible
   ↓
Migration explicite
   ↓
Reconstruction ciblée si nécessaire
   ↓
Audit
   ↓
Surveillance

Chaque étape doit pouvoir être expliquée indépendamment.

Évolution incrémentale¶

Préférer plusieurs changements bornés à une transformation massive :

ajout d'une structure ;
remplissage contrôlé ;
activation progressive des Readers/Writers ;
reconstruction ;
observation ;
retrait différé de l'ancien chemin.

Cette séquence facilite les tests, les comparaisons et le rollback.

CURRENT, TARGET et migration¶

Une documentation de cible ne prouve pas que le Runtime l'utilise déjà.

Avant de migrer :

vérifier les fichiers et services réellement chargés ;
identifier les readers et writers actifs ;
vérifier le schéma présent dans l'environnement concerné ;
distinguer clairement ancien chemin, chemin transitoire et cible.

Une migration ne doit pas être lancée simplement parce qu'une page décrit un design TARGET.

Compatibilité des consommateurs¶

Une évolution Database doit considérer séparément :

les Read Services ;
les Write Services ;
le Runtime ;
les adapters WordPress/CLI/HTTP ;
le Frontend ;
les scripts d'exploitation.

Le consommateur ne doit pas dépendre d'une nouvelle structure avant que celle-ci soit réellement disponible et peuplée.

Lorsqu'une transition nécessite une coexistence temporaire, elle doit être explicite et bornée dans le temps.

Migrations de schéma¶

Une migration de schéma doit documenter :

la précondition de version ;
les opérations appliquées ;
le comportement en rejeu ;
la durée ou le volume attendu ;
les verrous ou indisponibilités possibles ;
le rollback ou la restauration ;
la validation finale.

Un bootstrap passif, une page admin read-only ou un simple wp CLI ne doit pas déclencher silencieusement une migration structurelle.

Migrations de données¶

Une migration de données diffère d'une correction métier.

Elle sert à adapter des données existantes à un nouveau contrat de persistance sans inventer une nouvelle décision métier.

Si une opération doit décider qu'un produit auparavant ambiguous devient resolved, elle n'est plus une simple migration de structure : la décision appartient au Domain Core ou à un processus métier explicitement validé.

Projections¶

Une évolution du Domain Core, d'un Builder ou du contrat de projection peut nécessiter un rebuild.

Le schéma attendu reste :

Donnée de référence
    ↓
Builder
    ↓
Write Service
    ↓
Projection persistée
    ↓
Reader

Pour la famille Product Models documentée actuellement, l'ordre de reconstruction complet est :

Product Models
    ↓
Variants
    ↓
Specifications
    ↓
Gallery

Avant toute commande opérationnelle, vérifier que les services et entrypoints correspondants sont réellement chargés dans le Runtime courant.

Dépréciation¶

Ne pas supprimer immédiatement une structure parce qu'un nouveau chemin existe.

Cycle recommandé :

Nouveau contrat
   ↓
Double compatibilité ciblée si nécessaire
   ↓
Migration / remplissage
   ↓
Basculage des consommateurs
   ↓
Observation
   ↓
Dépréciation explicite
   ↓
Suppression

Avant suppression, vérifier :

usages dans le code ;
Readers ;
CLI ;
scripts Operations ;
documentation ;
jobs historiques encore exécutables ;
possibilité de restaurer une ancienne sauvegarde.

Rollback¶

Le rollback doit être défini avant l'écriture lorsque le risque le justifie.

Selon le changement, il peut reposer sur :

migration inverse ;
restauration de sauvegarde ;
réactivation temporaire d'un ancien Reader ;
reconstruction depuis les données de référence ;
désactivation d'une nouvelle fonctionnalité.

Un rollback n'est pas seulement « remettre le code précédent » si le schéma ou les données ont déjà été modifiés.

Vérification après migration¶

Vérifier séparément :

État technique¶

schéma attendu ;
volumes ;
contraintes ;
index ;
erreurs ;
version de migration.

État fonctionnel¶

réconciliation des compteurs ;
statuts resolved / unknown / ambiguous / conflict ;
projections reconstruisibles ;
compatibilité des Readers ;
absence de régression visible dans les audits.

Une migration techniquement réussie peut rester fonctionnellement invalide.

Données historiques¶

Lorsqu'une ancienne implémentation a modifié destructivement une projection ou une donnée dérivée, cette ancienne base ne doit pas servir directement de baseline.

Il faut :

identifier l'ancienne mutation ;
reconstruire l'état dérivé depuis une source fiable ;
relancer l'audit ;
comparer seulement ensuite.

Performances¶

Une évolution pour raisons de performance doit conserver le contrat fonctionnel.

Avant/après, comparer :

latence ;
volume ;
coût d'écriture ;
temps de rebuild ;
contention ;
impact mémoire ;
cohérence des résultats.

Un gain de performance qui supprime des reason codes, des inconnus ou de la traçabilité peut rendre le système moins maintenable même si la requête est plus rapide.

Erreurs fréquentes¶

Modifier plusieurs couches en même temps¶

Changer schéma, règle métier, projection et renderer dans le même mouvement rend la cause d'une régression difficile à isoler.

Faire d'une migration un correctif métier¶

Une migration doit appliquer un contrat de données validé, pas inventer de nouvelles décisions.

Supprimer l'ancien chemin trop tôt¶

Une coexistence courte et contrôlée est parfois moins risquée qu'un basculement irréversible.

Confondre succès SQL et succès produit¶

Le fait que toutes les requêtes aient réussi ne prouve pas que les résultats métier sont corrects.

Déclencher une migration par effet de bord¶

Aucun contexte read-only ne doit installer ou transformer silencieusement le schéma.

Checklist d'évolution¶

Avant déploiement :

[ ] statut CURRENT/TARGET compris ;
[ ] readers et writers identifiés ;
[ ] migration bornée ;
[ ] rejeu/idempotence compris ;
[ ] sauvegarde ou rollback prévu ;
[ ] consommateurs compatibles ;
[ ] rebuild nécessaire documenté ;
[ ] statuts d'incertitude préservés ;
[ ] audit avant disponible ;
[ ] critères de validation après définis.

Après déploiement :

[ ] migration techniquement terminée ;
[ ] compteurs réconciliés ;
[ ] projections valides ;
[ ] Readers fonctionnels ;
[ ] audit après conforme ;
[ ] erreurs et performances surveillées ;
[ ] éventuelle ancienne structure encore nécessaire documentée.

Invariants¶

Une évolution Database reste incrémentale et explicable.
Une migration n'invente pas de décision métier.
Les consommateurs ne basculent pas avant disponibilité réelle des données.
Les projections restent dérivées et reconstruisibles.
Les statuts d'incertitude restent visibles.
Le rollback prend en compte code, schéma et données.
Un succès technique ne remplace pas la validation fonctionnelle.
Les contextes read-only ne déclenchent pas de migration implicite.