How to use Flyway to manage database version changes in java

1 Introduction

	随着项目的不断迭代，数据库表结构、数据都在发生着变化。甚至有的业务在多环境版本并行运行。数据为王的时代，管理好数据库的版本也成为了迫切的需要。如何能做到像 Git 之类的版本控制工具来管理数据库？Java 项目中常用 Flyway 和 Liquibase 来管理数据库版本。其中 Flyway 相对来说比较受欢迎。

2. Features of Flyway

Flyway is popular because it has the following advantages:

Simple and very easy to install and learn, and the way of migration is also easy to be accepted by developers.
Dedicated Flyway focuses on database migration and version control without other side effects.
Powerful is designed for continuous delivery. Have Flyway migrate the database on application startup.

3. The working mechanism of Flyway

Flyway needs to create a metadata table in the DB first (the default table name is flyway_schema_history), in which each migration (migration) record is saved, and the record contains the version number of the migration script and the checksum value of the SQL script. The figure below represents multiple database versions.
insert image description here
Corresponding metadata table records:

Flyway scans the file system or the application's classpath to read DDL and DML for migration. Check the migration against the metadata table. If the script declares a version number less than or equal to one of the version numbers marked as current, they will be ignored. The remaining migrations are pending migrations: available, but not applied. Finally sort them by version number and execute them sequentially and write the execution result to the metadata table.

insert image description here
Corresponding metadata table records:

insert image description here
Flyway supports command line (command line tool needs to be downloaded) and Java Api, and also supports build tools Maven and Gradle. Here we focus on the Java Api.

4. Rules of Flyway

How does Flyway compare the sequence of two SQL files? It adopts the principle of left alignment, and vacancy is replaced by 0. To give a few examples:

1.0.1.1 is a later version than 1.0.1.

1.0.10 is a later version than 1.0.9.4.

1.0.10 is as high as 1.0.010 version number, leading 0's of each version number part are ignored.

Flyway divides SQL files into three types: Versioned, Repeatable and Undo:

Versioned is used for version upgrades. Each version has a unique version number and can only be executed once.
Repeatable can be executed repeatedly. When Flyway detects that the checksum of a Repeatable SQL script has changed, Flyway will reapply the script. It does not use For version updates, this type of migration is always executed after Versioned is executed.
Undo is used to undo the effects of a versioned migration with the same version. However, the rollback is too rough and too mechanized, so it is generally not recommended. It is generally recommended to use Versioned mode to solve.
These three naming rules are as follows:
insert image description here

Prefix is configurable, prefix identification, default value V means Versioned, R means Repeatable, U means Undo
Version identifies the version number, consisting of one or more numbers, and the separator between numbers can be a dot. or an underscore _
Separator is configurable, used to separate version identification and description information, the default is two underscores__
Description Description information, text can be separated by underscore_ or space
Suffix is configurable, follow-up identifier, the default is .sql

4. Spring Boot integrates Flyway

Spring Boot provides automatic configuration of Flyway. Allows us to use Flyway for database versioning out of the box.

4.1 Flyway dependencies

You just need to import dependencies:

org.flywaydb flyway-core

In order to explain the configuration intuitively, first we configure the H2 database in the Spring Boot configuration file application.yml as:

spring: datasource: # h3 driver driver-class-name: org.h3.Driver # h3 database is persisted to disk D:/h3 library name: flyway mysql mode url: jdbc:h3:file:D:/h3/flyway; MODE=MySQL;DATABASE_TO_LOWER=TRUE h3: # Enable console access default false console: enabled: true settings: # enable h3 console tracking for easy debugging default false trace: true # allow console remote access default false web-allow-others: true # h3 Access path context path: /h3-console

Of course you have to integrate your relational database environment. Here we use the H2 database to demonstrate, and other databases are the same except that the dialects are different. Those who are not familiar with the H2 database can refer to my special article Spring Boot 2 combat: H2 database integration and use.

4.2 Flyway configuration

In order to explain the configuration intuitively, first we configure the H2 database in the Spring Boot configuration file application.yml as:

flyway configuration spring: flyway: # enable or disable flyway enabled: true # flyway's clean command will delete all tables under the specified schema, and production must be disabled. The default value is false, which is theoretically unscientific as the default configuration. clean-disabled: true # SQL script directory, multiple paths separated by commas default value classpath:db/migration locations: classpath:db/migration # metadata version control information table default flyway_schema_history table: flyway_schema_history # If there is no flyway_schema_history metadata table, Before executing the flyway migrate command, you must first execute the flyway baseline command # Set it to true and then flyway will automatically execute a baseline when it needs a baseline. baseline-on-migrate: true # Specify the version number of the baseline, the default value is 1, SQL files below this version number will be ignored when migrating baseline-version: 1 # The default character encoding is UTF-8 encoding: UTF-8 # Whether to allow out-of-order migration Development suggestion true Production suggestion false out-of-order: false # Requires the schema list controlled by flyway, here we configure it as flyway default, use the schema configured by spring.datasource.url, # Yes Specify multiple schemas, but only create metadata tables under the first schema, and only apply the migration sql script to the first schema. # But the flyway Clean command will be executed under these schemas in turn.
Be sure to read the Flyway related configuration instructions carefully.

4.3 Writing SQL initialization scripts

We first write an initialization SQL file, and add a sys_user table to the schema flyway that has been automatically initialized in the H2 database. Note the naming convention. The script name is V1.0.1__Add_table_user.sql. The location of the SQL script is configured under spring.flyway.locations. The content is:

use flyway; CREATE TABLE sys_user( user_idint(10) unsigned NOT NULL AUTO_INCREMENT, usernamevarchar(1024) NOT NULL unique , encode_passwordvarchar(1024) NOT NULL, ageint(3) NOT NULL, PRIMARY KEY ( user_id) ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4; insert into flyway.sys_user values (1,'Felordcn','{noop}12345',18);
Start the Spring Boot application. Open the H2 database console http://localhost:8080/h3-console, paste jdbc:h3:file:D:/h3/flyway;MODE=MySQL;DATABASE_TO_LOWER=TRUE in the JDBC URL column and click the Connect button to enter the following interface:

How to use Flyway to manage database version changes in java

Here -1 is because we default the flyway_schema_history table required by Flyway. 0 is because the H2 database automatically initializes the Schema flyway, and other databases may require you to create it manually.

4.4 Writing SQL Change Scripts

We write a V1.0.0__Delete_sysuser_felordcn.sql to delete the users initialized in V1.0.1__Add_table_user.sql. You will find that the startup error is reported, because we have enabled the verification, so an exception will be thrown for the version with logic errors. We change the version number to V1.0.2__Delete_sysuser_felordcn.sql and start again. Through the H2 database console, we will find an additional change record:

How to use Flyway to manage database version changes in java

At the same time, the data in the sys_user table is gone, as expected.

5. Flyway Best Practices

Through the above introduction, I believe you will use Flyway for database version control soon. Here is a summary of some experience in actual development:

Production must disable spring.flyway.cleanDisabled=false.
Try to avoid using Undo mode.
The development version number should be named according to the team as much as possible to avoid confusion. For example, V1.0.1__ProjectName_{Feature|fix}_Developer_Description.sql, this kind of naming can also obtain more information about the developer of the script and related functions.
The value of spring.flyway.outOfOrder is true for production and false for development.
When multiple systems share a database schema, configure spring.flyway.table to set different metadata table names for different systems without using the default value flyway_schema_history.