Migrer le schéma de base de données Flower

Lorsque vous faites des modifications au schéma de base de données utilisé dans Flower, il est essentiel de créer un script de migration pour s’assurer que les bases de données existantes sur disque peuvent être mises à jour vers le nouveau schéma sans perte de données. À partir de la version Flower de 1.26.0, le cadre utilise Alembic comme outil de migration de base de données.

Ce guide décrit les étapes requises pour créer un nouveau script de migration après avoir modifié le schéma de base de données.

Pre-requisites

Installez des versions de développement de Flower selon les instructions dans Installer les versions de développement de Flower avec les dépendances dev.

Génération des Migrations

Le schéma SQL de la base de données est défini sous supercore/state/schema/. Après avoir fait des modifications au schéma (par exemple, en ajoutant une nouvelle colonne à une table), générer la révision de migration :

python -m dev.generate_migration "Descriptive message about the schema change"

Cette commande :

  1. Crée une base de données SQLite temporaire

  2. Upgrades it to all current heads

  3. Runs autogenerate to detect your schema changes, targeting flwr@head by default

  4. Generates a new migration file that extends the current flwr branch head in py/flwr/supercore/state/alembic/versions/

  5. Nettoie automatiquement la base de données temporaire

The generator does not loop over migration files itself. The alembic upgrade heads command asks Alembic to traverse the revision graph. Each revision identifies its predecessor through down_revision, so Alembic applies every pending revision in dependency order until all configured branch heads have been reached. Once the temporary database is current, the generator runs alembic revision --autogenerate with --head flwr@head. This makes the new revision extend the Flower branch instead of leaving the parent revision ambiguous when multiple heads exist. To target another configured branch, pass its branch head explicitly with --head <branch>@head.

Révision des Migrations Générées

Vérifiez toujours le fichier de migration généré avant de committer :

  • Vérifiez que les changements détectés correspondent à votre intention

  • Vérifiez la logique de migration de données si vous renommez ou supprimez des colonnes

  • Testez les chemins d’amélioration et de dégradation

Flux de travail manuel (Alternative)

Si vous préférez utiliser le CLI Alembic directement :

cd framework
alembic upgrade heads
alembic revision --autogenerate --head flwr@head \
  -m "Descriptive message about the schema change"
rm state.db  # Clean up the generated database file

Important

Use heads when upgrading so every configured migration branch is current, and explicitly select flwr@head when creating a Flower revision. The manual workflow creates a state.db file that should not be committed to git.