Database migrations are essential for maintaining consistent database schemas across environments. While SQL-based migrations handle most scenarios effectively, Java-based Flyway migrations offer additional flexibility for complex data transformations, business logic integration, and operations that would be cumbersome in pure SQL.
However, testing these Java migrations presents unique challenges that we need to address to maintain reliable database evolution.
This article explores how to implement and test Java-based Flyway migrations in Spring Boot applications, covering isolation strategies and addressing common testing pitfalls.
Understanding Java-Based Flyway Migrations
Java-based migrations provide capabilities beyond what SQL migrations can offer.
We might choose Java migrations when we need to perform complex data transformations, integrate with external services during migration, or leverage existing business logic components. These migrations implement Flyway’s JavaMigration interface and execute within our application’s context.
Here’s a simple example where we need to populate a new field based on existing data:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
@Component public class V2__PopulateUserDisplayNames implements JavaMigration { @Override public Integer getVersion() { return 2; } @Override public String getDescription() { return "Populate display names for existing users"; } @Override public void migrate(Context context) throws Exception { JdbcTemplate jdbcTemplate = new JdbcTemplate( new SingleConnectionDataSource(context.getConnection(), true)); String updateSql = """ UPDATE users SET display_name = CONCAT(first_name, ' ', last_name) WHERE display_name IS NULL """; jdbcTemplate.update(updateSql); } } |
This migration demonstrates a common scenario where we need to compute values based on existing data. While we could accomplish this with SQL, the Java approach allows us to leverage Spring’s JdbcTemplate for more robust database operations and potentially integrate more complex business logic when needed.
Let’s also create the foundation SQL migration that this Java migration builds upon:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
-- V1__Create_users_table.sql CREATE TABLE users ( id BIGINT PRIMARY KEY AUTO_INCREMENT, first_name VARCHAR(100) NOT NULL, last_name VARCHAR(100) NOT NULL, email VARCHAR(255) UNIQUE NOT NULL, display_name VARCHAR(255), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); INSERT INTO users (first_name, last_name, email) VALUES |
The Challenge of Testing Java Migrations
Testing Java-based Flyway migrations presents several challenges that don’t exist with SQL migrations. The primary issue emerges when we use @SpringBootTest – Spring Boot automatically runs all migrations during application startup, including the Java migration we want to test.
This means our migration has already executed before our test code runs, making it impossible to verify the migration’s behavior properly.
Additionally, we often need to establish a specific database state before running our Java migration. We might need test data that represents the “before” state, allowing us to verify that our migration transforms the data correctly.
Testing Strategy: Controlling Migration Execution
To test Java migrations effectively, we need to control when Flyway executes our specific migration. We accomplish this by using Spring Boot’s Flyway configuration properties to limit which migrations run during application startup, then manually triggering our target migration within the test.
Here’s how we can structure an integration test for our Java migration:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
@SpringBootTest @TestPropertySource(properties = { "spring.flyway.target=1" }) class PopulateUserDisplayNamesTest { @Autowired private JdbcTemplate jdbcTemplate; @Autowired private Flyway flyway; @Test void shouldPopulateDisplayNamesForExistingUsers() { List<Map<String, Object>> usersBefore = jdbcTemplate.queryForList( "SELECT id, first_name, last_name, display_name FROM users" ); assertThat(usersBefore).hasSize(3); assertThat(usersBefore).allSatisfy(user -> assertThat(user.get("display_name")).isNull() ); flyway.migrate(); List<Map<String, Object>> usersAfter = jdbcTemplate.queryForList( "SELECT id, first_name, last_name, display_name FROM users" ); assertThat(usersAfter).hasSize(3); assertThat(usersAfter).anySatisfy(user -> { assertThat(user.get("first_name")).isEqualTo("John"); assertThat(user.get("last_name")).isEqualTo("Doe"); assertThat(user.get("display_name")).isEqualTo("John Doe"); }); assertThat(usersAfter).anySatisfy(user -> { assertThat(user.get("first_name")).isEqualTo("Jane"); assertThat(user.get("last_name")).isEqualTo("Smith"); assertThat(user.get("display_name")).isEqualTo("Jane Smith"); }); } } |
The key elements of this testing strategy are:
spring.flyway.target=1– This property tells Flyway to only run migrations up to version 1, stopping before our Java migration- Manual migration execution – We inject Flyway and call
migrate()to run the remaining migrations, including our Java migration - Before and after verification – We verify the database state before and after migration execution
Summary
Java-based Flyway migrations provide powerful capabilities for complex database transformations, but they require careful testing strategies. By controlling migration execution through Spring Boot properties and manually triggering migrations in our tests, we can verify that our Java migrations work correctly.
The key principles for testing Java migrations effectively are: limit initial migration execution using spring.flyway.target, establish the required pre-migration database state, manually execute the migration under test, and verify the results. While this approach requires fresh databases for each Flywyay test, it provides the isolation necessary to test migration behavior reliably.
Remember to implement checksum generation for Java migrations to help Flyway detect changes over time. Although testing Java migrations requires more setup than SQL migrations, the investment ensures that our complex database transformations work correctly across all environments.
Java migrations fill an important gap in database evolution capabilities, and with proper testing strategies, we can use them confidently to handle scenarios that would be difficult or impossible with SQL alone.
Joyful testing,
Philip
