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.

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.