Spring Boot Flyway startup: apply versioned SQL before querying a receipt

The checked non-web context

BootFlywayStartupTest starts a minimal non-web Boot context with the test-scoped spring-boot-starter-flyway. It points spring.flyway.locations at three SQL resources under db/relay-migration and selects target version 2. When run returns, the test obtains Flyway and JdbcTemplate beans and counts two versioned history entries. The old receipt insert then succeeds while tenant_id is nullable.

A second context starts against the same named H2 database with target version 3. Boot applies the remaining migration before the test reads rows. The older insert shape now fails the NOT NULL constraint; the new shape succeeds. The SQL phase lesson explains why this is a compatibility interval rather than a single schema flip.

Name the application boundary

This test proves Boot auto-configuration in a separate test application. It does not wire Flyway into the runnable ReceiptApplication. The starter is test-scoped, and the migrations are test resources. The ownership decision remains open for a real rollout.

H2 2.3.232 checks the local sequence. It does not measure DDL locks, transaction behavior or a concurrent replica deployment on the target engine. The startup path must be tested again against that engine before a production release.

Checked source

try (var context = start(uniqueH2Url, 2)) {
    assertNotNull(context.getBean(Flyway.class));
    var jdbc = context.getBean(JdbcTemplate.class);
    jdbc.update("insert into shipment_receipt(receipt_id, amount_minor) values (102, 500)");
}

Verification boundary

BootFlywayStartupTest.bootAppliesEachStageBeforeTheApplicationReadsRows. The excerpt is shortened; the source kit contains the checked fixture.

Costs and limits

This is a non-web test context, test-scoped starter and H2 database. ReceiptApplication remains without runtime Flyway wiring.

Common Mistakes

• Do not call a direct Flyway API test proof of Boot startup wiring.
• Do not put the contract migration into service before old writers retire.
• Do not infer target-engine lock time from H2.

Read next

Spring Boot migration target: test an old writer before closing the schema, Spring Boot migration history failure: stop context startup on a mismatch, Flyway SQL migrations: record ordered schema changes against a real database, Spring Boot and Flyway: choose who runs migrations before traffic starts.