313-frameworks-spring-db-migrations-flyway

Spring — 数据库迁移（Flyway）

应用适用于 Spring Boot 的 Flyway 迁移指南。

此技能涵盖哪些内容？

• 使用 Spring Boot BOM 的 flyway-core 和特定数据库的 Flyway 模块（例如 PostgreSQL）
• src/main/resources/db/migration 下的版本化 SQL（V{version}__{description}.sql）
• spring.flyway.* 属性：locations、baseline-on-migrate、validate-on-migrate
• 用于数据回填的可选 Java 迁移（BaseJavaMigration）
• 仅向前的原则：不要在共享环境中重写已应用的迁移
• Parallel Change：针对破坏性或对数据敏感的架构变更，采用安全的扩展、迁移、收缩工作流
• 与 @311-frameworks-spring-jdbc 和 @312-frameworks-spring-data-jdbc 协同

范围： 根据参考规则和正反示例应用建议。

约束

在应用 Flyway 或 SQL 变更之前，确保项目能够编译。改进后，运行完整验证。

• 强制要求：应用任何变更之前，运行 ./mvnw compile 或 mvn compile
• 安全要求：如果编译失败，立即停止
• 验证要求：应用改进后，运行 ./mvnw clean verify 或 mvn clean verify
• 应用前：阅读参考资料，了解详细规则和正反模式
• 破坏性变更审查：在建议或应用迁移之前，评估它是否可能影响已部署的应用版本、依赖服务、报告、作业或生产数据的解读；如果可能，则必须先由人工明确审查
• 边界情况：如果用户目标不明确，在编辑文件或运行项目范围的命令之前停止并提出澄清问题
• 边界情况：如果缺少必要的上下文、文件、凭据或工具，明确说明阻碍，并询问是否继续进行设置或提供备用指导
• 边界情况：如果请求的变更与项目约束或安全边界冲突，说明冲突，并请用户确认首选的权衡方案

何时使用此技能

• 在 Spring Boot 项目中添加或审查 Flyway 迁移
• 配置 spring.flyway 或 db/migration 布局
• 为 Spring Boot 添加版本化 Flyway SQL 迁移
• 审查 Spring Boot 数据库迁移的顺序
• 修复 Spring 项目中的可重复 Flyway 迁移

工作流

1. 阅读参考资料并评估项目上下文

阅读 references/313-frameworks-spring-db-migrations-flyway.md、references/313-frameworks-spring-db-migrations-flyway-antipatterns.md 和 references/313-frameworks-spring-db-migrations-flyway-parallel-change.md，然后检查当前项目配置，再提出变更建议。

2. 明确范围并确定目标改进

确定请求的结果、约束，以及要应用的最小安全变更集。

3. 应用符合框架规范的变更

遵循参考模式和项目惯例实现或重构配置/代码。对于破坏性或对数据敏感的架构变更，默认采用 Parallel Change（扩展、迁移、收缩）作为安全方案。

4. 运行验证并报告结果

执行适当的构建/测试，并总结变更内容、验证情况以及后续操作。

参考资料

详细指南、示例和约束请参阅：

• references/313-frameworks-spring-db-migrations-flyway.md
• references/313-frameworks-spring-db-migrations-flyway-antipatterns.md
• references/313-frameworks-spring-db-migrations-flyway-parallel-change.md