Database Best Practices¶

Status: CONTRACT

Rôle¶

Cette page complète les règles Database avec une méthode pratique pour concevoir, modifier et exploiter les structures persistées sans casser les frontières de CMonChoix Platform.

Elle ne remplace ni les contrats métier, ni les migrations, ni les procédures Operations. Elle aide à préparer un changement et à vérifier qu'il reste explicable, réversible lorsque nécessaire et compatible avec les consommateurs.

Avant de toucher au schéma¶

Commencer par identifier :

le problème observé ;
la table ou famille concernée ;
le producteur de la donnée ;
les Readers qui la consomment ;
le Write Service ou mécanisme d'écriture ;
le run, snapshot ou périmètre touché ;
le caractère source, intermédiaire, métier, dérivé ou technique de la donnée.

Ne pas partir d'une table puis inventer sa responsabilité a posteriori.

Préférer une observation read-only¶

Avant toute mutation, mesurer l'état réel :

volumes ;
nulls ;
doublons ;
fraîcheur ;
distribution des statuts ;
relations cassées ;
écarts entre source et projection.

Une observation SQL doit rester une observation. Elle ne valide pas automatiquement une correction métier.

Garder les populations réconciliables¶

Lors d'un audit ou d'une migration, les compteurs doivent permettre d'expliquer toute la population.

Par exemple :

examined
= changed
+ unchanged
+ skipped
+ failed

Pour la résolution, conserver explicitement les statuts resolved, unknown, ambiguous et conflict au lieu de fusionner les cas difficiles dans une catégorie générique.

Concevoir les écritures comme des opérations explicites¶

Une mutation importante doit avoir :

un périmètre borné ;
des préconditions ;
un résultat structuré ;
des compteurs ;
une stratégie de reprise ;
un mode dry-run ou une simulation lorsque pertinent ;
un rollback ou une justification documentée de son absence.

Les commandes, interfaces admin et endpoints HTTP restent des adapters : ils délèguent l'écriture à une façade ou un Write Service.

Idempotence¶

Lorsqu'une opération peut être rejouée, elle doit distinguer au minimum :

réellement modifié ;
déjà conforme ;
ignoré par politique ;
en échec.

Un second lancement ne doit pas dupliquer les effets ni dégrader un état valide.

Reconstruire plutôt que patcher une projection¶

Une projection est dérivée.

En cas d'écart :

vérifier la donnée source ;
vérifier le calcul ou Builder ;
vérifier le Write Service ;
vérifier l'état de persistance ;
reconstruire explicitement si nécessaire ;
auditer le résultat.

Éviter l'UPDATE manuel qui rend la projection visuellement correcte mais impossible à reproduire.

Préparer les migrations¶

Pour une migration de schéma ou de données :

documenter l'état initial ;
définir le périmètre ;
vérifier la sauvegarde/restauration adaptée au risque ;
simuler lorsque possible ;
exécuter par lots si le volume l'impose ;
rendre l'interruption visible et reprenable ;
mesurer l'état final ;
auditer les consommateurs et projections touchés.

Une migration ne doit pas être déclenchée par un simple bootstrap read-only.

Index et performances¶

Ajouter ou modifier un index uniquement après mesure d'une requête ou d'un chemin réellement coûteux.

Vérifier :

sélectivité ;
coût d'écriture ;
taille ;
requêtes concernées ;
impact sur les rebuilds ;
comportement sur un jeu de données représentatif.

Ne pas optimiser une requête qui existe uniquement parce qu'une mauvaise couche contourne les Readers ou projections prévus.

Nommage et documentation¶

Pour une nouvelle structure, documenter au minimum :

son rôle ;
son owner logique ;
son producteur ;
ses principaux consommateurs ;
sa durée de vie ;
son caractère reconstruisible ou non ;
son mécanisme de migration/dépréciation.

Le nom doit aider à comprendre la responsabilité sans ouvrir plusieurs fichiers de code.

Données historiques¶

Un état historique peut être contaminé par un ancien comportement destructif ou une ancienne règle.

Avant de l'utiliser comme baseline :

identifier la version de code ;
vérifier si une mutation historique a altéré les données ;
reconstruire les projections si nécessaire ;
refaire l'audit sur un état fiable.

Un snapshot contaminé reste utile pour comprendre l'incident, pas comme référence de validation.

Production : ordre sûr d'intervention¶

Observation
  ↓
Audit
  ↓
Hypothèse
  ↓
Simulation / dry-run
  ↓
Sauvegarde si nécessaire
  ↓
Écriture explicite
  ↓
Vérification SQL read-only
  ↓
Audit métier
  ↓
Surveillance

Une vérification SQL après écriture confirme l'état persistant ; l'audit métier confirme que cet état produit le résultat attendu.

Ce qu'il faut éviter¶

écrire depuis un renderer Frontend ;
utiliser $wpdb dans une couche qui devrait passer par un Reader/Repository ;
mettre une décision métier dans une migration SQL ;
corriger un conflict en forçant une valeur en base ;
supprimer les unknowns pour améliorer artificiellement un KPI ;
reconstruire une projection sans identifier son dataset source ;
lancer une opération large sans limite, compteurs ou reprise ;
considérer dry-run comme preuve de non-mutation sans test réel ;
changer simultanément schéma, règle métier et projection sans pouvoir isoler les effets.

Checklist de revue¶

Avant merge ou déploiement d'un changement Database, vérifier :

[ ] responsabilité de la structure claire ;
[ ] source de vérité inchangée ;
[ ] statuts d'incertitude préservés ;
[ ] readers/writers identifiés ;
[ ] aucun transport ou Frontend propriétaire de l'écriture ;
[ ] migration explicite ;
[ ] reprise/idempotence vérifiées lorsque nécessaire ;
[ ] rollback ou restauration documenté ;
[ ] projections reconstruisibles ;
[ ] compteurs réconciliables ;
[ ] audit avant/après disponible ;
[ ] aucune mutation implicite dans un contexte read-only.

Invariants¶

Mesurer avant de modifier.
Une mutation est explicite et bornée.
Une projection se reconstruit ; elle ne se patch pas comme vérité primaire.
Les statuts d'incertitude restent visibles.
Les migrations sont traçables et reprenables selon le risque.
Les performances sont optimisées à partir de mesures.
SQL confirme un état persistant ; il ne remplace pas l'audit métier.
Un contexte read-only reste réellement read-only.