Java 后端 / 系统课时
使用 Flyway 管理表结构
使用 Flyway 管理表结构
本课把数据库结构变更从“人工执行 SQL”改造成可追踪、可校验的版本迁移。完成后,你将能在 Spring Boot 启动时按顺序创建表、写入初始化数据,并在部署阶段发现脚本缺失、顺序错误或校验和不一致。
学习目标
- 配置 Spring Boot 3 集成 Flyway,并理解迁移脚本的命名与执行顺序
- 编写表结构和初始化数据脚本,验证迁移结果
- 处理已执行脚本被修改、版本冲突和生产部署失败
Flyway 如何管理版本
Flyway 会在目标数据库中维护 flyway_schema_history 表。应用启动时,它先读取历史记录,再扫描迁移目录,将尚未执行的版本脚本按版本号排序执行;每次成功迁移都会记录版本、描述、脚本名、校验和和执行状态。

版本迁移文件使用 V<版本>__<描述>.sql,双下划线不可省略。例如 V1__create_customer.sql 会先于 V2__seed_customer.sql 执行。已经在共享环境成功执行的版本脚本不应再修改;后续变更必须新增更高版本。
接入 Flyway
以下是 Maven 项目的依赖片段,放入现有 pom.xml 的 dependencies 节点。示例假设项目已引入 Spring JDBC 或 Spring Data JPA,以及对应数据库驱动。
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-core</artifactId>
</dependency>
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>在 application.yml 中配置数据源和迁移位置。Spring Boot 3 会在数据源创建后、JPA 初始化前执行 Flyway。
spring:
datasource:
url: jdbc:postgresql://localhost:5432/app
username: app_user
password: app_password
jpa:
hibernate:
ddl-auto: validate
flyway:
enabled: true
locations: classpath:db/migration
validate-on-migrate: true这里将 Hibernate 设置为 validate,让实体映射只校验表结构,而不是自行改表。生产项目不要同时使用 Flyway 和 ddl-auto: update 管理结构,否则变更来源会失去唯一性。
编写迁移脚本
在 src/main/resources/db/migration 下创建首个迁移文件 V1__create_customer.sql。
CREATE TABLE customer (
id BIGSERIAL PRIMARY KEY,
email VARCHAR(200) NOT NULL,
display_name VARCHAR(100) NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT uk_customer_email UNIQUE (email)
);预期结果
成功创建 customer 表,并在 flyway_schema_history 中新增版本 1、状态 Success 的记录。初始化数据应放在后续版本,避免把建表和数据问题混在同一次迁移中。创建 V2__seed_customer.sql。
INSERT INTO customer (email, display_name)
VALUES ('admin@example.com', 'System Admin');预期结果
customer 表新增 1 行初始化数据,flyway_schema_history 新增版本 2 的成功记录。启动应用验证迁移。端口和时间等实际值可能不同。
./mvnw spring-boot:run预期输出
Successfully validated 2 migrations
Migrating schema "public" to version "1 - create customer"
Migrating schema "public" to version "2 - seed customer"
Successfully applied 2 migrations
Started <APPLICATION> in <TIME> seconds再次启动时不会重复执行 V1 和 V2,日志应显示当前 schema 已是最新版本。也可以直接查询历史表确认版本顺序和执行状态。
部署校验与失败处理
当已执行脚本被修改时,当前文件校验和会与历史记录不一致,Flyway 会中止启动。正确做法不是直接改历史记录,而是恢复原脚本,再新增 V3__alter_customer.sql 完成变更。
ALTER TABLE customer
ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE';预期结果
customer 表新增 status 列,已有记录填充为 ACTIVE,迁移历史新增版本 3。常见故障可按以下顺序处理:
Validate failed:检查已执行脚本是否被改动、删除或重命名,优先从版本库恢复- 版本重复:确保同一迁移目录中每个版本号唯一,并统一团队的版本分配方式
- SQL 执行失败:查看失败语句和数据库错误,修正后在未共享环境重建数据库;共享环境需评估清理失败记录或新增补偿迁移
- 接管已有数据库:先核对现有结构,再谨慎配置 baseline,不能把 baseline 当作跳过未知历史的捷径
生产部署应先在与生产同版本的数据库副本执行迁移,确认锁表时间、数据回填耗时和回滚方案。对于大表变更,优先采用“先加兼容字段、再灰度写入、最后删除旧字段”的多阶段演进方式。