If you rename a Flyway migration file that was already executed, Flyway will treat it as a new migration and might:
- ❌ Try to re-run it (if version number changes)
- ❌ Throw a checksum error (if only filename changes)
- ✅ Require repair to fix inconsistencies
🔎 What Happens Depends On the Change
1. 🔁 Renaming a Versioned Migration (e.g., V1__init.sql → V1__initial_setup.sql)
- ✅ Same version (
V1), new description - ❌ Flyway compares checksums → checksum mismatch
- 🔒 Migration is not re-run, but Flyway throws a validation error
To fix:
flyway repair
This tells Flyway: “Yes, I deliberately changed the file name or contents — trust me.”
2. 🆕 Changing the Version (V1 → V2)
E.g., V1__init.sql → V2__init.sql
- ✅ Flyway sees this as a new migration
- ❌ It runs it again, even if the contents are identical to
V1 - ⛔ Can result in duplicate changes, errors, or schema conflicts
3. 🔁 Renaming a Repeatable Migration (R__...)
- The description part (after
R__) is the unique identifier - Renaming it → Flyway thinks it’s a new repeatable
- ✅ Re-runs the new one
- ✅ Deletes the old one from tracking
📋 Summary Table
| Scenario | Result | Solution |
|---|---|---|
| Rename file (same version, diff description) | ❌ Checksum mismatch | flyway repair |
| Rename + change version | ❌ Treated as new migration → re-run | Avoid, or manually manage |
| Rename repeatable migration | ✅ Re-run with new name, old one removed | Acceptable if intentional |
✅ Best Practices
- 🔒 Never rename versioned migration files after they are applied
- ✅ If you must rename → follow with
flyway repairto fix metadata - 🔁 Repeatable migrations can be renamed, but do it thoughtfully
- 🧪 Always test migrations in a staging DB before production
📌 Key Takeaways
✅ Renaming a Flyway migration can break integrity checks or cause re-execution
✅ Versioned migrations are sensitive to filenames and checksums
✅ Use flyway repair when you intentionally rename or edit an applied migration
❌ Avoid renaming files casually in production environments