## 01、痛点

```
┌──────────────────────────────────────┐
│  数据库变更的典型灾难现场            │
├──────────────────────────────────────┤
│  开发环境：users 表多了 age 字段     │
│  测试环境：还是旧结构               │
│  生产环境：SQL 手工执行了一半       │
└──────────────────────────────────────┘
```

你有没有遇到过：本地数据库表结构改了，测试环境没改，上线后直接报错？我是老李，一个在后端和数据库之间反复横跳的开发者，今天聊聊怎么让数据库变更像代码一样有版本可回溯。

在很多团队里，数据库结构变更还停留在“谁改谁知道”的阶段。开发人员在本地库执行了一条 ALTER TABLE，然后把 SQL 文件发到群里，让运维去生产环境执行。运气好，执行成功，但没有记录；运气不好，测试环境漏执行，或者生产环境重复执行，导致线上事故。更常见的是，同一个项目在不同环境下表结构不一致：开发环境多了几个字段，测试环境还是旧结构，生产环境甚至不知道在哪个版本。数据库 Schema 无法像代码一样通过 Git 追踪版本，这是所有后端开发者的切肤之痛。

手工管理数据库变更的问题至少有三点。第一，执行顺序容易乱，先加字段还是先建表，没有约束。第二，执行状态不可见，某个脚本到底执行过没有，只能靠记忆。第三，回滚困难，出问题后不知道改了什么、什么时候改的。这些问题在单体时代还能靠人工小心应付，到了微服务和容器化时代，环境数量成倍增加，手工方式彻底不可持续。

## 02、是什么

```
┌──────────────┐      ┌──────────────────┐
│  Migration   │─────▶│ Schema Version   │
│  V1, V2, V3  │      │ 当前处于哪个版本 │
└──────────────┘      └──────────────────┘
         │
         ▼
┌──────────────────────┐
│ flyway_schema_history│
│ 记录每次迁移的元数据 │
└──────────────────────┘
```

Flyway 是一个开源的数据库迁移工具，核心思想是：把每一次数据库结构变更写成一个版本化的 SQL 脚本，然后由 Flyway 按照版本顺序自动执行，并把执行历史记录在数据库里。这样，数据库结构就拥有了和代码一样的版本管理能力。

Flyway 里有几个核心概念。Migration 是指一次数据库变更的单元，通常对应一个 SQL 文件，比如 V1__init_schema.sql。Schema Version 表示当前数据库结构对应的版本，由已经执行成功的 Migration 版本号决定。flyway_schema_history 是 Flyway 自动创建的一张历史表，用来记录每个 Migration 的执行情况，包括版本号、描述、脚本名、校验和、执行时间、是否成功等。

命名规范非常重要。最常用的版本化迁移文件格式是 V<version>__<description>.sql，版本号可以是数字或带点号的数字，例如 V1、V1.1、V2.0，后面两个下划线是固定分隔符，描述部分用下划线连接单词。Flyway 会按照版本号升序执行这些文件。除了版本化迁移，还支持可重复迁移，文件名以 R 开头，每次内容变化都会重新执行。

## 03、为什么

```
没有 Flyway：
  人工执行 SQL ──▶ 遗漏 ──▶ 环境不一致 ──▶ 事故

有 Flyway：
  版本化脚本 ──▶ 自动执行 ──▶ 记录历史 ──▶ 可重复
```

为什么现在必须用 Flyway 这种工具？因为数据库变更的频率和风险都上来了。微服务拆分后，每个服务都有自己的数据库，一个团队可能同时维护十几个数据库实例。容器化和 CI/CD 让应用可以随时发布，但数据库结构如果没有自动化迁移，发布就变成了一次次手工操作，既慢又容易出错。云原生环境要求基础设施可重复、可审计，数据库变更也不例外。

没有 Flyway 时，流程通常是：开发写完 SQL，发给 DBA 或者运维，在生产库执行，然后祈祷不会出错。一旦出错，要么回滚应用，要么紧急修库。有了 Flyway，SQL 脚本和代码放在同一个仓库，版本化、可评审、可追溯。发布时，Flyway 自动比对已执行记录和待执行脚本，只执行缺失的部分，已经执行过的不会被重复执行。更重要的是，Flyway 会校验每个已执行脚本的 checksum，如果脚本被修改，启动时直接报错，防止历史变更被篡改。

Spring Boot 集成 Flyway 的成本极低，只要引入一个依赖、配置一下数据源，启动时自动完成迁移。这对中小团队来说是性价比最高的数据库变更治理方案。

## 04、架构

```
Spring Boot 启动
      │
      ▼
DataSource 初始化
      │
      ▼
Flyway 自动配置执行迁移
      │
      ▼
flyway_schema_history 校验
      │
      ▼
JPA / MyBatis 初始化
```

在 Spring Boot 3.x 中，Flyway 的集成架构非常清晰。应用启动时，Spring Boot 会先初始化数据源 DataSource，然后触发 Flyway 的自动配置。Flyway 会扫描 classpath 下的迁移脚本目录，默认是 classpath:db/migration，也可以通过 flyway.locations 配置。接着，Flyway 会连接数据库，检查 flyway_schema_history 表是否存在，不存在则先创建。然后，它对比历史表和迁移脚本列表，找出尚未执行的迁移，按照版本号排序后逐个执行。每个迁移执行成功后，会向历史表插入一条记录。全部完成后，Spring Boot 的 JPA 或 MyBatis 才会继续初始化。

这个过程的关键点是顺序：Flyway 必须在 ORM 框架初始化之前完成，否则应用启动后可能读到不存在的表或字段。Spring Boot 的自动配置已经保证了这一点。flyway_schema_history 表的字段包括：installed_rank 表示执行顺序，version 表示迁移版本，description 是描述，type 是迁移类型，script 是文件名，checksum 是校验和，installed_by 是执行用户，installed_on 是执行时间，execution_time 是执行耗时，success 表示是否成功。这些字段让每次变更都有迹可循。

## 05、实战

```
项目结构
.
├── pom.xml
├── docker-compose.yml
├── src/main/resources
│   ├── application.yml
│   └── db/migration
│       └── V1__init_schema.sql
```

下面用一个 Java 21 + Spring Boot 3.x + Maven 的示例，走一遍完整流程。

第一步，创建项目。可以用 Spring Initializr 生成，选择 Java 21、Spring Boot 3.3.x、Maven，依赖勾选 Spring Web、Spring Data JPA（或 MyBatis）、Flyway Migration、MySQL Driver。最终 pom.xml 中会包含 flyway-core 和 mysql-connector-j，版本由 Spring Boot 管理，无需手动指定。

第二步，用 Docker Compose 启动 MySQL 8。新建 docker-compose.yml 文件，内容如下：

```
services:
  mysql:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: mydb
    ports:
      - '3306:3306'
```

执行 docker compose up -d 以后，MySQL 8 就运行在本地 3306 端口。

第三步，检查依赖引入。如果 pom.xml 中没有 flyway-core，手动添加：

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

第四步，配置 application.yml：

```
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC
    username: root
    password: root
  flyway:
    enabled: true
    locations: classpath:db/migration
```

这里 flyway.enabled 默认为 true，可以显式写出；locations 指定迁移脚本目录。

第五步，创建目录 src/main/resources/db/migration，并在其中新建 V1__init_schema.sql，内容如下：

```
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

第六步，启动 Spring Boot 应用。观察日志，会看到 Flyway 打印出正在执行 V1__init_schema.sql 的信息，然后应用正常启动。此时登录 MySQL，执行 SHOW TABLES，可以看到 users 表和 flyway_schema_history 表都已创建。

第七步，查看 flyway_schema_history 表，执行 SELECT version, description, checksum, success FROM flyway_schema_history; 会看到一条记录，version 为 1，description 为 init schema，checksum 是一个数字，success 为 1。这证明迁移已自动完成且记录在案。

## 06、洞见

```
判断待执行迁移：
classpath 迁移文件排序
      │
      ▼
对比 history 表已执行记录
      │
      ▼
找出 pending migrations
      │
      ▼
执行并写入 history
```

Flyway 的真正价值不只是自动执行 SQL，而是它建立了一套“不可变迁移”的纪律。一旦某个版本脚本被执行，它就不应该再被修改。Flyway 通过 checksum 来强制这一点：每个脚本在第一次执行时会计算一个 checksum，存入历史表；下次启动时，Flyway 会重新计算所有已执行脚本的 checksum，如果发现不匹配，立即抛出异常。这就逼迫团队把数据库变更当作“新版本”，而不是“改旧文件”。

那么，Flyway 如何判断哪些 SQL 需要执行？它会把 classpath 下所有符合命名规范的迁移文件按版本号排序，然后与 flyway_schema_history 表中的已执行版本对比。已执行且 checksum 一致的，跳过；已执行但 checksum 不一致的，报错；未执行的，加入待执行列表，按顺序执行。如果数据库不是空库但还没有历史表，可以配置 baseline-on-migrate: true，让 Flyway 以当前结构为基线，后续只执行高于基线版本的迁移。

关于 Spring Boot 启动顺序，有一个常见坑：JPA 的 ddl-auto 配置。如果 jpa.hibernate.ddl-auto 设置为 create 或 update，Hibernate 会尝试自动建表或更新表结构，这可能与 Flyway 的迁移逻辑冲突，导致表被重复创建或结构不一致。推荐将 ddl-auto 设为 validate 或 none，让 Flyway 全权负责数据库结构变更，Hibernate 只做校验。

## 07、行动

```
行动清单
☐ 现有项目引入 Flyway
☐ 建立 V1 基线脚本
☐ 统一命名规范
☐ 开启 checksum 校验
☐ 接入 CI 流水线
```

如果你现在的项目还没有数据库迁移工具，建议按以下步骤行动起来。第一步，先为现有数据库生成一份基线脚本，命名为 V1__baseline.sql，内容为当前完整的表结构。第二步，引入 Flyway，并在空库或新环境上验证迁移是否可重复执行。第三步，制定命名规范，例如 V1、V2、V3 依次递增，描述用英文小写加下划线。第四步，把迁移脚本纳入代码仓库，和业务代码一起评审、一起发布。第五步，在 CI 流水线中加入数据库迁移步骤，让测试环境先执行，确认无误后再到生产。第六步，定期检查 flyway_schema_history 表，确认没有异常记录。第七步，牢记一条铁律：已执行的迁移文件绝不修改，有变更就新增 V2、V3，宁可多文件，也不要改历史。

## 08、小结

```
┌─────────────────────────────────────┐
│  数据库变更的答案不是更小心，       │
│  而是更自动、更可回溯、更可重复。   │
└─────────────────────────────────────┘
```

数据库变更的答案不是更小心，而是更自动、更可回溯、更可重复。Flyway 不是什么复杂方案，它就是用版本化 SQL 和一张历史表，把数据库结构纳入工程化管理。你在代码里用 Git 追踪每一行变更，现在数据库结构也能做到同样的事。

## 09、链接与概念说明

```
┌─────────────┐
│ 概念澄清    │
└─────────────┘
```

最后澄清几个容易混淆的概念。Migration 不是指整个数据库迁移，而是单次变更的脚本单元。Schema Version 不是数据库软件版本，而是数据库结构对应的迁移版本号。flyway_schema_history 不是业务表，而是 Flyway 自己维护的元数据表，不要手动修改。Checksum 是脚本内容的校验和，用于防止已执行脚本被篡改。Baseline 是给已有数据库设置一个起始版本，让 Flyway 只处理后续变更。Undo 是回滚迁移，但社区版支持有限，通常需要自行规划版本回退。

延伸阅读建议查看 Flyway 官方文档中关于版本化迁移、命令、配置的章节；Spring Boot 官方文档中关于 Flyway 集成的部分；以及 Docker Hub 上 MySQL 8 镜像的环境变量说明。理解这些基础概念以后，你就可以放心地在生产环境使用 Flyway 了。

你有没有遇到过：本地数据库表结构改了，测试环境没改，上线后直接报错？我是老李，一个在后端和数据库之间反复横跳的开发者，今天聊聊怎么让数据库变更像代码一样有版本可回溯。

《Spring Boot Flyway 实战手册》第1招 Flyway 入门与集成——让数据库结构第一次拥有版本

本文从 Flyway 解决的核心问题出发，结合 Spring Boot 3.x + MySQL 8 实战，拆解迁移执行流程、版本表机制与启动顺序，帮你落地数据库

架构师

数据库

后端

开发工具

Flyway通过版本化SQL脚本和自动历史记录，解决数据库结构变更中执行顺序混乱、状态不可见和回滚困难三大痛点，让数据库Schema像代码一样可追踪、可审计，实现多环境结构一致和自动化部署。

数据库软件

代码解释

云原生

容器

Docker

MySQL

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《Spring Boot Flyway 实战手册》第1招 Flyway 入门与集成——让数据库结构第一次拥有版本-腾讯云开发者社区-腾讯云

《Spring Boot Flyway 实战手册》第1招 Flyway 入门与集成——让数据库结构第一次拥有版本

《Spring Boot Flyway 实战手册》第1招 Flyway 入门与集成——让数据库结构第一次拥有版本

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐