Flyway manages database schema migrations for RapidPM. It runs automatically during deployment via Docker Compose.
| Rule | Description |
|---|---|
| Naming Convention | Files MUST be named V{version}__{description}.sql |
| Double Underscore | Use __ (two underscores) between version and description |
| Version Format | Use semantic versioning: V26_1_1_0_1 |
| No Direct Files | Never add .sql files directly to migrations/ root |
V{major}_{minor}_{patch}_{sequence}__{description}.sql
✅ V26_1_1_0_1__create_sequences.sql
✅ V26_1_1_0_2__create_tables.sql
✅ V26_2_0_1__add_user_preferences.sql
❌ add_artefact_indexes_20251128.sql (missing V prefix)
❌ fix_missing_root_containers.sql (missing version)
❌ V26.1.1__create_tables.sql (dots instead of underscores)
migrations/
├── v26.1.1/ # Version folder
│ ├── V26_1_1_0_1__create_sequences.sql
│ └── V26_1_1_0_2__create_tables.sql
└── (no loose .sql files here!)
artifacts/migrations/ # Reference only (gitignored)
└── applied/ # Manually applied migrations
└── *.sql
1. docker-compose up
2. Flyway container starts
3. Flyway scans migrations/ folder
4. Validates all filenames match pattern
5. Runs new migrations in version order
6. Exits with code 0 (success) or 1 (failure)
7. App container starts (depends on Flyway success)
app:
depends_on:
flyway:
condition: service_completed_successfully
If Flyway fails, the app will NOT start!
Check existing migrations:
ls migrations/v26.1.1/
# Format: V{version}__{description}.sql
touch migrations/v26.1.1/V26_1_1_0_3__add_new_column.sql
-- V26_1_1_0_3__add_new_column.sql
ALTER TABLE users ADD COLUMN preferences JSON;
docker-compose -f docker-compose.test.yml up flyway
git add migrations/
git commit -m "feat: add user preferences column"
git push
For migrations applied directly to production (emergency fixes):
artifacts/migrations/applied/ (gitignored)migrations/ - Flyway will failCause: Files in migrations/ without proper V{version}__ prefix
Fix:
# Move invalid files to artifacts
mv migrations/bad_file.sql artifacts/migrations/applied/
Cause: Flyway failed, blocking app startup
Check:
docker-compose logs flyway
Cause: Trying to re-run an existing migration
Fix: Flyway tracks applied migrations in flyway_schema_history table. Create a new version instead.
FROM flyway/flyway:10
COPY flyway/conf /flyway/conf
COPY migrations /flyway/sql
ENTRYPOINT ["flyway"]
| File | Environment |
|---|---|
flyway/conf/prod.conf |
Production |
flyway/conf/test.conf |
Test server |
flyway.url=jdbc:mysql://host:3306/rapidpm
flyway.user=rapidpm
flyway.password=${DB_PASSWORD}
flyway.locations=filesystem:/flyway/sql
IF NOT EXISTS