Spring Boot集成Flyway实战：数据库版本管理从入门到避坑-代码聚汇网

Spring Boot集成Flyway实战：数据库版本管理从入门到避坑

银星皓月·2026-09-04·阅读 68 GEO检测（免费）

Flyway数据库版本管理Spring Boot

|难度：普通|阅读约 41 分钟

程序员做久了，多多少少都遇到过这样的场景：本地改完表结构，一脸自信地推到测试环境，结果其他同事的应用没启动起来，报错一看，原来是有人提前在同一个字段上加了索引，而我的迁移脚本里刚好又建了一遍。更离谱的还有把数据库整个drop掉重来的狠人，开发库没数据倒是无所谓，生产一旦这样搞，哭都来不及。

后来我开始在Spring Boot项目里用Flyway做数据库版本管理，等于给数据库的表结构变更装了一个“git”。所有人改表结构，都通过写版本化脚本来完成，谁执行过、执行到哪一步、有没有人改过历史脚本，都有据可查。这篇文章就把我实际集成Flyway的过程、踩过的坑和做过的取舍一次性讲清楚，希望能帮你少走点弯路。

1. 先说清楚：项目里为什么需要Flyway

1.1 没有版本控制的“经典事故”

数据库表结构本质上也是代码的一部分。Java代码可以扔进Git仓库管理，可表结构变更却常常游离在版本控制之外。团队里经常出现的协作方式是：小明在本地给user表加了一个nickname字段，顺手在群里喊了一句“我加了字段，大家pull一下代码自己手动执行下SQL”。然后小红可能不知道，或者执行错了环境，又或者执行了两次直接报错。

更麻烦的是生产环境。发布新版本时，代码可以通过制品库部署到任何一台新机器，可数据库只有一个。如果一次改动包含了多个建表、加字段、改索引的操作，手工执行脚本的顺序稍有偏差，结果就完全不一样。而我见过最头疼的一种场景是：有人直接在测试库里面手工改表，等到上线前拿备份去对结构，发现测试环境跟生产环境不知道什么时候已经差了十几张表。

所以，数据库结构变更必须有版本记录，这跟代码用Git做版本管理一个道理。谁在什么版本加入了什么脚本、已经执行到哪一步、下一台新增环境要怎么做，应该有个集中的、可靠的管理机制来自动完成，而不是靠经验和微信群。

1.2 Flyway到底在做什么

Flyway的核心原理不复杂，说穿了就是一个独立的schema记录历史表。它默认会在一套数据库里建一张名为flyway_schema_history的表，里面记录每一次执行的迁移脚本版本号、描述、脚本名、checksum校验值、执行时间和是否成功等元数据。

进程启动时，Flyway会把项目里配置的迁移脚本目录下的SQL文件扫描一遍，再跟flyway_schema_history里已经记录过的脚本做比对。发现新的、没执行过的脚本，就按版本号顺序依次执行；每执行完一个脚本，在这张历史表里插入一条对应的记录。下次再启动，它发现这个版本已经存在，就会跳过。

这跟Liquibase的思路属于殊途同归，都是建一张表做记录，但Flyway的“约定大于配置”风格，上手门槛低很多，基本就是起个脚本文件名、扔进约定目录，然后什么都不用管。

1.3 这套方案适合什么团队、什么项目

不是说所有项目都必须上Flyway。一个纯个人单机小项目、或者SQLite那种单文件数据库，自己心里有数也就行了。但只要是下面这些情况中的任何一种，我都建议引入：

项目由多人协作开发，大家都会改表结构；
存在开发、测试、生产等多套环境，需要保证表结构一致；
项目需要一键初始化新环境，比如新同事的本地库、新的测试环境；
上线策略要求数据库变更跟应用发布一起走，不能落下任何一环。

我个人觉得，从项目第一天就引入Flyway，成本是最低的。如果已经是“历史包袱”比较重的存量项目也有补救办法，后面会专门讲baseline。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 集成前的方案设计：Flyway还是Liquibase

2.1 主流的几个数据库迁移工具对比

做Java生态数据库版本管理，主流选择基本是Flyway和Liquibase，另外还有少量团队会自己基于Spring的ApplicationRunner写一套简易执行器。

简单对比一下：

对比维度	Flyway	Liquibase
使用门槛	低，SQL脚本为主	较高，需要学习XML/YAML/JSON格式
脚本形式	可直接写数据库原生SQL	推荐用数据库无关的changelog格式
团队熟悉程度	对常规Java后端团队更友好	DBA或已有规范团队更友好
迁移回滚能力	社区版不支持undo，靠手工编写down脚本	社区版同样不支持rollback
Spring Boot生态	官方有独立starter，集成非常顺滑	也有starter，但配置和依赖相对多一点

我自己两个都试过。Liquibase的changlog抽象层确实强大，尤其适合需要同时兼容多种数据库的产品化项目，可如果你的项目确定就是PostgreSQL/MySQL其中一种，Flyway那种直接写原生SQL的路子反而没那么绕。维护起来也简单——一个普通的后端开发就能看懂一个V2__add_column.sql是加字段的意思。

2.2 为什么最终选了Flyway

当初在项目里选型时，我偏向Flyway的原因其实很朴素。第一个是迁移脚本直接用SQL，没有中间那层抽象。DBA评审SQL时直接看到真实的数据库语法，不会出现代码里的<addColumn>实际生成出来的SQL跟预期不一致的隐性风险。

第二个是跟Spring Boot的整合体验。Flyway官方提供了flyway-core和flyway-mysql或是flyway-database-postgresql这类数据库模块。Spring Boot的自动装配基本上做到了引入依赖、配个数据源地址、把script放到约定目录，启动即执行的程度。甚至大多数时候连配置项都不用写多少。

第三个是它足够轻。Flyway不像一些重框架需要维护独立的服务端，它就是一个打包进应用里的库，Spring Boot应用启动时自动执行迁移逻辑，非常适合当前微服务架构下每个服务管好自己库的模式。

2.3 先想清楚迁移策略再动手

Flyway脚本分两大类：

版本化迁移（Versioned Migration），文件名形如V1__init.sql、V2__add_column.sql，同一版本只会执行一次；
可重复迁移（Repeatable Migration），文件名形如R__view_user_order.sql，每次内容checksum变化都会重新执行。

日常表结构的增减字段、新建表，都应该用版本化迁移。视图、存储过程、函数这类对象，因为没有“变更历史”概念，每次都像是覆盖写，所以更适合用可重复迁移。

我个人还有个习惯：版本号线上尽量规范一点。不要用V20240101__xxx.sql这种纯日期作为版本号，不同人同一天加脚本会导致版本冲突。建议用递增数字，比如V1__、V2__、V3__，或者带用户标识的V1.1__、V1.2__。关键是同一个版本号全局唯一，且新脚本的版本号顺序必须一致地递增。

3. Spring Boot + Flyway 落地实操

3.1 准备一个干净的Spring Boot项目

本文示例采用Spring Boot 3.2.x配合Java 17。如果你还在用Spring Boot 2.x，集成思路完全一致，只是Flyway需要选择对应的较老版本，比如Spring Boot 2.7对应Flyway 8.x/9.x。

先建一个普通Spring Boot项目，只添加下面几个起步依赖：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

JDBC驱动这个scope设为runtime就够了，没有它编译期也不会报错，但运行时少了它肯定驱动不了连接。

如果项目用Gradle管理依赖，对应的build.gradle部分可以写成这样：

groovy复制dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-jdbc'
    runtimeOnly 'com.mysql:mysql-connector-j'
}

3.2 引入Flyway依赖与基础配置

Spring Boot官方starter做得非常贴心，我们只需要引入下面两个依赖即可：

xml复制<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>
</dependency>

Gradle对应的是：

groovy复制implementation 'org.flywaydb:flyway-core'
implementation 'org.flywaydb:flyway-mysql'

为什么要单独引入flyway-mysql？因为Flyway从8.0开始，把各类数据库支持模块拆分出去了。如果数据库是PostgreSQL，就引入flyway-database-postgresql；Oracle对应flyway-database-oracle。不清数据库的话启动时会直接报找不到对应DatabaseType支持的错。

接着在application.yml里配上数据源和Flyway的基本信息：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo
    username: root
    password: root
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    validate-on-migrate: true
  jpa:
    hibernate:
      ddl-auto: validate

这里先简单解释一下关键参数：

locations：迁移脚本所在目录，默认就是classpath:db/migration，不需要改；
baseline-on-migrate：存量数据库首次启动时是否自动基线化，生产库第一次接Flyway时非常关键；
validate-on-migrate：启动时是否校验已执行脚本是否有变更，强烈建议保持默认的true。

3.3 迁移脚本的目录约定与命名规范

默认目录约定是classpath:db/migration。在标准Maven工程里，脚本放在src/main/resources/db/migration目录下。

文件名格式是固定的三段式：

V版本号__描述.sql

注意中间是两个下划线，不是横杠。比如：

code复制src/main/resources/db/migration/
├── V1__create_user_table.sql
├── V2__add_user_age_column.sql
├── V3__create_order_table.sql
└── R__user_order_info_view.sql

虽然Flyway官方默认校验了命名格式，但很多人第一次上手还是会在这里翻车。比如写成了V1_create_user_table.sql（只有一个下划线），Flyway扫描时会直接忽略这个文件，不报错、不提醒，后来发现脚本没执行时排查了半天。

版本号的排序逻辑也值得说一句：Flyway不是按文件名字符串排序，而是对每个由点号分隔的数字部分做数值比较。举个例子，V10__xx.sql会排在V9__xx.sql后面，而不是按字符串长度简单排。这个设计对版本号超过10的情况非常友好。

3.4 编写并执行第一个迁移脚本

先写第一个脚本，建一张用户表：

sql复制-- V1__create_user_table.sql
CREATE TABLE t_user (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
    username VARCHAR(50) NOT NULL COMMENT '用户名',
    password VARCHAR(100) NOT NULL COMMENT '密码',
    email VARCHAR(100) COMMENT '邮箱',
    status TINYINT DEFAULT 1 COMMENT '状态: 1-启用 0-禁用',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

直接启动应用，控制台会看到类似这样的日志：

code复制INFO  [main] o.f.c.i.database.base.DatabaseTypeSupport: Unable to determine database type for ...
INFO  [main] o.f.core.internal.command.DbMigrate: Current version of schema `demo`: null
INFO  [main] o.f.core.internal.command.DbMigrate: Migrating schema `demo` to version "1 - create user table"
INFO  [main] o.f.core.internal.command.DbMigrate: Successfully applied 1 migration to schema `demo` (execution time 00:00.045s)

然后去看数据库，除了你自己的t_user表，还会多出一张flyway_schema_history表。它里面记录了刚刚这次迁移的操作。

sql复制-- 查看迁移记录
SELECT installed_rank, version, description, script, checksum, success
FROM flyway_schema_history
ORDER BY installed_rank;

执行结果大致是：

installed_rank	version	description	script	success
1	1	create user table	V1__create_user_table.sql	1

这里注意version字段是字符串，Flyway会在启动时把它跟脚本里的魔法版本号做匹配。如果发现历史表里已有版本1，但扫描目录里没有对应的V1__脚本，会直接报FlywayValidateException。反过来，如果目录里有新版本的未执行脚本，就会自动执行。

我再举个例子说明增量迁移。第二天我需要给用户表加昵称字段，于是新增文件：

sql复制-- V2__add_nickname_to_user.sql
ALTER TABLE t_user ADD COLUMN nickname VARCHAR(50) DEFAULT NULL COMMENT '昵称';

重启应用，Flyway检测到V2__这个脚本在历史表里不存在，就会自动按顺序执行它，不用任何人手工操作。

3.5 已有表结构的存量项目：baseline处理

上面这套流程适合“绿田”项目。但很多实际开发场景是：项目跑了几个月甚至几年，数据库里已经有了一大堆表，这时候才想起引入Flyway。

这时候千万不能直接把已有库拖进Flyway管理就完事。最稳妥的方式是用baseline（基线化）功能。它的含义是：把当前数据库状态定义为一个基线版本，从该版本之后的脚本才由Flyway管理，之前的脚本全部视为已执行，不再重复执行。

操作分两步：

第一步，手动复制一份现有生产/测试库的schema，在目标环境跑通你的初始化SQL，把结构还原出来，整理成基线脚本。比如把全量建表SQL整理为V1__baseline_schema.sql。

第二步，在application.yml里先配置baseline-on-migrate: false（或者干脆用默认），然后设置：

yaml复制spring:
  flyway:
    baseline-on-migrate: false
    baseline-version: 1

但这里面有个细节值得注意。如果你的存量数据库已经有一堆表，又不想把它们的历史全部反向整理成一个巨大的基线脚本，可以不用这招，换另一种思路：

先在项目里新增一个空迁移脚本，比如V1__do_nothing.sql，内容不写任何SQL，只留一行注释；
启动时开启baseline-on-migrate: true，Flyway会自动创建一个版本为1的基线记录，但不会执行任何SQL；
之后新增的真实变更从V2__xxx.sql开始写。

这种方式适合已有数据库表结构无需变动，只想管住后续变更的情况。需要明确的是：Flyway默认baseline的版本是1，如果项目里已有V1__脚本，那么baseline-version应该设置为大于已有脚本编号，比如2。具体设置方式是：

yaml复制spring:
  flyway:
    baseline-on-migrate: true
    baseline-version: 2

这样Flyway在历史表里记录一条“基线版本=2”，从版本3开始才作为真正的增量脚本执行。

4. 几个容易踩坑的场景与原因分析

4.1 checksum校验失败：一个标点符号都可能让环境崩溃

Flyway的历史表里记录着每个脚本的checksum值，它是脚本内容的校验和。默认情况下Spring Boot开启了validate-on-migrate，意味着每次启动都会扫描目录下的脚本，然后计算checksum，跟历史表里的旧值对比。

只要有人改动了已执行过的脚本内容，哪怕只是在SQL里加了个空格或者注释，checksum都会变化，启动时就会报错：

code复制Migration checksum mismatch for migration version 2

这个机制本质上是在保护你：防止线上环境的数据库迁移历史跟开发环境不一致。但确实也给很多人带来过困扰。如果项目规范允许，可以执行下面这条命令来“接受当前脚本并更新历史记录”：

bash复制mvn flyway:repair

不过在Spring Boot应用中更常见的做法是把历史表里对应版本的checksum字段手动更新为null，让下次启动时自动重新记录。但必须说明，这不是银弹。如果脚本已经被各个环境执行过，修改历史脚本本身就是一种禁忌，会造成环境间迁移历史混乱。

修复建议：如果只是改了注释导致checksum变了，又确实不想影响线上，直接更新flyway_schema_history表里对应行的checksum为null，再重启。如果是真正改了表结构逻辑，麻烦老老实实新增一个新版本的迁移脚本，做增量变更或补偿操作。

4.2 错误地清理flyway_schema_history表引发雪崩

有人为了图省事，直接执行：

sql复制DELETE FROM flyway_schema_history;

这样做的结果是灾难性的。下次应用启动时，Flyway发现历史表为空，认为自己从来没有执行过任何迁移，于是把所有V1__到Vn__的脚本全部重新执行一遍。如果你的所有迁移脚本都是幂等的，可能还能侥幸跑通；万一有DROP TABLE或者ALTER TABLE ADD COLUMN这种非幂等操作，就直接把原有表结构弄坏了。

删除历史表、清理历史数据、手工改表，都属于“绕过Flyway”的高危操作。真需要重置环境的话，正确做法是连数据库schema一并删除重建，然后让Flyway从零开始执行所有脚本。但也一定要确认目标环境没有无法重建的业务数据。

4.3 与JPA/Hibernate的ddl-auto同时使用

Spring Boot项目里很多人会同时用Spring Data JPA。Hibernate有个特性是通过spring.jpa.hibernate.ddl-auto配置自动更新表结构。常见设置包括update、create、create-drop、validate。

如果同时开启Flyway和JPA的ddl-auto: update，就会产生双写冲突：Flyway管一套，Hibernate又按实体类推导另一套表结构，两边都尝试改表。轻则日志一堆告警，重则两边建的表字段类型不一致，或者Flyway执行完后Hibernate又自动把字段长度按照实体定义改回去了，结果两个团队的“结构标准”乱了套。

我的建议是： 只要用了Flyway，就把ddl-auto固定为validate，甚至是none，让数据库结构完全由Flyway掌控。Hibernate只在启动时校验表跟实体是否对得上，对不上就报错提示，这样至少能把问题暴露在开发阶段。

4.4 多数据源场景下Flyway如何绑定各自库

微服务架构经常遇到一个服务需要连两个或多个数据源的情况。Spring Boot自动装配默认只会给主数据源配置Flyway。如果你有多个数据源，就需要手动为每个数据源创建独立的Flyway配置。

其中一个可行方案是为每个数据源单独定义一个FlywayMigrationStrategy。下面用@Configuration做一个示意：

java复制@Configuration
public class MultipleFlywayConfig {

    @Bean
    public FlywayMigrationInitializer flywayForUserDataSource(
            @Qualifier("userDataSource") DataSource userDataSource) {
        Flyway flyway = Flyway.configure()
                .dataSource(userDataSource)
                .locations("classpath:db/migration/user")
                .load();
        flyway.migrate();
        return new FlywayMigrationInitializer(flyway, null);
    }

    @Bean
    public FlywayMigrationInitializer flywayForOrderDataSource(
            @Qualifier("orderDataSource") DataSource orderDataSource) {
        Flyway flyway = Flyway.configure()
                .dataSource(orderDataSource)
                .locations("classpath:db/migration/order")
                .load();
        flyway.migrate();
        return new FlywayMigrationInitializer(flyway, null);
    }
}

这里使用Flyway.configure()是Flyway官方提供的一种编程式配置方式。如果你设置了多个FlywayMigrationInitializer，要注意两个Bean之间的执行顺序问题：

不同数据源的迁移脚本应该放在不同目录下，避免扫描冲突；
如果有依赖关系，比如订单表外键引用用户表，需要确保用户数据源的迁移先执行。

Flyway提供的原生API编程式配置远不止上述一种，也可以用FluentConfiguration.ruby()。如果项目不需要这种精细控制，最省力的做法其实是：给每个数据源单独配一个Spring Boot的spring.flyway子配置，配不同location和baseline。只是后者配置起来更啰嗦一些。

4.5 迁移脚本里的事务与隐式提交

MySQL里有个天坑：DDL语句会自动隐式提交。比如你写了一个迁移脚本，里面有三条DDL，想把它们放进一个事务里，失败就回滚。但在MySQL的InnoDB下，CREATE TABLE、ALTER TABLE这类语句会隐式提交当前事务，意味着并不能像InnoDB行级DML那样有完整回滚能力。

所以如果迁移脚本中间某一步因为字段冲突失败了，Flyway不会把整个脚本回滚，只会把历史表里对应的执行记录标记为失败，后续修复时需要你手动清理失败残留。PostgreSQL的处理方式稍好一些，它能更好地支持事务性DDL，但也不要完全依赖。

这个特性平时很少有人提，但坑是真的。我的经验是：尽量让一个版本化迁移脚本里只做一件逻辑独立的事。如果要同时对一个表做加字段和加索引，其实无所谓；但如果你在一个脚本里建了表、又插入基础数据、又改存储过程，出了错定位和回滚都会极其痛苦。

5. 生产环境发布时的实践心得

5.1 大型发布时如何协调多个迁移脚本

如果你的版本发版比较频繁，分支横跨时间长，提交的脚本顺序可能乱。Flyway是按版本号排序的，跟Git提交时间没有关系。如果A分支加了V3，B分支也加了V3，合并时就会出现两个相同版本号的冲突，Flyway会拒绝执行后加的那个。

这种情况最稳的处理方式是：合并到主干后，立即检查db/migration目录下有没有重复版本号的脚本，有则把其中一个改成更高版本号。一定要改文件名和SQL里的版本号，然后再动历史表，否则可能导致线上执行到一半时发现版本号冲突而失败。

5.2 千万小心破坏性变更

Flyway本身不限制你在脚本里写DROP COLUMN或DROP TABLE，所以破坏性变更需要开发者和DBA自己把关。

一个比较稳妥的上线策略是：先删除依赖该字段的代码，发布一小段时间后再提交DROP COLUMN的迁移脚本。这样即便有旧版本实例没完全下线，也不会因为字段丢失而直接报错。

这里要特别提醒的是，如果你有定时任务或者消息消费者还在运行，即使应用代码已经更新，RabbitMQ/MQ里可能还有老消息没消费完，消息里带着旧字段的JSON结构，一旦数据库列被真正删除，反序列化时可能直接抛异常。

5.3 生产环境要不要开启`spring.flyway.enabled`

默认情况下Spring Boot集成Flyway后是自动开启的，也就是说应用启动时就会执行迁移。这在开发环境和测试环境没什么问题，因为数据丢了也不心疼。

但生产环境，很多团队会担心应用启动瞬间执行迁移失败了怎么办。有两种常见策略：

策略一：保持自动执行，应用启动失败就失败，发布系统自然会把这次发布标记为失败，人工介入处理即可；
策略二：把spring.flyway.enabled设为false，然后在发布流水线里用Maven插件或独立任务先执行flyway:migrate，成功后再启动应用。

实操中我推荐策略一，因为它更符合“代码和数据库脚本一起部署”的理念。但如果你的DBA管得严、数据库变更需要走独立审批流，那策略二更适合。改成false之后，应用启动前必须确保SQL已经由其他途径导入，否则业务跑到一半发现表结构不对劲，比启动失败更难排查。

5.4 多个环境和梯次发布的版本对齐

Dev、Test、Staging、Production几套环境，迁移脚本执行进度不一定要完全一致，但最低要求是“所有环境的迁移历史记录最终趋同”。

比如生产上某些迁移脚本只在特殊数据修复场景下编写，其他环境甚至不需要执行。我建议把通用表结构变更和一次性数据修复脚本分开，或者用不同的前缀规范标记。比如通用结构用V，一次性数据修复放到独立的src/main/resources/db/fix目录，由运维手工触发脚本执行，这样Flyway的历史表就不会因为数据修复的不确定性而出现跨环境不一致。

6. 一些有价值的补充建议

Flyway还有一个比较有用的特性，是支持占位符替换。比如在某条SQL里写${tablePrefix}，然后在配置里指定：

yaml复制spring:
  flyway:
    placeholders:
      tablePrefix: t_

这个功能适合一套代码部署给多个租户/分公司，每个库的表前缀还不同的场景。但过度使用会降低SQL的可读性，个人建议仅在确实需要做环境差异化时再用。

另外一个容易被忽略的点是定期归档flyway_schema_history表。别笑，如果项目跑了五年，“版本号”都到几百了，这张表越来越多行，虽然不会影响性能，但查询时经常看到几百条记录也烦。好在Flyway对历史表只做插入和更新，不做删除，属于只增表，这个表通常也不会太大。如果哪天你真的出现“版本号达到9999”这种极端情况，Flyway还支持使用字母后缀版本号进行扩容，所以不用担心。

说了这么多，我在实际集成Flyway后的最大感受是：以前最怕的“生产环境表结构不一样”的情况基本绝迹了。新同事入职拉代码，本地启动一条命令全自动把表结构建好，再也不用翻群里一个接一个的SQL文件。如果你正在被手工维护表结构的流程折磨，花一个下午把Flyway集成进Spring Boot流程里，是绝对值得的。