Flyway Database Migration Tool: Concepts, Commands, and Spring Boot Integration

Flyway is a lightweight database migration (migration) tool that runs SQL or Java scripts automatically when an application is deployed, ensuring that the database schema stays in sync with the code.

What problem does Flyway solve?

It manages the execution order of migration scripts, compares them with the metadata stored in the database, and applies any missing scripts, eliminating manual schema updates.

Types of migrations in Flyway

Versioned Migrations : Executed once per version, identified by a version number (e.g., V1.0__Init_DB.sql ); used for creating or altering tables and inserting data.

Undo Migrations : Reverse operations of versioned migrations (available only in the paid edition).

Repeatable Migrations : Can be re‑executed multiple times, identified by a description but no version number; ideal for views, stored procedures, etc.

The file naming convention is Prefix + Version + __ + Description + .sql , where the prefix is V for versioned, U for undo, and R for repeatable.

Common Flyway commands

Migrate : Scans the classpath for migration files, compares them with the metadata table, and applies any pending migrations.

Clean : Drops all objects in the configured schema (useful for dev/test, never on production).

Info : Prints detailed information about all migrations and their current state.

Validate : Checks that applied migrations match the checksum of the local scripts.

Undo : Rolls back the last versioned migration (paid feature).

Baseline : Creates a baseline entry in an existing database so Flyway can start managing it.

Repair : Repairs the Flyway metadata table when it becomes corrupted.

Spring Boot integration

Spring Boot’s auto‑configuration already includes Flyway support. Add the required dependencies to pom.xml :

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.28</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>
    <version>8.5.7</version>
</dependency>

Configure Flyway in application.yml (or application.properties ):

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test_db_flyway?useSSL=false&autoReconnect=true&characterEncoding=utf8
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: root
    password: your_password
  flyway:
    enabled: true
    encoding: UTF-8
    locations: classpath:db/migration
    validate-on-migrate: true

Sample migration scripts

Versioned migration V1.0__Init_DB.sql creates a tb_user table:

DROP TABLE IF EXISTS `tb_user`;
CREATE TABLE `tb_user` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `user_name` varchar(45) NOT NULL,
  `password` varchar(45) NOT NULL,
  `email` varchar(45) DEFAULT NULL,
  `phone_number` int(11) DEFAULT NULL,
  `description` varchar(255) DEFAULT NULL,
  `create_time` datetime DEFAULT NULL,
  `update_time` datetime DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8;

Repeatable data migration V1.1__Init_Data.sql inserts a sample user:

INSERT INTO `tb_user` (id, user_name, password, email, phone_number, description, create_time, update_time)
VALUES (1, 'pdai', 'dfasdf', '[email protected]', 1212121213, 'afsdfsaf', '2021-09-08 17:09:15', '2021-09-08 17:09:15');

Running the application

When the Spring Boot application starts, Flyway logs show the validation and migration steps, creation of the flyway_schema_history table, and execution of the two migrations. Sample log excerpts are included in the original article.

Notes

Undo migrations, Baseline, and Repair are only available in the commercial edition.

Be aware of MySQL warnings about character set aliases and integer display width deprecation.

The article ends with an invitation to discuss the content, join the author’s architecture community, and obtain additional resources via WeChat public‑account replies.