Migrate Flower Database Schema¶

When making changes to the database schema used in Flower, it is essential to create a migration script to ensure that existing on-disk databases can be updated to the new schema without data loss. From Flower version 1.26.0 onwards, the framework uses Alembic as our database migration tool.

This guide describes the steps required to create a new migration script after modifying the database schema.

Pre-requisites¶

Install development versions of Flower according to the instructions in Install development versions with the dev dependencies.

Generating Migrations¶

The Flower SQL database schema is defined under supercore/state/schema/. After making changes to the schema (e.g., adding a new column to a table), generate the migration revision:

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

This command:

  1. Creates a temporary SQLite database

  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. Automatically cleans up the temporary database

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.

Review Generated Migrations¶

Always review the generated migration file before committing:

  • Check that the detected changes match your intent

  • Verify data migration logic if renaming/removing columns

  • Test the upgrade and downgrade paths

Manual Workflow (Alternative)¶

If you prefer using the Alembic CLI directly:

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.