数据库迁移

约 677 字大约 2 分钟

布欧-Lewyon

2026-05-15

使用 Flyway 或 Liquibase 将数据库 Schema 变更纳入版本控制，确保各环境的表结构一致且可追溯。

Flyway

Flyway 是 Spring Boot 官方推荐的迁移工具，约定优于配置，使用 SQL 脚本管理变更。

集成

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

对于 PostgreSQL 等数据库，还需数据库特定依赖：

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>

迁移脚本

脚本放在 src/main/resources/db/migration/，命名规则：

V{版本号}__{描述}.sql

例如：

src/main/resources/db/migration/
├── V1__init_users_table.sql
├── V2__add_email_column.sql
└── V3__create_orders_table.sql

V1__init_users_table.sql：

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    age INTEGER NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_username ON users(username);

V2__add_email_column.sql：

ALTER TABLE users ADD COLUMN email VARCHAR(100);

配置

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true   # 对已有数据库首次启用时基线化

启动后日志可见 Flyway 自动执行迁移：

INFO  o.f.core.internal.command.DbMigrate - Current version of schema "public": 1
INFO  o.f.core.internal.command.DbMigrate - Migrating schema "public" to version "2 - add email column"
INFO  o.f.core.internal.command.DbMigrate - Successfully applied 1 migration

与 JPA ddl-auto 配合

生产环境建议：

spring:
  jpa:
    hibernate:
      ddl-auto: validate    # 启动时验证实体与表结构一致
  flyway:
    enabled: true           # 由 Flyway 管理表结构变更

Liquibase（简述）

Liquibase 使用 XML / YAML / JSON 描述变更而非纯 SQL：

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

# src/main/resources/db/changelog/db.changelog-master.yaml
databaseChangeLog:
  - changeSet:
      id: 1
      author: lewyon
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: BIGSERIAL
                  autoIncrement: true
                  constraints:
                    primaryKey: true
              - column:
                  name: username
                  type: VARCHAR(50)
                  constraints:
                    nullable: false

小结

Flyway 使用版本号命名的 SQL 脚本（V{version}__{desc}.sql）管理 Schema 变更。
脚本放在 db/migration/，自动按版本号顺序执行。
生产环境推荐 Flyway + ddl-auto: validate 组合。
易错：已执行的 Flyway 脚本不能修改（checksum 校验失败会阻止应用启动）。如果需修改，新建一个更高版本号的迁移脚本。baseline-on-migrate 对已有数据库首次启用 Flyway 时必须为 true。
生产意识：在多环境部署中，Flyway 脚本必须向前兼容——不能删除已有版本号的脚本，也不能修改已发布的脚本。版本号可以跳跃（如 V1→V3），但已执行的不会重复。如果某次迁移出错导致应用启动失败，可以使用 flyway.repair 修复校验和记录。禁止在迁移脚本中使用 DDL 语句内的 IF NOT EXISTS 作为"补丁"手段——这是掩盖设计问题的做法，应通过正确的版本号管理解决。
思考任务：在项目中集成 Flyway，编写 V1__init.sql 创建 users 表，编写 V2__add_email.sql 增加 email 列，启动验证表结构是否正确创建。

上一节：声明式事务

下一节：缓存