Migrations de données
Exécute une migration de données écrite en Go, désignée par son nom, embarquée dans la version livrée.
Fonctionnement
Certains changements ne s’expriment pas en SQL : réécrire des charges utiles d’événements au nouveau format binaire, normaliser des données héritées, recalculer des champs dérivés. Chacun de ces changements est livré comme migration codée — une tâche — dans l’application.
Vous exécutez une tâche à la fois, en la nommant. Il n’existe délibérément aucun mode « tout exécuter » : balayer toutes les migrations d’un coup est sans limite et traverse tous les espaces de travail, et il suffisait auparavant de laisser un champ vide pour y parvenir. Le champ Task est obligatoire, et sa liste déroulante affiche exactement les tâches enregistrées par la version déployée.
Une exécution procède ensuite ainsi :
- Prévisualisation par défaut — avec Apply désactivé, la tâche indique ce qu’elle modifierait, sans rien écrire. Lisez d’abord la prévisualisation ; c’est précisément à cela qu’elle sert
- N’écrit que sur votre ordre — activez Apply pour valider. Le formulaire exige une confirmation préalable, car les modifications sont écrites dans tous les espaces de travail concernés et ne peuvent pas être annulées
- Reconstruit éventuellement les projections — une tâche qui modifie des charges utiles d’événements d’une manière que les projections doivent réobserver le déclare en tant que suite. Une fois l’exécution terminée, le worker planifie Reconstruction des projections d’employés comme nouvelle exécution. Cette exécution chaînée apparaît dans l’interface d’administration comme une entrée distincte démarrée strictement après la fin de l’exécution de migration
Quand elle s’exécute
La tâche est pilotée par l’opérateur. Elle est enregistrée auprès du worker mais ne se déclenche jamais seule — l’API ne l’exécute pas au démarrage. Déclenchez-la lorsqu’une migration est nécessaire, depuis . Elle ne peut être exécutée que depuis l’espace de travail système et n’apparaît dans aucun autre espace de travail.
Le déclenchement automatique a été désactivé parce que des répliques d’API mises à l’échelle automatiquement mettraient chacune en file une exécution en double, et que des exécutions concurrentes sur les mêmes lignes provoquent de la contention en base et un flot d’événements de rejeu.
Paramètres
| Paramètre | Obligatoire | Signification |
|---|---|---|
| Task | Oui | La migration à exécuter, choisie parmi les tâches enregistrées. Une exécution qui ne nomme aucune tâche est rejetée avant tout travail — de même qu’un nom non enregistré |
| Apply | Non | Désactivé (par défaut), prévisualise sans écrire, pour les tâches qui le prennent en charge ; les tâches qui écrivent toujours l’ignorent. Activé, valide les modifications, qui sont alors irréversibles |
| Employee | Non | Restreint une tâche cadrée à un seul employé — utile pour tester sur un employé avant une exécution globale. Les tâches qui balaient toujours globalement l’ignorent |
L’API programmatique accepte les mêmes options, plus workspace_id pour restreindre une tâche cadrée à un espace de travail ; il n’existe pas de sélecteur d’espace de travail dans le formulaire.
{"jobs":["migrations"],"options":{"tasks":["<nom-de-tâche>"]}}
{"jobs":["migrations"],"options":{"tasks":["<nom-de-tâche>"],"apply":true}}Les options fournies à une exécution apparaissent dans la colonne Paramètres de la liste des exécutions. Cette colonne est masquée par défaut — activez-la depuis le menu des colonnes pour distinguer deux exécutions de la même tâche.
Résultats de la tâche
Le résultat porte dry_run (l’inverse d’Apply) et une clé par tâche exécutée :
| Clé | Signification |
|---|---|
dry_run | true lorsque rien n’a été écrit — l’exécution n’a fait que prévisualiser |
applied | Indique si la tâche a réellement écrit ses modifications |
affected_count | Le nombre d’entités touchées, ou qui le seraient |
by_workspace | Les comptes par espace de travail, avec les noms résolus |
details | Les entités touchées, avec le détail avant/après que la tâche enregistre |
Un nom qui ne correspond à aucune tâche enregistrée apparaît sous la forme "unknown task" en regard de ce nom.
Lorsqu’une tâche marquée « reconstruit les projections » s’exécute, le résultat contient aussi next_jobs: ["rebuild-employee-projections"], et le worker planifie automatiquement cette tâche.
Relance
Toutes les tâches enregistrées peuvent être relancées à la demande. La requête de sélection de chaque tâche écarte les lignes déjà migrées : une relance après un succès partiel reprend là où la précédente s’est arrêtée, et relancer une tâche terminée ne fait rien et signale zéro entité touchée.
Dépannage
| Problème | Solution |
|---|---|
| « No task selected » | Choisissez une tâche dans le champ Task. Il n’existe pas de mode « tout exécuter » — nommer la tâche est la seule façon de lancer cette tâche |
L’exécution signale "unknown task" | Le nom n’est pas enregistré dans la version déployée — le plus souvent une tâche retirée depuis. Choisissez dans la liste plutôt que de saisir un nom |
| Run Job reste désactivé | Apply est activé et la confirmation en dessous n’est pas cochée. Lisez l’avertissement et cochez la case, ou désactivez Apply pour prévisualiser à la place |
affected_count vaut 0 | La tâche n’a aucune ligne en attente — l’état normal une fois qu’elle est terminée |
| Erreurs pendant une tâche | Ouvrez le détail de l’exécution. Les erreurs par ligne y figurent ; l’échec de toute l’exécution traduit en général une condition fatale. Corrigez les données et relancez |
| La reconstruction des projections n’a pas suivi | Si l’exécution n’a pas atteint l’état « completed » (échec en cours de route), la suite n’est pas déclenchée. Corrigez l’échec, relancez la tâche, puis relancez Reconstruction des projections d’employés manuellement si nécessaire |