Flyway - Just Run SQL Scripts In Order

I've been using Flyway since 2019 because it solves the one problem every team has: database changes are a pain in the ass. Before Flyway, our deployments looked like this: "Hey Dave, did you run those ALTER TABLE statements on staging? What about prod? Oh shit, we forgot to update the indexes."

Now it's just `flyway migrate` and I'm done.

How Flyway Works (The 30-Second Version)

You put SQL files in a folder. Name them V1__something.sql, V2__something_else.sql. Run flyway migrate. That's it.

Flyway keeps a table called flyway_schema_history that tracks what's been run. It won't run the same migration twice, and it runs them in version order. If V3 fails, V4 through V99 won't run until you fix V3.

The genius is in what it doesn't do - no XML config files, no proprietary formats, no learning Hibernate all over again. Just SQL.

Version Reality Check

Latest version as of September 2025 is 11.11.2, released in August. Redgate owns it now (bought it in July 2019) but they haven't fucked it up. Community edition is still free and does everything most teams need.

Word of warning: they keep pushing their Enterprise edition hard. Unless you're managing 20+ databases or need automatic rollbacks (spoiler: they usually don't work anyway), stick with Community.

Why Not Just Write Database Scripts Manually?

Because you will fuck it up. Here's what happens without Flyway:

• Dev runs migration on their local DB
• QA forgets to run it on staging
• Prod deployment explodes with "column doesn't exist" errors
• You're debugging at 2am while customers are pissed

With Flyway, the same script runs everywhere in the same order. Your staging environment is exactly what prod will look like. When shit breaks (and it will), at least you know why.

The One Thing That Actually Matters

Flyway forces you to treat database changes like code changes. Every schema modification goes through version control. You can see what changed, who changed it, and when. Your database schema becomes as predictable as your application code.

This is huge for teams. No more "database guy" who's the only one allowed to touch production. No more wondering why staging acts differently than prod. No more rollback disasters.

But here's where it gets tricky: Redgate wants you to upgrade to Enterprise. The free Community edition does everything I just described perfectly. I've migrated 47 microservices with Community edition and only had 3 disasters (all my fault, not Flyway's). Whether you need to pay depends on your specific situation - let's break down what you actually get for your money.

Database Support: The Good and Ugly

Flyway claims to support 50+ databases. Here's what that actually means:

Works Great: PostgreSQL (9.6+), MySQL (5.7+), SQL Server (2016+), Oracle (12c+). These are the main targets and everything works as advertised. Full DDL support, transactional migrations where supported, clean error reporting.

Works Fine: MariaDB (10.3+), SQLite (3.7+), H2 (1.4+). Minor quirks but nothing that'll kill your deployment. SQLite's ALTER TABLE limitations might surprise you, and H2's compatibility modes can be finicky.

Works With Pain: DB2 (11.1+), Sybase ASE (16.0+), Informix (12.10+). Prepare to debug weird SQL dialect issues and non-standard error messages. Check GitHub issues before committing to these - community support is thin.

Cloud Stuff: Aurora, Azure SQL, Google Cloud SQL all work because they're just rebranded versions of the main databases above.

Trendy Data Platforms: Snowflake support is solid. BigQuery support exists but you'll hit limitations with complex DDL. MongoDB "support" is preview-only and honestly pretty buggy.

Reality Check: Unless you're using PostgreSQL, MySQL, or SQL Server, expect to spend time working around database-specific quirks.

How Migrations Actually Run

1. Flyway checks for a flyway_schema_history table. Creates one if it doesn't exist.
2. It scans your migration folder for V*__.sql files
3. Compares what's in your folder vs what's been run (stored in that history table)
4. Runs any missing migrations in version order
5. Records each successful migration with a checksum

If any migration fails, Flyway stops. No V4 until you fix V3.

File Organization That Won't Cause Pain

db/migration/
├── V1__create_users_table.sql
├── V2__add_email_index.sql
├── V3__insert_admin_user.sql
├── V4__add_password_reset_table.sql
└── V20250901__big_refactor.sql  <- dated versions for major changes

Pro tips from experience:

• Use double underscores __ not single. Single underscore breaks on some systems. Our entire CI pipeline broke when they changed this default in version 6.0.
• Keep descriptions short. Windows has path length limits that will bite you in prod.
• For big releases, I use dated versions like V20250901 so there's room for hotfixes (V20250901.1, etc.). Saved my ass during the Q4 2024 deployment disaster.

Where Flyway Falls Apart

MySQL DDL Rollback: MySQL doesn't support transactional DDL, so if your migration fails halfway through a big ALTER TABLE, you're fucked. MySQL 8.0+ added atomic DDL for some operations, but complex migrations with multiple statements still leave you in an inconsistent state. Flyway can't roll it back automatically - you'll need manual cleanup.

Checksum Hell: Change one character in an old migration? Flyway throws a fit with "Migration checksum mismatch" errors. The checksum validation uses CRC32 on file contents, which prevents you from modifying historical migrations. Usually good for preventing accidental changes, but occasionally infuriating when you need to fix a typo in V1 from three years ago.

Large Migrations: That 2-hour data migration that transforms 100M rows? Flyway will sit there and wait with zero feedback. No progress updates, no way to resume if it fails, no timeout handling. The migration either completes or your connection dies and you're left wondering what state your data is in. I learned this the hard way when our user analytics migration took down staging for 6 hours. Plan accordingly with chunked updates or external batch jobs.

Parallel Deployments: Two deployments hit the same database at once? Flyway uses a lock table (flyway_schema_history_lock) to prevent concurrent migrations, but I've still seen race conditions in high-concurrency environments cause deployments to fail with "table already exists" errors or lock timeouts exceeding 20 seconds.

Integration Reality Check

Spring Boot: Works perfectly out of the box. Just drop migration files in src/main/resources/db/migration/. See the Spring Boot integration guide. AWS RDS works perfectly. Azure SQL has weird timeout issues. Google Cloud SQL is fine but their managed backups don't snapshot mid-migration.

Docker: The official Flyway Docker image works fine for CI/CD. I use it in GitHub Actions.

Gradle/Maven: Plugins work but the configuration is verbose. Most teams just use the CLI.

Kubernetes: Works but migrations run in init containers can timeout. Set your resource limits appropriately.

These are the fundamentals, but real projects always hit edge cases. Flyway works great until you have 47 microservices all trying to migrate at deploy time. The Docker image is fine but good luck debugging why it works locally and fails in K8s. The questions below come from actual issues I've solved (or caused) over the years. If you're dealing with a broken deployment or weird migration behavior, start here.