Aller au contenu

Migration

Status: TARGET

À quoi sert un Migration Write Service ?

Un Migration Write Service transforme des données existantes lorsqu'un contrat, un schéma métier ou une représentation persistée évolue.

Une migration n'est pas un simple script SQL isolé. Elle traduit une évolution connue d'un état vers un autre avec des préconditions, un périmètre, des compteurs, une stratégie de reprise et une vérification finale.

Ancien état compatible
        ↓
Migration contrôlée
        ↓
Nouvel état attendu
        ↓
Validation et audit

État documentaire

Cette page décrit la cible d'architecture de la famille Migration.

Elle ne garantit pas l'existence d'un service générique de migration actif dans le Runtime. Les migrations réellement disponibles doivent être identifiées dans le code, les commandes CLI et la documentation opérationnelle avant exécution.

Migration de données ou migration de schéma ?

Les deux notions doivent rester séparées.

Une migration de schéma modifie la structure technique du stockage. Une migration métier transforme les données pour satisfaire un nouveau contrat.

Les deux peuvent être liées, mais elles ne doivent pas être confondues dans une même étape opaque. Il doit être possible de savoir ce qui change dans le schéma et ce qui change dans les valeurs métier.

Entrées attendues

Une migration doit définir :

  • version ou état source ;
  • version ou état cible ;
  • population concernée ;
  • préconditions ;
  • règles de transformation ;
  • exclusions ;
  • mécanisme de reprise ;
  • stratégie de rollback ou justification de son absence ;
  • métriques avant/après.

Ce qu'une migration ne doit jamais faire

Une migration ne doit jamais :

  • interpréter silencieusement des données ambiguës comme certaines ;
  • fusionner des identités sans politique métier validée ;
  • modifier plusieurs responsabilités sans séparation observable ;
  • utiliser le Frontend comme source de vérité ;
  • dépendre d'un ordre de lignes non déterministe ;
  • considérer une exécution partielle comme un succès complet ;
  • réexécuter des effets non idempotents sans garde-fou.

Phases recommandées

Pour une opération sensible :

1. audit de l'état source
2. sauvegarde / point de restauration
3. simulation ou dry-run
4. migration sur périmètre réduit
5. vérification
6. extension contrôlée
7. audit final

Une migration globale directe n'est acceptable que si son risque et son mécanisme de restauration sont explicitement maîtrisés.

Reprise et idempotence

Une migration volumineuse doit pouvoir reprendre après interruption.

Le service doit savoir si un élément :

  • n'a pas encore été traité ;
  • a déjà été migré ;
  • est incompatible avec la migration ;
  • a échoué techniquement.

Le rejeu ne doit pas appliquer une transformation deux fois lorsqu'elle n'est pas naturellement idempotente.

Résultat attendu

Le rapport devrait inclure au minimum :

  • examined ;
  • migrated ;
  • already_migrated ;
  • skipped ;
  • failed ;
  • version source et cible ;
  • batch ou run ;
  • avertissements ;
  • raisons d'échec.

Diagnostic

Si une migration échoue :

  1. identifier le dernier batch ou élément validé ;
  2. ne pas relancer aveuglément depuis le début ;
  3. vérifier si l'échec vient des données, du schéma ou de l'infrastructure ;
  4. mesurer l'état partiellement migré ;
  5. décider reprise ou rollback selon le contrat documenté.

Tests attendus

Tester au minimum :

  • état source valide ;
  • état source déjà migré ;
  • donnée incompatible ;
  • reprise après interruption ;
  • idempotence ou garde-fou de rejeu ;
  • compteurs réconciliables ;
  • respect des invariants métier ;
  • rollback lorsque celui-ci est supporté.

Invariants

  1. Les états source et cible sont explicites.
  2. Migration métier et migration de schéma restent distinguables.
  3. Aucun état ambigu n'est converti silencieusement en certitude.
  4. Une migration partielle est observable et reprenable.
  5. Les données sont auditées avant et après l'opération.

Voir aussi