Flyway guide with solutions to common issues

Common Issues

• Checksum Mismatch
  • Why this happens
  • Fixing Checksum Mismatch (Local Only)

Rule of Thumb

Once a Flyway migration has been applied:

• Do not edit the SQL file
• Create a new migration instead

Checksum Mismatch

Checksum mismatch error in logs

TL;DR Flyway migrations are immutable once applied. If you modify an already-applied SQL script during local development, Flyway will fail with a checksum mismatch. This guide explains why that happens and how to safely reset your local DB state.

Flyway thinks you have changed the existing migration files, why?

When the application is launched for the first time, Flyway applies all migration files and stores their checksums in flyway_schema_history.

On every subsequent launch, Flyway recalculates the checksum for each migration file and compares it with the stored value to ensure that already-applied migrations have not changed.

If you modify an applied migration file and run the application again, Flyway detects the mismatch and fails fast with a checksum error.

flyway_schema_history table after successful migration

Now under normal circumstances, once changes are made to production environment you would have to add a new SQL script for any new changes.

During local development, requirements can change frequently.
If a migration has not yet been merged or deployed, it is reasonable to update the same migration file instead of creating multiple incremental migrations on a single branch.

Initially applied migration file

Newly added changes in same migration file

Fixing Checksum Mismatch (Local Only)

Important
The steps in this guide are ONLY for local development.
Never delete entries from flyway_schema_history in production databases.

• change directory to your application folder from root of project

  cd /application/

• you should see the database file

• use sqlite3 to open interactive shell sqlite3 <database_file_name>.db

• check flyway_schema table

  SELECT * FROM flyway_schema_history

• Drop the problematic schema(script that you added during local development)

  DELETE FROM flyway_schema_history WHERE version = <VERSION_NUMBER_OF_APPLIED_SCHEMA>

NOTE
At this point, Flyway no longer knows that the migration was applied, but the database schema still reflects those changes. You must manually drop any tables or columns introduced by that migration to fully revert the database state.

After this, Flyway will treat the migration as new and apply it again using the updated SQL.