Java 后端 / 系统课时

使用 Flyway 管理表结构

使用 Flyway 管理表结构

本课把数据库结构变更从“人工执行 SQL”改造成可追踪、可校验的版本迁移。完成后,你将能在 Spring Boot 启动时按顺序创建表、写入初始化数据,并在部署阶段发现脚本缺失、顺序错误或校验和不一致。

学习目标

  • 配置 Spring Boot 3 集成 Flyway,并理解迁移脚本的命名与执行顺序
  • 编写表结构和初始化数据脚本,验证迁移结果
  • 处理已执行脚本被修改、版本冲突和生产部署失败

Flyway 如何管理版本

Flyway 会在目标数据库中维护 flyway_schema_history 表。应用启动时,它先读取历史记录,再扫描迁移目录,将尚未执行的版本脚本按版本号排序执行;每次成功迁移都会记录版本、描述、脚本名、校验和和执行状态。

Flyway 迁移与校验流程

版本迁移文件使用 V<版本>__<描述>.sql,双下划线不可省略。例如 V1__create_customer.sql 会先于 V2__seed_customer.sql 执行。已经在共享环境成功执行的版本脚本不应再修改;后续变更必须新增更高版本。

接入 Flyway

以下是 Maven 项目的依赖片段,放入现有 pom.xml 的 dependencies 节点。示例假设项目已引入 Spring JDBC 或 Spring Data JPA,以及对应数据库驱动。

xml
<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。

yaml
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。

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)
);

预期结果

text
成功创建 customer 表,并在 flyway_schema_history 中新增版本 1、状态 Success 的记录。

初始化数据应放在后续版本,避免把建表和数据问题混在同一次迁移中。创建 V2__seed_customer.sql。

sql
INSERT INTO customer (email, display_name)
VALUES ('admin@example.com', 'System Admin');

预期结果

text
customer 表新增 1 行初始化数据,flyway_schema_history 新增版本 2 的成功记录。

启动应用验证迁移。端口和时间等实际值可能不同。

bash
./mvnw spring-boot:run

预期输出

text
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 完成变更。

sql
ALTER TABLE customer
ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE';

预期结果

text
customer 表新增 status 列,已有记录填充为 ACTIVE,迁移历史新增版本 3。

常见故障可按以下顺序处理:

  • Validate failed:检查已执行脚本是否被改动、删除或重命名,优先从版本库恢复
  • 版本重复:确保同一迁移目录中每个版本号唯一,并统一团队的版本分配方式
  • SQL 执行失败:查看失败语句和数据库错误,修正后在未共享环境重建数据库;共享环境需评估清理失败记录或新增补偿迁移
  • 接管已有数据库:先核对现有结构,再谨慎配置 baseline,不能把 baseline 当作跳过未知历史的捷径

生产部署应先在与生产同版本的数据库副本执行迁移,确认锁表时间、数据回填耗时和回滚方案。对于大表变更,优先采用“先加兼容字段、再灰度写入、最后删除旧字段”的多阶段演进方式。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Flyway 管理表结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通