Migrations de base de données

Chaque mise à jour Scrydon peut inclure des migrations de base de données. Ce runbook couvre ce qui s'exécute, comment vérifier et comment gérer une migration échouée.

Fonctionnement des migrations

Lors d'une mise à jour, chaque service Scrydon propriétaire d'un schéma exécute ses propres migrations au démarrage. Le premier pod de chaque déploiement progressif applique la migration ; les pods suivants voient la migration comme déjà appliquée et la sautent.

Les migrations sont conçues pour être unidirectionnelles. Aucune migration inverse n'est fournie ; si vous devez revenir en arrière, restaurez depuis une sauvegarde.

Ce que fait une migration

Les migrations consistent généralement à :

• Ajouter une nouvelle colonne (ADD COLUMN ... NULL).
• Remplir des données dérivées en arrière-plan.
• Ajouter un index en mode CONCURRENTLY.
• Déprécier doucement une colonne (renommée, puis lue depuis la nouvelle + l'ancienne, puis lue uniquement depuis la nouvelle, puis supprimée).

Les migrations qui bloqueraient les écritures pendant plus de quelques secondes sont découpées en plusieurs versions — la plateforme ne livre jamais une migration unique qui verrouille toute la table sur une grande table.

Vérifier qu'une migration a été exécutée

# Find the migration version
kubectl exec -it deploy/api-platform -n scrydon-platform -- \
  psql "$DATABASE_URL" -c "SELECT version, applied_at FROM platform_migrations ORDER BY applied_at DESC LIMIT 5;"

Chaque service dispose de sa propre table de migrations.

Gestion d'un échec de migration

Si un pod échoue à appliquer une migration, il reste en état CrashLoopBackOff. L'erreur de migration apparaît dans les journaux du pod.

Procédure de récupération :

1. Lisez les journaux du pod en échec.
2. Identifiez la version de migration et l'instruction SQL qui a échoué.
3. Choisissez entre trois chemins :
   • Corriger et avancer : appliquer un correctif à la migration en échec. Redémarrer le pod.
   • Ignorer la migration (si vous avez décidé que c'est sûr) : marquer la migration comme appliquée dans la table des migrations manuellement et redémarrer.
   • Restaurer depuis une sauvegarde : revenir à l'état avant la mise à jour. Restaurez PostgreSQL depuis le snapshot pris avant la mise à jour.

Prenez toujours un snapshot PostgreSQL avant de démarrer une mise à jour. Le runbook de mise à jour le précise explicitement.

Désynchronisation du suivi des migrations

La tâche de migration vérifie sa table de suivi par rapport au schéma réel de la base de données à chaque exécution. Si la table de suivi prétend que des migrations sont appliquées alors que leurs objets n'existent pas, la tâche échoue avec :

[migrate-bootstrap] FATAL: the migration tracking table is out of sync with
the actual database schema — it claims migrations are applied whose objects
do not exist. This is a tracking desync, not a migration bug.

Lorsque le message propose MIGRATE_REPAIR_TRACKING=1 (« Re-run with MIGRATE_REPAIR_TRACKING=1 to rewind tracking from ... »), l'état est réparable automatiquement de manière prouvée : les migrations concernées n'ont laissé aucun objet derrière elles, donc les ré-appliquer ne peut pas entrer en conflit avec des données existantes. Activez la réparation via l'indicateur de values du service concerné :

# surcharge de values pour le service concerné uniquement — auth, analytics,
# cortex, apiOntology ou agentic
analytics:
  migration:
    repairTracking: true

Relancez ensuite helm upgrade. La tâche de migration rembobine les lignes faussement suivies et ré-applique les migrations dans l'ordre.

Si le message d'échec signale au contraire un état partiel ou non contigu, la réparation automatique refuse de s'exécuter par conception — contactez le support avant de toucher manuellement à la table de suivi.

Remplissages de longue durée

Certaines mises à jour introduisent un remplissage (population d'une nouvelle colonne à partir de données existantes). Pour les grands ensembles de données, le remplissage s'exécute comme une tâche d'arrière-plan distincte, sans bloquer le déploiement progressif.

La progression est visible dans le journal d'audit sous forme d'événements MIGRATION_BACKFILL_*. La tâche peut être mise en pause, reprise ou redémarrée là où elle s'est arrêtée.

Ce que helm upgrade ne touche pas

helm upgrade orchestre le déploiement mais ne touche pas lui-même la base de données. Les services appliquent leurs propres migrations au démarrage. Cette séparation signifie que :

• Un rollback Helm ne désapplique pas les migrations.
• Un upgrade Helm échoué où les pods ont refusé de démarrer a généralement laissé le schéma inchangé.
• L'historique des migrations appartient au service, pas à Helm.

Associé

• Runbook de mise à jour — procédure complète de mise à jour.
• Sauvegarde et restauration — le chemin de retour en arrière.