Flyway 数据库版本迁移零基础完整学习文档

前言

在项目开发、测试、上线过程中，数据库SQL混乱、环境不一致、上线漏执行SQL、多人协作冲突是90%的项目都会遇到的致命问题。

Flyway 是一款开源、轻量、无侵入、自动化数据库版本控制工具，业界主流默认方案（SpringBoot 官方推荐）。

本文档专为零基础初学者编写，从零讲解原理、使用、集成、规范、避坑，可直接作为学习笔记、面试资料、企业开发手册使用。

一、Flyway 是什么？（通俗理解）

1.1 核心类比（秒懂）

Git / SVN ：管理代码版本
Flyway ：管理 数据库版本

Flyway 可以让数据库像代码一样：版本可控、可追溯、自动更新、多环境一致。

1.2 解决的行业痛点

没有 Flyway 时，开发常见灾难：

本地改了数据库结构，忘记发给测试、运维
测试库、生产库、本地库结构不一致
上线手动执行 SQL，漏执行、错执行、顺序错乱
多人开发，多人改表，SQL 冲突覆盖
出问题无法追溯：这条表结构是谁改的、什么时候改的
项目迭代几年，数据库脚本杂乱无法维护

Flyway 一次性解决所有问题。

1.3 Flyway 核心优势

零侵入、无需修改业务代码
自动执行、自动记录、自动版本管理
严格版本递增，杜绝SQL错乱
支持所有主流数据库（MySQL、PostgreSQL、Oracle、SQLServer）
完美集成 SpringBoot，开箱即用
开源免费版足够企业日常使用

二、Flyway 核心工作原理（初学者必懂）

2.1 核心机制

Flyway 的核心逻辑只有一句话：

按版本号从小到大，自动执行未执行过的SQL，并且永久记录执行历史。

2.2 自动生成版本记录表

Flyway 首次运行，会自动在当前数据库创建一张表：

flyway_schema_history

这张表是 Flyway 的核心，用来记录：

所有执行过的 SQL 版本号
脚本文件名、执行时间
执行耗时、执行状态（成功/失败）
执行备注、唯一校验码

后续项目启动时，Flyway 会对比：本地脚本版本 & 数据库历史版本，只执行新增脚本。

2.3 执行规则（硬性规则）

版本号必须 严格递增，不允许回退、不允许跳号乱序
已经执行过的脚本 禁止修改内容（修改会报错）
所有环境脚本统一，保证开发/测试/生产完全一致

三、Flyway 脚本命名规范（重中之重）

Flyway 靠文件名识别版本，命名错了直接报错，初学者90%的坑都在这里。

3.1 标准命名格式

复制代码

V版本号__描述.sql

规则拆解：

V：大写V开头（固定）
版本号：数字、小数点，递增（1、2、1.1、1.2）
两个下划线 __：分隔版本与描述（必须两个）
描述：英文/中文均可，见名知意
.sql：脚本后缀

3.2 正确示例

复制代码

V1__init_database.sql V2__create_user_table.sql V3__add_user_index.sql V4__update_user_field.sql

3.3 错误示例（绝对禁止）

复制代码

v1.sql // 小写V不行 V1_2.sql // 单下划线不行 V1__测试脚本.sql // 中文可，但不推荐乱命名 V3__xxx.sql // 跳版本不规范

3.4 两种脚本类型区别

类型	前缀	作用	使用场景
版本迁移脚本	V	正向执行，永久生效	建表、加字段、加索引、数据初始化
撤销回滚脚本	U	撤销对应V版本	企业付费版可用，开源版不支持

⚠️ 开源版 Flyway 不支持自动回滚，生产只能正向迭代（行业标准）

四、SpringBoot 完整集成教程（从零可跑）

4.1 环境要求

SpringBoot 2.x / 3.x 通用
MySQL / PostgreSQL 均可
项目已配置数据库连接

4.2 引入 Maven 依赖

pom.xml 新增依赖，无需额外配置，开箱即用：

复制代码

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

4.3 配置文件 application.yml 核心配置

最简通用配置（所有项目通用）：

复制代码

spring: # 数据库配置 datasource: url: jdbc:mysql://localhost:3306/test_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver # Flyway 配置 flyway: enabled: true # 开启Flyway locations: classpath:db/migration # 脚本存放路径 baseline-on-migrate: true # 旧项目兼容（关键配置） validate-on-migrate: true # 启动校验脚本完整性 clean-disabled: true # 禁止生产清空库 encoding: UTF-8

4.4 创建固定脚本目录

必须严格按照此路径创建，不能自定义（默认规范）：

复制代码

resources/ └── db/ └── migration/ V1__init.sql V2__create_table.sql V3__add_field.sql

4.5 编写测试SQL脚本

示例：V1__init_user_table.sql

复制代码

CREATE TABLE IF NOT EXISTS sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL COMMENT '用户名', password VARCHAR(100) NOT NULL COMMENT '密码', create_time DATETIME DEFAULT NOW() ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

4.6 启动项目自动执行

启动 SpringBoot 项目，控制台打印 Flyway 日志即代表成功：

复制代码

Flyway migrating schema version v1 Successfully applied 1 migration

数据库自动生成 flyway_schema_history 记录表 + 业务数据表。

五、Flyway 核心命令与功能详解

结合 SpringBoot，最常用 4 大核心功能

5.1 migrate（核心、最常用）

项目启动自动执行：执行所有未运行的新版本SQL

日常开发、上线 99% 只用这个功能

5.2 info（查看版本状态）

可通过日志或插件查看：

已执行版本、待执行版本
脚本是否缺失、是否被篡改

5.3 clean（清空数据库）

极度危险！！！

作用：删除当前库所有表、清空所有数据

✅ 仅用于本地开发测试

❌ 生产环境绝对禁止开启

配置 clean-disabled: true 禁止误操作

5.4 validate（校验脚本完整性）

校验本地脚本与数据库执行记录是否一致：

已执行脚本被修改 → 启动报错拦截
脚本缺失、损坏 → 启动拦截

保证数据库脚本不可篡改，保证环境一致性

六、新旧项目适配方案（重点）

6.1 新项目（无旧数据库）

直接从零开始：

V1 初始化全量表结构
后续迭代依次 V2、V3 递增

6.2 旧项目（已有数据库，最常用）

使用核心配置：baseline-on-migrate: true

作用：

自动把当前已有数据库结构标记为基线版本 V1
后续新增脚本从 V2 开始正常迭代
无需重构旧SQL，无缝接入Flyway

这是旧项目接入 Flyway 的核心关键配置

七、企业级开发规范（团队协作标准）

7.1 脚本编写规范

只增不改：已提交、已执行的SQL脚本，绝对禁止修改内容
所有变更（加表、加字段、改字段、加索引、初始化数据）必须新建版本
脚本必须包含注释、描述清晰
单脚本功能单一，不要堆积大量无关SQL

7.2 版本迭代规范

迭代版本严格递增：V1、V2、V3 禁止跳号、重复
多人开发各自新建新版本，禁止覆盖他人脚本
上线前统一校验版本完整性

7.3 生产环境红线规则

禁止开启 clean 功能
禁止手动修改 flyway_schema_history 表数据
禁止手动在生产执行临时SQL，所有变更必须走Flyway脚本
禁止修改已上线的历史脚本

八、初学者常见报错与解决方案

报错1：Validate failed: migration checksum mismatch

原因：已执行的脚本被修改了

解决方案：

开发环境：可清空历史表重新运行
生产环境：遵守规则，绝不修改旧脚本，新建新版本修正

报错2：Found non-empty schema without metadata table

原因：旧项目已有数据表，无Flyway记录

解决方案：开启 baseline-on-migrate: true

报错3：Duplicate migration version

原因：版本号重复

解决方案：修改文件名，保证版本号唯一递增

九、Flyway 优缺点总结（面试必背）

优点

实现数据库版本控制，解决多环境不一致问题
自动化上线，避免人工操作失误
脚本可追溯、可审计
轻量、无侵入、集成简单
规范团队SQL迭代，杜绝混乱

缺点

开源版不支持自动回滚，只能正向迭代
严格约束脚本规范，初学者需要适应
历史脚本禁止修改，需要养成规范习惯

十、初学者极简学习路线

理解 Flyway = 数据库 Git
熟记 V版本__描述.sql 命名规范
搭建 SpringBoot 基础集成环境
测试 V1、V2 迭代自动执行
掌握旧项目 baseline 适配
遵守企业开发规范，规避报错

十一、一句话终极总结

Flyway 让数据库不再是"手动随意改"，而是像代码一样"版本化、规范化、自动化、可追溯"，是现代后端项目数据库迭代的标配工具。

Flyway 数据库版本迁移 零基础完整学习文档

一、Flyway 是什么？（通俗理解）

1.1 核心类比（秒懂）

1.2 解决的行业痛点

1.3 Flyway 核心优势

二、Flyway 核心工作原理（初学者必懂）

2.1 核心机制

2.2 自动生成版本记录表

2.3 执行规则（硬性规则）

三、Flyway 脚本命名规范（重中之重）

3.1 标准命名格式

3.2 正确示例

3.3 错误示例（绝对禁止）

3.4 两种脚本类型区别

四、SpringBoot 完整集成教程（从零可跑）

4.1 环境要求

4.2 引入 Maven 依赖

4.3 配置文件 application.yml 核心配置

4.4 创建固定脚本目录

4.5 编写测试SQL脚本

4.6 启动项目自动执行

五、Flyway 核心命令与功能详解

5.1 migrate（核心、最常用）

5.2 info（查看版本状态）

5.3 clean（清空数据库）

5.4 validate（校验脚本完整性）

六、新旧项目适配方案（重点）

6.1 新项目（无旧数据库）

6.2 旧项目（已有数据库，最常用）

七、企业级开发规范（团队协作标准）

7.1 脚本编写规范

7.2 版本迭代规范

7.3 生产环境红线规则

八、初学者常见报错与解决方案

报错1：Validate failed: migration checksum mismatch

报错2：Found non-empty schema without metadata table

报错3：Duplicate migration version

九、Flyway 优缺点总结（面试必背）

优点

缺点

十、初学者极简学习路线

十一、一句话终极总结

Flyway 数据库版本迁移零基础完整学习文档