Master Flyway with Spring Boot 3: A Step‑by‑Step Migration Guide

We announce a Spring Boot 3 practical case collection that now includes over 80 hands‑on articles, permanent updates, and downloadable source code and Markdown notes for subscribers.

1. Introduction to Flyway

Flyway is an open‑source database migration tool that manages schema changes via ordered SQL scripts. Its main features are:

Version control : each change gets a version number, preventing duplicate execution.

Cross‑platform : supports MySQL, PostgreSQL, Oracle, SQL Server, etc.

Ease of use : simple CLI and API, integrates smoothly with Spring Boot.

Automation : runs migrations automatically, aiding agile development and testing.

Using Flyway ensures every database change is versioned and applied in order, keeping development, testing, and production environments consistent.

2. Practical Flyway Example

2.1 Add Maven Dependencies

<code>&lt;dependency&gt;
  &lt;groupId&gt;org.flywaydb&lt;/groupId&gt;
  &lt;artifactId&gt;flyway-core&lt;/artifactId&gt;
&lt;/dependency&gt;

&lt;dependency&gt;
  &lt;groupId&gt;org.flywaydb&lt;/groupId&gt;
  &lt;artifactId&gt;flyway-mysql&lt;/artifactId&gt;
&lt;/dependency&gt;</code>

2.2 Configure the DataSource

<code>spring:
  datasource:
    driverClassName: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/pack?serverTimezone=GMT%2B8&amp;useSSL=false&amp;characterEncoding=UTF-8
    username: root
    password: xxxooo
    type: com.zaxxer.hikari.HikariDataSource</code>

2.3 Flyway Settings

<code>spring:
  flyway:
    enabled: true
    # Table to store migration history (default: flyway_schema_history)
    table: flyway_schema_history
    # Script encoding (default: UTF-8)
    encoding: UTF-8
    # Create baseline if history table is missing
    baseline-on-migrate: true
    # Locations of migration scripts (default: classpath:db/migration)
    locations:
      - classpath:db/migration</code>

The above configuration uses default values, so you can omit it if no custom needs exist.

2.4 Create the First Migration Script

Under db/migration create V1.0_001__create_table.sql :

<code>create table t_person (
  id int auto_increment primary key,
  name varchar(32) not null,
  sex varchar(2) not null,
  age int default 0
);</code>

This script creates the t_person table.

2.5 Run the Application

When the Spring Boot application starts, Flyway applies the script, creates flyway_schema_history , and logs the successful migration.

The console shows two key messages: the creation of the flyway_schema_history table and the successful execution of version v1.0.001 .

2.6 Verify the Database

Inspect the flyway_schema_history table to see the applied version and script details.

2.7 Add a New Migration

Create V1.1_001__update-t_person.sql with the following content:

<code>alter table t_person add column email varchar(32) default '';</code>

Restart the application; Flyway detects the new version and applies the alteration.

3. Advanced Flyway Usage

3.1 Specify Database Vendor

Use the {vendor} placeholder to load vendor‑specific scripts:

<code>spring:
  flyway:
    locations:
      - classpath:db/migration/{vendor}</code>

3.2 Multiple DataSources

When multiple data sources exist, you can define a dedicated Flyway data source:

<code>@Bean
@FlywayDataSource
DataSource flywayDataSource() {
    HikariDataSource ds = new HikariDataSource();
    ds.setJdbcUrl("jdbc:mysql://localhost:3306/msg?serverTimezone=GMT%2B8&nullCatalogMeansCurrent=true&useSSL=false&characterEncoding=UTF-8");
    ds.setDriverClassName("com.mysql.cj.jdbc.Driver");
    ds.setUsername("root");
    ds.setPassword("xxxooo");
    ds.setPoolName("flyway");
    return ds;
}</code>

Or configure Flyway’s own data source via properties:

<code>spring:
  flyway:
    url: jdbc:mysql://localhost:3306/msg?serverTimezone=GMT%2B8&nullCatalogMeansCurrent=true&useSSL=false
    user: root
    password: xxxooo</code>

These options let Flyway operate on a separate database when needed.

Overall, this guide demonstrates how to integrate Flyway into a Spring Boot 3 project, manage versioned migrations, and extend its usage for vendor‑specific scripts and multiple data sources.