Flyway 数据库迁移工具详解

1. 概述

Flyway 是一款把数据库 Schema 变更（Migration，迁移脚本）纳入版本控制的工具，由 Axel Fontaine 于 2010 年创建，现归 Redgate 公司所有。它将"数据库像代码一样管理"——迁移脚本用 SQL 编写、放进版本控制、按版本顺序执行，让开发、测试、生产各环境的数据库始终保持一致且可追溯，是 Database DevOps（数据库 DevOps）领域事实上的标准工具。

1.1 Flyway 支持什么

1.2 专有名词解释

2. 核心概念

2.1 迁移类型

Flyway 的迁移分为三种：版本化迁移（Versioned）、可重复迁移（Repeatable）、基线迁移（Baseline）。其中版本化迁移又分为普通迁移和撤销迁移（Undo）。

执行顺序规则：在单次 migrate 运行中，先按版本顺序执行所有待执行的版本化迁移，再按描述（description，字母序）执行所有已变更的可重复迁移。

2.2 命名规范

迁移脚本的文件名由四部分构成，可被配置项调整：

[prefix][version]__[description].[suffix]
 ────────┬───────  ────┬───────   ─────┬─────
         前缀 V/R/U      分隔符 __       后缀 .sql

V1__create_user_table.sql      ← 版本化迁移，版本 1
V2.1__add_age_column.sql       ← 版本支持点号/下划线，如 V2_1 等价
R__all_views.sql               ← 可重复迁移，无版本号
U1__create_user_table.sql      ← 撤销迁移，对应 V1

版本号必须唯一，且按数值排序执行（V1 < V2 < V2.1 < V10）。描述仅用于可读性。用零填充（如 V001）或时间戳可减少多人协作时的冲突。

2.3 Schema 历史表（flyway_schema_history）

Flyway 只创建一张表——就是这张历史表。数据库里的其他表（users、orders 等应用表）都是迁移脚本执行后产生的，不是 Flyway 创建的。

数据库中各类对象及关系：

三者关系（一对多、无外键）：

• 历史表（1 张）↔ 迁移脚本（N 个）：一对多——一张历史表记录所有已应用脚本，每行对应一个已应用的迁移（版本化 V / 可重复 R / 基线 B）
• 迁移脚本（N 个）→ 应用表（M 张）：每个脚本可创建 / 修改多张应用表
• 历史表与应用表之间没有外键约束：历史表是独立的审计表，删除应用表不影响历史表，反之亦然；历史表只能由 Flyway 通过 migrate / repair / baseline 等命令写入

首次 migrate 时，Flyway 会在默认 Schema 中自动创建历史表，作为所有数据库变更的完整审计轨迹。表名可用 table 配置项修改。

通过 flyway info 命令可以查看每条迁移在目标库上的状态（Migration States）：

2.4 占位符（Placeholders）

所有迁移脚本都支持占位符替换，默认使用 Ant 风格 ${myplaceholder}。常用于抽象环境差异（如表名、所有者、时区等）。

-- V1__create_user_table.sql
CREATE TABLE ${table_prefix}users (
    id BIGINT PRIMARY KEY,
    name VARCHAR(255) NOT NULL
);

-- 配置占位符
flyway.placeholders.table_prefix=app_
flyway.placeholders.table_prefix=app_

内置占位符 ${flyway:timestamp} 每次执行都会改变，把它放在可重复迁移顶部，可以让该迁移每次都强制执行（常用于强制刷新物化视图等场景）。

2.5 回调（Callbacks）

把脚本命名为回调事件名并放入回调目录，即可在迁移生命周期的特定时点自动执行。常用于：重编译存储过程、刷新物化视图、VACUUM 等数据库维护。

2.6 配置方式

Flyway 支持多种配置来源，优先级从高到低：命令行参数 > Java API 编程配置 > 环境变量 > 配置文件（flyway.conf 或 application.yml）。

# flyway.conf 示例
flyway.url=jdbc:postgresql://localhost:5432/demo
flyway.user=postgres
flyway.password=secret
flyway.locations=filesystem:./sql
flyway.baselineOnMigrate=true
flyway.placeholders.env=dev

3. 行为图（系统"做什么"）

3.1 用例图 — Flyway 用户交互全景

图 1：Flyway 用例图

3.2 活动图 — migrate 主流程

migrate 是 Flyway 的核心命令：扫描迁移脚本 → 对比数据库已应用记录 → 补齐差距。它是幂等的，无论数据库当前处于哪个版本都可安全执行。

图 2：migrate 主流程活动图

3.3 时序图 — migrate 全过程

一次 flyway migrate 中，Flyway 引擎、迁移脚本与目标数据库之间的交互细节：

图 3：migrate 时序图

3.4 状态机图 — 迁移状态流转

每条迁移在 flyway_schema_history 中会处于不同状态，随着 migrate / repair / baseline 等操作不断流转：

图 4：迁移状态机图

4. 结构图（系统"由什么组成"）

4.1 部署图 — 多种接入方式

Flyway 是一个库 + 多种前端的工具：CLI、Java API、构建工具插件、Spring Boot 自动装配、Docker 容器等全部复用同一核心引擎，通过各自配置的 JDBC 驱动连接目标数据库。

图 5：Flyway 部署图

4.2 组件图 — 核心架构

Flyway 核心引擎内部由"配置 → 扫描发现 → 解析 → 执行 → 历史记录"的责任链组成，各组件职责单一、通过接口协作：

图 6：Flyway 核心组件图

4.3 包图 — 代码结构

Flyway 源码（Java）的主要包划分：org.flywaydb 根包下按职责分包，核心引擎与各前端分离：

图 7：Flyway 包图

4.4 类图 — 核心对象模型

核心门面 Flyway 类聚合配置与各能力接口，对外提供 migrate / info / validate 等命令入口：

图 8：Flyway 核心类图

5. 实战演示操作手册

5.1 用 CLI 从零搭建一个项目

以 macOS 上操作 PostgreSQL 为例，完整走一遍"建目录 → 写迁移 → migrate → 改脚本 → 再迁移"的闭环。

步骤 1：下载并安装 Flyway CLI

# 从 https://www.red-gate.com/products/flyway/ 下载最新版（Community 免费）
# 解压后加入 PATH
export PATH="$HOME/flyway-10.x/flyway:$PATH"
flyway -v

步骤 2：创建项目结构与首个迁移

mkdir -p demo-flyway/sql
cd demo-flyway
cat > sql/V1__create_user_table.sql <<'EOF'
CREATE TABLE users (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE,
    created_at TIMESTAMP DEFAULT NOW()
);
EOF

步骤 3：配置并执行 migrate

cat > flyway.conf <<'EOF'
flyway.url=jdbc:postgresql://localhost:5432/demo
flyway.user=postgres
flyway.password=secret
flyway.locations=filesystem:./sql
EOF

flyway migrate
# 输出: Successfully applied 1 migration to schema "public" (execution time 00:00.123s)

此时数据库中已自动创建 public.flyway_schema_history 表。查看状态：

flyway info
# ┌──────┬─────────┬─────────────────┬─────┬────────────────────────┬────────┐
# │State │ Version │ Description     │Type │ Script                 │ ...    │
# ├──────┼─────────┼─────────────────┼─────┼────────────────────────┼────────┤
# │ ✔    │ 1       │ create_user...  │ SQL │ V1__create_user_table.sql│ ...   │
# └──────┴─────────┴─────────────────┴─────┴────────────────────────┴────────┘

步骤 4：追加新迁移（推进 schema）

cat > sql/V2__add_profile_column.sql <<'EOF'
ALTER TABLE users ADD COLUMN profile VARCHAR(2000);
EOF

flyway migrate   # 只应用 V2
flyway info      # V1 仍为 Success，V2 变 Success

步骤 5：验证与校验

# 改一下已应用的 V1（比如加个空格），再执行 validate：
flyway validate
# ✗ ERROR: Migration checksum mismatch for migration version 1
#  → applied to database : X, resolved locally : Y

validate 发现 checksum 不一致。若确实要改，用 flyway repair 重新对齐历史表的 checksum：

flyway repair
flyway validate   # 通过

5.2 集成 Spring Boot

Spring Boot 只需引入依赖 + 配置，应用启动时（JPA 初始化前）自动执行迁移：

<!-- pom.xml -->
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<!-- 数据库驱动按需引入，如 flyway-database-postgresql / mysql-connector-j 等 -->

# application.yml
spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
  datasource:
    url: jdbc:postgresql://localhost:5432/demo
    username: postgres
    password: secret

把迁移脚本放在 src/main/resources/db/migration/（Spring Boot 默认位置）：

src/main/resources/db/migration/
├── V1__create_user_table.sql
└── V2__add_profile_column.sql

启动应用，日志中即可看到 Flyway ... Successfully validated 2 migrations 与 Migrating schema 输出。Maven 构建时也可用插件手动触发：

mvn flyway:migrate    # 默认绑定 pre-integration-test 阶段
gradle flywayMigrate

5.3 已有数据库如何接入 Flyway（Baseline）

项目已运行很久、数据库里已有大量对象，此时接入 Flyway 不能重跑历史脚本，用 baseline 打底：

# 假设现有 Schema 相当于"版本 1"的状态
flyway baseline -baselineVersion=1 -baselineDescription="Existing schema"

# 结果：历史表中插入一条 BASELINE 记录，版本 1，成功
flyway info
# │ Baseline │ 1 │ Existing schema │ BASELINE │ ... │ ✔ │

之后 flyway migrate 只会应用版本 > 1 的迁移（版本 ≤ 1 的脚本被视为 Below Baseline 而跳过）。也可直接开启自动基线：

flyway migrate -baselineOnMigrate=true   # 历史表为空且库非空时自动 baseline 到最新版本

6. 参数指令速查手册

6.1 命令速查

6.2 常用配置参数速查

6.3 常见问题排查