Spring Boot and Flyway: choose who runs migrations before traffic starts

What this kit actually does

The downloadable kit now declares spring-boot-starter-flyway with test scope. FlywayReceiptMigrationTest creates a Flyway instance directly; BootFlywayStartupTest also checks a separate non-web Boot context. ReceiptApplication still does not enable a runtime migration path. The generated SQL files sit under db/relay-migration, away from Boot’s conventional db/migration path. This separation keeps a reader from mistaking a checked teaching fixture for a production rollout.

If an application startup owns migrations, coordinate concurrent replicas and readiness so none serves a schema it cannot read. If a deployment job owns them, make the job idempotent and gate the rollout on its result. Choose one owner. The API test proves ordered local execution, not either deployment arrangement.

Match dependency scope to ownership

Moving Flyway to runtime and placing scripts in the configured location is a deliberate application change. The target database may need an additional Flyway database module. Run the exact scripts against a disposable instance of that engine before promotion. Test old and new application versions across V2; after V3 the old writer is intentionally incompatible.

Never start a long, unbounded data backfill on every replica. A migration tool records versions; it does not decide business ownership for historical rows or guarantee zero lock time. The staged rollout names those decisions.

Checked source

<!-- The source kit keeps this test-only. Runtime rollout requires an owner. -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-flyway</artifactId>
  <scope>test</scope>
</dependency>

Verification boundary

FlywayReceiptMigrationTest uses Flyway.configure() directly; BootFlywayStartupTest checks a separate non-web Boot context. ReceiptApplication does not run Flyway at startup. The excerpt is shortened or a labelled design sketch; the kit contains the checked tests.

Costs and limits

A separate non-web Boot auto-configuration test now checks local startup on H2. No production database module, concurrent-replica deployment job, readiness gate or target-engine migration is checked.

Common Mistakes

• Do not call a test-scoped dependency production migration wiring.
• Do not let both a job and every replica own the same rollout without a deliberate coordination plan.
• Do not assume migration history proves the application can read all legacy rows.

Read next

Flyway SQL migrations: record ordered schema changes against a real database, Flyway expand and contract: show exactly when an old writer breaks, Spring readiness: report an unavailable dependency without forcing liveness failure, Spring schema rollout tests: check old and new writers at every phase.

Continue with checked Boot startup

Continue with Spring Boot Flyway startup: apply versioned SQL before querying a receipt, Spring Boot migration tests: distinguish a test starter from a runtime rollout.