Flyway uses a structured naming convention for migration files:
V<Version>__<Description>.sql
✅ The V stands for versioned migration
✅ A double underscore __ separates the version from the description
✅ The description is free-form (no spaces) and helps identify the purpose
✅ The file must end in .sql (or .java for Java-based migrations)
🔎 Detailed Breakdown
🔸 Example:
V1__create_users_table.sql
V2__add_email_column.sql
V3__create_orders_table.sql
V1, V2, V3 → version numbers (can be integers or dotted like 1.1, 2.5.3)
__ (double underscore) → required separator
create_users_table → optional human-readable description (use snake_case)
🧪 Special File Types
| Type | Naming Format | Purpose |
|---|---|---|
| Versioned | V1__init.sql | Run in order, exactly once |
| Undo | U1__undo_init.sql | (optional) Used to undo versioned migration V1 |
| Repeatable | R__refresh_materialized_view.sql | Re-run when file checksum changes |
⚠️ Important Notes
- Versions must increase monotonically (
V1,V2,V3, …) - Descriptions must not contain spaces
- Flyway sorts migrations based on version number
- You cannot have two migrations with the same version
✅ File System Example
/resources/db/migration/
├── V1__init_schema.sql
├── V2__add_users_table.sql
├── V3__add_roles_table.sql
├── R__refresh_views.sql
📌 Key Takeaways
✅ The standard Flyway naming pattern is V<version>__<description>.sql
✅ Use U<version>__... for undo and R__... for repeatable migrations
✅ Naming is how Flyway orders, tracks, and applies migrations safely