flyway-migrations-rrezartprebreza-spring-boot-skills

1. 基本信息

项目	内容
名称	flyway-migrations-rrezartprebreza-spring-boot-skills
作者/维护者	rrezartprebreza（个人开发者）
来源链接	https://github.com/rrezartprebreza/spring-boot-skills/tree/main/skills/spring-boot-4/flyway-migrations
许可证	MIT（GitHub API 获取）
GitHub Stars	196（整个 spring-boot-skills 合集仓库；该数字属整个合集，不代表本技能自身热度，GitHub API 获取）
Forks	35（同上，合集整体，GitHub API 获取）
最新版本	无独立版本号；仓库整体最近一次修订为 2026-07-30（GitHub API 获取）
安装方式	复制该子目录到 agent 的 skills 目录（见第 10 章）

2. 功能介绍与亮点

这是一份 Spring Boot 项目里用 Flyway 做数据库 schema 迁移的团队规范，把命名约定、安全变更手法与团队协作流程整理成可直接对照执行的清单。核心内容：

依赖陷阱提醒：Spring Boot 4 的模块化 starter 不再自动带出 Flyway——只加 spring-boot-starter-data-jpa 不会报错，但迁移会静默不执行；必须显式加 spring-boot-starter-flyway 和数据库专属模块（如 flyway-database-postgresql）
文件命名约定：V{version}__{description}.sql（一次性版本迁移）、R__{description}.sql（校验和变化时重跑的可重复迁移）、U{version}__{description}.sql（回滚，需付费版）三类前缀的双下划线规则与顺序编号纪律
安全变更模式对照：加可空列、加带默认值的列、CREATE INDEX CONCURRENTLY（需用 .sql.conf 旁路文件关闭事务包裹，否则在 Flyway 默认事务里直接失败）都标为安全；直接 RENAME COLUMN（会打断正在运行的应用）、给已有大表加不带默认值的 NOT NULL 列（会锁表失败）标为危险，并给出加列→回填→加约束→（后续版本）删旧列的四步安全改名替代方案
团队协作流程：多名开发者并发写迁移文件时的版本号冲突处理（共享追踪表、按时间戳编号），以及在 CI/CD 用 flyway validate 做部署前校验的建议
application.yml 配置与测试/开发环境种子数据（用 Spring @Profile("dev") 而非 Flyway 迁移文件塞测试数据）

文末附 9 条“agent 常犯错误”清单，覆盖上述全部要点，并额外指出 agent 常只加 flyway-core 而漏加数据库专属模块，导致启动报错 “Unsupported Database”。全部内容为纯 Markdown 文档配 SQL/YAML/Java 示例，另附 examples/（好坏迁移文件对照）与 templates/（迁移文件与种子数据模板）两个子目录的可直接复制文件。

3. 适用场景

所属分类：工程效率与代码质量——本技能产出的是数据库迁移文件本身的写法规范与团队协作纪律，属于技术栈编码指南范畴，不涉及运维数据库服务器或做数据分析。

适合任何使用 Spring Boot（4.x 或切换到仓库 Boot 3 分支）搭配关系型数据库、用 AI 编程 agent 生成或维护 Flyway 迁移脚本的后端团队。数据库迁移不同于普通业务代码——写错了不是编译失败，而是可能在生产环境锁死一张大表、或者悄悄跳过迁移导致线上 schema 与代码预期不一致，agent 独立生成迁移脚本时很容易忽略这类只在真实数据量下才会暴露的风险。

4. 跨 Agent 兼容性

Claude Code：原生支持——仓库明确提供 .claude/skills/ 安装路径与徽章标注兼容
Codex：原生支持——仓库同时提供 .codex/skills/ 安装路径与徽章标注兼容
OpenClaw：未验证——SKILL.md 遵循标准 YAML front matter + Markdown 正文格式，理论上可迁移，但仓库文档未点名支持
Hermes Agent：未验证——同上，未见任何提及

5. 推荐理由

数据库迁移是那种“平时不出事、出事就是大事”的代码：agent 独立生成迁移脚本时，最容易写出编译期看不出问题、却在真实数据量或并发部署时才暴露的坏迁移——给大表加不带默认值的 NOT NULL 列直接锁表失败，直接改列名会打断正在运行的应用。这份技能把安全变更模式（加列/回填/加约束/删列的四步替代方案）、CREATE INDEX CONCURRENTLY 在 Flyway 事务里的已知坑，以及 Spring Boot 4 一个容易被忽略的破坏性变化——Flyway 不再随 JPA/JDBC starter 自动引入，迁移可能悄无声息地不执行——整理成一份可直接对照执行的清单。对任何用 agent 维护 Spring Boot 项目数据库 schema 的团队，这是一份能实打实拦住生产事故的护栏文档。

6. 评分

维度	分数	说明
受欢迎程度	5	该技能所属子目录本身尚无独立的第三方讨论或引用证据；所属合集仓库由单一开发者维护，196 星与 35 复刻数字属整体仓库，不可归给单个子技能
可用性	9	复制单个文件夹即可安装，无需配置或付费依赖；仓库最近一次修订为 2026-07-30，内容随 Spring Boot 4 当前版本同步维护；除 SKILL.md 正文外另附可直接复制的好坏迁移对照示例与模板文件
安全性	9	纯 Markdown 文档配 SQL/YAML/Java 示例与模板文件，技能自身不执行任何命令、不联网、不要求任何凭据；仓库许可证明确（MIT）；内容未见任何可疑指令或误导性说明

综合评分：7.7

7. 跟同类 Skills 相比的优势

项目	定位	与本技能的差异
database-skills（planetscale/database-skills）	PlanetScale 官方数据库知识包，覆盖 MySQL/PostgreSQL/Vitess 的 schema 设计、索引、分区、事务锁与性能排查	覆盖面是数据库设计与运维全流程，但不含 Flyway 这类迁移工具的文件命名约定、多人协作版本冲突处理这类迁移工作流细节；本技能反过来不涉及索引调优或分片架构
springboot-migration（a-pavithraa/springboot-skills-marketplace）	名称同含“migration”，但实际是把 Spring Boot 应用从 3.x 升级到 4.x（含 Java 25、Spring Modulith 2、Testcontainers 2）的框架版本升级技能，附带迁移扫描脚本	主题完全不同——该技能处理的是“框架版本”迁移（一次性升级项目依赖与代码），本技能处理的是“数据库 schema”迁移（项目生命周期内持续新增的版本化 SQL 变更），两者可能被同一个“migration”关键词搜到但服务的是不同场景

8. 用户评价

该技能目前在第三方平台尚无具名用户评价。

9. 其他补充

仓库同时维护 Spring Boot 3 分支下的等价版本（迁移文件命名与安全变更模式部分不变，Boot 4 专属的 starter 依赖细节在 Boot 3 分支被替换为等效说明），供仍在 Spring Boot 3.x 的团队使用。

10. 安装使用方式

Claude Code：

mkdir -p "$PROJECT_DIR/.claude/skills"
cp -r skills/spring-boot-4/flyway-migrations "$PROJECT_DIR/.claude/skills/"

Codex：

mkdir -p "$PROJECT_DIR/.codex/skills"
cp -r skills/spring-boot-4/flyway-migrations "$PROJECT_DIR/.codex/skills/"

安装后无需重启 agent，下次涉及数据库迁移文件、schema 变更或种子数据脚本的生成与修改时会被自动读取触发；仓库同时提供 Spring Boot 3 分支的等价目录（skills/spring-boot-3/flyway-migrations），按项目实际框架版本二选一。

11. 注意事项

回滚迁移（U{version}__ 前缀）需要付费版 Flyway Teams，技能本身不含免费替代方案，仅作命名约定说明
CREATE INDEX CONCURRENTLY 的旁路配置（.sql.conf 文件、executeInTransaction=false）是 Flyway 特有机制，换成 Liquibase 等其他迁移工具不适用
技能给出的是迁移文件写法与团队流程的模板，落地时仍需团队根据自身数据库类型与既有迁移历史做一次性适配，不是开箱即用的最终产物
仓库由个人开发者维护，无企业组织背书，长期维护的连续性无法保证