Flyway：Flyway 知识点全景深度梳理 / 开源数据库版本迁移管理工具

术语

详细释义

作用

迁移脚本 (Migration Script)

存放在项目resources/db/migration目录下的 SQL 文件，是数据库变更最小单元

记录每一次建表、加字段、改索引、初始化数据操作

版本表flyway_schema_history

Flyway 自动在目标库创建的系统记录表

1. 记录所有已执行脚本版本、执行时间、执行状态、哈希校验值 2. 启动时对比脚本与历史记录，判断是否需要执行迁移

基线 (Baseline)

项目接入 Flyway 前，数据库已存在存量表结构，初始化历史版本记录的操作

存量老项目无缝接入 Flyway，不用重新初始化库

迁移 (Migrate)

核心动作：启动项目自动扫描未执行脚本，按版本顺序依次执行 SQL

所有环境统一表结构的核心能力

校验 (Validate)

启动时校验本地脚本文件哈希值和历史执行记录哈希是否一致

防止已上线脚本被私自修改，规避环境错乱

清理 (Clean)

清空库内所有表、视图、存储过程（生产环境严禁使用）

仅本地调试重置数据库使用

修复 (Repair)

修复版本表异常记录、哈希不一致、迁移失败中断残留数据

解决迁移中途报错导致的版本状态错乱

脚本前缀标识

脚本类型

执行时机

适用场景

命名示例

V

版本迁移脚本（Versioned）

仅执行 1 次，执行完毕永久锁定，不会重复执行

建表、新增字段、修改字段、创建索引、基础字典初始化数据

V1__init_base_table.sql V2__add_staff_column.sql

U

撤销回滚脚本（Undo）

版本脚本执行成功后，执行 U 脚本可撤销对应 V 脚本变更

社区免费版不推荐、功能残缺，仅商业 Pro 版完整支持

U2__undo_add_staff_column.sql

R

可重复执行脚本（Repeatable）

每次项目启动都会执行（文件修改即触发执行）

视图、存储过程、函数、定时任务 SQL、动态配置字典数据

R__view_staff_role.sql R__init_menu_data.sql

B

基线脚本（Baseline）

存量老项目初始化基线使用

已有大量数据表的老系统接入 Flyway

B1__baseline_exist_tables.sql

配置 Key

默认值

取值说明

适用场景

spring.flyway.enabled

true

true：开启迁移；false：关闭

本地临时调试可关闭，线上必须开启

spring.flyway.locations

classpath:db/migration

脚本扫描路径，多路径逗号分隔

拆分模块脚本、公共脚本存放

spring.flyway.baseline-on-migrate

false

true：无版本表时自动创建基线

存量老项目接入必备配置

spring.flyway.validate-on-migrate

true

启动校验脚本哈希一致性

线上必须开启，防止脚本篡改

spring.flyway.clean-disabled

false

true：禁用 clean 清空库能力

生产环境强制开启，杜绝误删库

spring.flyway.table

flyway_schema_history

修改版本记录表名

多数据源、分库场景自定义

spring.flyway.encoding

UTF-8

SQL 文件编码

统一中文不乱码

spring.flyway.out-of-order

false

true：允许执行更高版本脚本，跳过缺失低版本

紧急线上补丁临时开启，日常关闭

spring.flyway.placeholders

–

占位符变量替换

多环境库名、前缀差异化配置

步骤序号

执行动作

内部逻辑

1

数据源加载

读取 spring.datasource 配置，建立 MySQL 连接

2

校验库内是否存在flyway_schema_history版本表

不存在：触发 baseline 基线初始化；存在：读取所有历史执行记录

3

扫描项目路径下所有 SQL 脚本

区分 V/U/R/B 四类脚本，按版本号排序

4

Validate 哈希校验

对比本地脚本哈希值 和 版本表存储哈希：不一致直接启动报错

5

Migrate 迁移执行

筛选版本号大于历史最大版本的 V 脚本，按顺序逐条执行；执行成功写入版本表

6

执行所有 R 可重复脚本

每次启动均执行，更新视图、存储过程

7

SpringBoot 项目正常启动完成

接口可正常访问数据库表

对比维度

Flyway

Liquibase

核心设计思想

约定优于配置，纯 SQL 编写，学习成本极低

基于 XML/YAML/JSON 结构化定义，跨数据库兼容极强

脚本编写形式

原生 SQL，贴合 DBA 日常习惯

自定义标签语法，可自动生成多数据库适配 SQL

回滚能力

免费版无完整回滚，依赖备份 + 正向补丁

原生支持任意版本一键回滚

执行速度

轻量小巧，启动速度快

功能繁多，启动开销略大

国内企业使用率

绝大多数 Java 后端项目首选

外企、多数据库适配项目使用居多

学习门槛

极低，开发 1 小时即可上手

偏高，需要记忆专属标签语法

复杂场景适配

简单迭代、MySQL 单库最优

分库分表、Oracle/PostgreSQL 多数据库异构场景

✅ 选型结论：仅使用 MySQL、中小团队日常迭代 → 优先 Flyway

Maven 命令

功能

使用场景

mvn flyway:migrate

手动执行迁移脚本

打包前本地验证 SQL 执行效果

mvn flyway:validate

单独执行哈希校验

排查脚本篡改、版本不一致问题

mvn flyway:clean

清空数据库所有表

本地调试重置库，线上禁止执行

mvn flyway:baseline

手动初始化基线版本

老项目初次接入初始化

mvn flyway:repair

修复版本表异常记录

迁移中途报错、执行失败后修复状态

mvn flyway:info

查看所有脚本执行状态

排查哪些脚本未执行、执行失败

开发场景

标准操作流程

禁忌操作

新建角色表、菜单表

新建V1__create_sys_role_menu.sql编写建表语句，启动项目自动建表

Navicat 手动在 dev 库建表，不写入项目脚本

角色表新增排序字段

新建V2__add_sort_column_to_role.sql，ALTER TABLE 语句新增字段

修改 V1 脚本内原有 SQL 内容

创建角色分页查询视图

新建R__view_role_page.sql编写 VIEW 视图

写在 V 脚本中，导致视图无法迭代更新

给角色初始化 3 条基础测试数据

写入 V 版本脚本一次性初始化；正式字典数据放 R 脚本

每次启动重复 INSERT 插入测试数据

存量老项目接入 Flyway

开启baseline-on-migrate=true，启动自动生成基线

手动创建 flyway_schema_history 表填写记录

报错信息

根因

解决方案

Validate failed: checksum mismatch

已上线执行过的 V 脚本被本地修改，哈希值不一致

1. 本地未提交：恢复脚本原始内容 2. 已上线：执行mvn flyway:repair修复哈希

Found non-empty schema without metadata table

库内已有数据表，无 Flyway 版本表

开启baseline-on-migrate: true自动基线

Migration failed: SQL error in script

SQL 语法错误、字段冲突、主键重复

查看控制台 SQL 异常日志，修正脚本后 repair 重试

Unknown column xxx

脚本执行顺序错乱，前置表未创建

严格保证版本号递增，禁止随意调整脚本顺序

connect refused 数据库连接失败

数据源地址、账号密码错误，VPN 未连通

核对 application.yml 数据库配置，连通内网 VPN

环节

执行规范

安全约束

上线发布

1. 脚本提交 Git dev 分支 2. Jenkins 流水线打包部署 3. 服务启动自动执行 migrate 4. 查看启动日志确认全部脚本执行成功

上线前必须本地完整验证 SQL 执行效果

线上结构变更

所有 DDL 语句（建表、加字段、改索引）均新增高版本 V 脚本

禁止 DBA 直连生产库手动执行 ALTER 语句

线上回滚方案（免费版无 undo）

方案 1：正向新增 V 回滚脚本（推荐） 方案 2：上线前全量备份数据库，异常时回档备份

不依赖 Undo 脚本做线上回滚

大表字段新增

拆分小批次脚本，避开业务高峰期执行

上亿条大表禁止高峰执行 DDL，锁表阻塞业务

权限管控

生产账号仅拥有 DML 读写权限，DDL 变更全权交由 Flyway 执行

DBA 日常不持有生产库超级管理员权限