Flyway数据库迁移工具全面指南：从入门到项目整合

Flyway是一款开源数据库版本控制工具，通过管理SQL脚本版本确保不同环境数据库结构的一致性。其核心原理是通过元数据表记录迁移历史，按版本顺序执行SQL脚本。基本使用包括规范命名脚本（V前缀版本化/R前缀可重复）、存放在默认目录（db/migration），并支持Spring Boot自动整合（添加依赖即可）。高级功能涵盖多环境配置、基线化已有数据库、Java迁移和回调机制。常见问题包括脚本校验

itzixiao

975人浏览 · 2025-06-18 22:52:44

itzixiao · 2025-06-18 22:52:44 发布

文章目录

Flyway是一款简单易用的开源数据库版本控制工具，它通过管理SQL脚本的版本，帮助开发团队在不同环境中保持数据库结构的一致性。本文将详细介绍Flyway的核心概念、工作原理以及如何在Java项目中整合使用Flyway。

一、Flyway核心概念与工作原理

1.1. Flyway是什么

Flyway是一款数据库版本控制管理工具，可以像Git管理代码版本那样管理数据库的变更历史。它的主要特点包括：

简单直接：使用纯SQL脚本进行数据库变更，无需学习额外语法
版本控制：通过脚本文件名中的版本号严格管理执行顺序
自动执行：项目启动时自动检测并执行未应用的迁移脚本
多环境一致：确保开发、测试、生产环境的数据库结构一致

1.2. Flyway工作原理

Flyway的工作流程如下：

初始化阶段：首次运行时，Flyway会在目标数据库中创建一个名为flyway_schema_history的元数据表，用于记录迁移历史
脚本扫描：Flyway扫描指定目录(默认classpath:db/migration)下的SQL脚本文件
版本比对：将扫描到的脚本版本与flyway_schema_history表中的记录进行比对
迁移执行：
- 对于版本号高于已应用最高版本的脚本，按版本号顺序依次执行
- 对于已应用的脚本，校验其checksum值，确保未被修改
记录更新：成功执行脚本后，在flyway_schema_history表中记录执行详情

二、Flyway基本使用

2.1. 环境准备

使用Flyway需要以下基础环境：

JDK 1.8+
Spring Boot 2.x+ (可选，简化整合)
支持的数据库(MySQL、PostgreSQL、Oracle等)

2.2. SQL脚本命名规范

Flyway对SQL脚本文件名有严格规范，主要分为两类：

版本化迁移脚本(V前缀)：

V<Version>__<Description>.sql

例如：V1__Create_user_table.sql、V2.1__Add_email_column.sql

可重复迁移脚本(R前缀)：

R__<Description>.sql

例如：R__Update_user_roles.sql

命名规则说明：

V/R：必须大写，表示脚本类型
<Version>：版本号，可以使用数字和点/下划线(如1.2.3或1_2_3)
__：两个下划线分隔版本和描述
<Description>：描述文本，建议简明扼要
.sql：固定后缀

2.3. 脚本存放位置

默认情况下，Flyway会在以下位置查找迁移脚本：

classpath:db/migration

可以通过配置修改此位置

三、Java项目整合Flyway

3.1. Spring Boot项目整合

Spring Boot提供了对Flyway的自动配置支持，整合非常简单：

3.1.1 添加Maven依赖

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

如果使用Spring Boot，版本号可以省略，使用Spring Boot管理的版本即可

3.1.2 配置数据源和Flyway

在application.yml或application.properties中添加配置：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_database
    username: your_username
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
    
  flyway:
    enabled: true  # 启用flyway
    baseline-on-migrate: true  # 当数据库非空且无flyway元数据表时，自动初始化
    locations: classpath:db/migration  # 脚本位置
    validate-on-migrate: true  # 迁移时校验脚本
    out-of-order: false  # 是否允许无序迁移(生产环境建议false)
    clean-disabled: true  # 禁用clean命令(生产环境必须为true)

3.1.3 创建迁移脚本

在resources/db/migration目录下创建SQL脚本文件，例如：

V1__Initial_schema.sql:

CREATE TABLE user (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

V2__Add_user_status.sql:

ALTER TABLE user ADD COLUMN status VARCHAR(20) DEFAULT 'ACTIVE';

3.1.4 启动应用

启动Spring Boot应用时，Flyway会自动执行未应用的迁移脚本

3.2. 传统Java项目整合

对于非Spring Boot项目，可以通过编程方式使用Flyway：

3.2.1 添加Maven依赖

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>8.5.0</version> <!-- 使用最新版本 -->
</dependency>

3.2.2 编程方式配置

import org.flywaydb.core.Flyway;

public class FlywayMigration {
    public static void main(String[] args) {
        // 配置Flyway
        Flyway flyway = Flyway.configure()
            .dataSource("jdbc:mysql://localhost:3306/your_db", "user", "password")
            .baselineOnMigrate(true)
            .locations("db/migration")
            .load();
        
        // 执行迁移
        flyway.migrate();
    }
}

3.2.3 执行迁移

运行上述代码即可执行数据库迁移

四、Flyway高级配置与使用技巧

4.1. 多环境配置

在实际项目中，通常需要为不同环境配置不同的Flyway行为：

spring:
  profiles: dev
  flyway:
    out-of-order: true  # 开发环境允许无序迁移
    
---
spring:
  profiles: prod
  flyway:
    out-of-order: false  # 生产环境严格按顺序迁移
    clean-disabled: true  # 生产环境禁用clean命令

4.2. 基线化已有数据库

如果项目中途引入Flyway，而数据库已有表结构，需要进行基线化：

spring:
  flyway:
    baseline-on-migrate: true
    baseline-version: 1  # 设置基线版本

或者手动执行基线命令：

Flyway flyway = Flyway.configure()
    .dataSource(dataSource)
    .baselineVersion("1")
    .load();
flyway.baseline();

4.3. 使用Java-based迁移

除了SQL脚本，Flyway还支持Java-based迁移：

public class V2__Add_user_status implements JdbcMigration {
    @Override
    public void migrate(Connection connection) throws Exception {
        try (Statement stmt = connection.createStatement()) {
            stmt.execute("ALTER TABLE user ADD COLUMN status VARCHAR(20) DEFAULT 'ACTIVE'");
        }
    }
}

4.4. 回调机制

Flyway提供了丰富的回调接口，可以在迁移的不同阶段执行自定义逻辑：

@Configuration
public class FlywayCallbackConfig {
    @Bean
    public FlywayCallback flywayCallback() {
        return new FlywayCallback() {
            @Override
            public boolean supports(Event event, Context context) {
                return event == Event.AFTER_EACH_MIGRATE;
            }

            @Override
            public boolean canHandleInTransaction(Event event, Context context) {
                return true;
            }

            @Override
            public void handle(Event event, Context context) {
                System.out.println("执行迁移后操作: " + event);
            }
        };
    }
}

五、常见问题与解决方案

5.1. 校验失败(checksum mismatch)

如果修改了已经应用的迁移脚本，Flyway会报校验失败错误。解决方案：

推荐：创建新的迁移脚本进行修改
临时方案：修复元数据表(仅限开发环境)

flyway.repair();

5.2. 版本冲突

确保团队中使用的版本号唯一且有序。如果出现冲突：

协调团队成员重新命名脚本文件
使用out-of-order配置(仅限开发环境)

5.3. 多数据源配置

对于多数据源项目，需要为每个数据源配置独立的Flyway实例：

@Configuration
public class MultiDataSourceFlywayConfig {
    
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }
    
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }
    
    @Bean(initMethod = "migrate")
    public Flyway primaryFlyway(@Qualifier("primaryDataSource") DataSource dataSource) {
        return Flyway.configure()
            .dataSource(dataSource)
            .locations("db/migration/primary")
            .load();
    }
    
    @Bean(initMethod = "migrate")
    public Flyway secondaryFlyway(@Qualifier("secondaryDataSource") DataSource dataSource) {
        return Flyway.configure()
            .dataSource(dataSource)
            .locations("db/migration/secondary")
            .load();
    }
}