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

Le chart Helm attribue à chaque schéma un Job de migration propriétaire. Lors d'une mise à niveau, ces Jobs s'exécutent comme hooks pre-upgrade pondérés avant le déploiement des nouveaux pods d'application.

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.

Le retrait d'un produit annoncé explicitement peut supprimer une table après l'étape d'export requise pour l'opérateur. Traitez ces migrations comme des exceptions au modèle de déploiement additif habituel et suivez leur procédure propre à la version.

Retrait de l'ancien chat public Agentic

La migration 0102_remove_legacy_chat supprime la table retirée public.chat. Avant l'exécution du Job de migration, consignez le nombre de lignes et créez un export de données protégé :

psql "<agentic-database-url>" \
  -c 'SELECT count(*) AS legacy_chat_rows FROM public.chat;'

pg_dump "<agentic-database-url>" \
  --data-only --table=public.chat --column-inserts \
  > legacy-agentic-chat.sql

Cet export facilite l'inventaire et l'archivage contrôlé ; ce n'est pas une migration inverse. Le point de restauration pris en charge est un snapshot complet de la base de données Agentic réalisé avant la mise à niveau. La migration est un hook pré-mise à jour : un rollback Helm après sa réussite ne recrée pas la table, et l'ancienne application Agentic ne peut pas servir ses routes publiques de chat avec le nouveau schéma. Restaurez ensemble le snapshot complet et la révision précédente de l'application si un retour arrière complet est nécessaire.

Cette version supprime également le type de bloc de workflow hérité et masqué chat_trigger. Inventoriez les définitions de workflow avant la mise à niveau :

psql "<agentic-database-url>" \
  -c "SELECT count(*) AS legacy_chat_trigger_blocks, count(DISTINCT workflow_id) AS affected_workflows FROM public.workflow_blocks WHERE type = 'chat_trigger';"

Si l'un des nombres est différent de zéro, remplacez chaque bloc hérité par le bloc Start unifié et redéployez le workflow avant la mise à niveau. Ne modifiez pas directement le type du bloc dans PostgreSQL : les versions de déploiement immuables et les instantanés d'exécution peuvent contenir des copies distinctes de la définition du workflow. Après la mise à niveau, Agentic traite chat_trigger comme un bloc retiré inconnu et le supprime lors de la sanitisation du workflow.

Le retrait n'affecte pas les tables de conversation Cortex, les publications A2A, les checkpoints de workflow, les retours du copilote ni l'état des conversations de l'éditeur de workflow.

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 les Jobs de migration et le déploiement des workloads. Cela signifie que :

• Un rollback Helm ne désapplique pas les migrations.
• Un déploiement échoué peut déjà avoir appliqué ses migrations pré-mise à jour.
• Le propriétaire du schéma et son historique de migrations restent propres au service, même si Helm lance les Jobs.

Associé

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