Flyway 数据库迁移 #

Flyway 是数据库版本管理工具，通过按顺序执行 SQL 迁移脚本实现表结构、索引和约束的增量演进。本项目的迁移文件统一存放在 src/main/resources/db/migration/ 下，由 Spring Boot 启动时自动执行。

命名规范 #

迁移文件命名格式为 V{version}__{description}.sql，注意版本号与描述之间是双下划线：

  • V1__init.sql — 初始建表
  • V2__phase1_hardening.sql — Phase 1 加固
  • V3__add_user_avatar.sql — 新增用户头像字段
  • V3_1__add_classroom_table.sql — 小版本号追加

版本号规则： - 主版本号使用递增整数（1, 2, 3...） - 小版本号用下划线分隔（3_1），用于同一个主版本内的增量脚本 - 同一个主版本号下按自然序执行（V3, V3_1, V3_2） - 版本号一旦提交到仓库就不能修改

添加新迁移 #

  1. 确认当前最大版本号 — 查看 db/migration/ 目录下已有的 SQL 文件，确定下一个可用版本号。
  2. 创建迁移文件 — 在 src/main/resources/db/migration/ 下新建 SQL 文件，按命名规范取名，例如 V4__add_course_tags.sql。
  3. 编写 SQL — 在新建文件中书写本次迁移的 DDL 或 DML。确保语句适合目标数据库（本项目使用 PostgreSQL）。
  4. 本地验证 — 启动本地 Core 服务，确认 Flyway 日志输出 Successfully applied 1 migration，无报错。
  5. 提交代码 — 将迁移文件随业务代码一并提交，PR 中注明迁移目的与影响范围。

常见操作 #

以下为本项目开发中高频使用的迁移 SQL 示例（PostgreSQL 语法）：

新增字段 #

ALTER TABLE t_user ADD COLUMN avatar VARCHAR(500);
ALTER TABLE t_user ADD COLUMN bio TEXT DEFAULT '';

添加注释 #

COMMENT ON COLUMN t_user.avatar IS '用户头像 URL';
COMMENT ON COLUMN t_user.bio IS '用户个人简介';

新建表 #

CREATE TABLE t_classroom (
    id          BIGSERIAL PRIMARY KEY,
    name        VARCHAR(200)  NOT NULL,
    teacher_id  BIGINT        NOT NULL REFERENCES t_user(id),
    created_at  TIMESTAMP     NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMP
);

COMMENT ON TABLE t_classroom IS '课堂表';

修改约束 #

-- 添加非空约束
ALTER TABLE t_classroom ALTER COLUMN name SET NOT NULL;

-- 添加唯一约束
ALTER TABLE t_user ADD CONSTRAINT uk_user_email UNIQUE (email);

-- 添加外键
ALTER TABLE t_task ADD CONSTRAINT fk_task_classroom
    FOREIGN KEY (classroom_id) REFERENCES t_classroom(id);

创建索引 #

CREATE INDEX idx_task_classroom_id ON t_task(classroom_id);
CREATE INDEX idx_user_role ON t_user(role);

注意事项 #

  • 绝不修改已提交的迁移文件 — Flyway 通过校验和检测变更，修改历史文件会导致启动失败。需要调整历史结构时，请新建一个迁移来补救。
  • 迁移与业务代码一起提交 — 避免迁移与代码不同步导致环境不一致。
  • 回滚需新建迁移 — Flyway 不支持自动回滚。如需撤销某次变更，新建一个反向操作的迁移文件，例如先 ADD COLUMN 后 DROP COLUMN。
  • 写幂等 SQL 更安全 — 尽量使用 ADD COLUMN IF NOT EXISTS 或先判断再操作的写法，降低重复执行风险。
  • 生产环境升级前先备份 — 在出具破坏性 DDL（如 DROP、ALTER TYPE）时，务必先导出当前库结构或做快照。

关联阅读 #