413-frameworks-quarkus-db-migrations-flyway

Quarkus — 数据库迁移（Flyway）

应用 Quarkus 的 Flyway 迁移指南。

此 Skill 涵盖哪些内容？

• quarkus-flyway 与 quarkus-jdbc-* 驱动
• src/main/resources/db/migration 下的版本化 SQL
• quarkus.flyway.migrate-at-start、位置和基线选项
• 多个数据源（如适用）
• 将 Parallel Change 作为安全的扩展、迁移、收缩工作流，用于有破坏性或对数据敏感的架构变更
• 与 @411-frameworks-quarkus-jdbc 和 @412-frameworks-quarkus-panache 协调

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

约束

应用 Flyway 或 SQL 变更前，确保项目可以编译。完成改进后，运行完整验证。

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

何时使用此 Skill

• 在 Quarkus 项目中添加或审查 Flyway 迁移
• 配置 quarkus-flyway 或 db/migration 目录结构
• 为 Quarkus 添加版本化 Flyway SQL 迁移
• 审查 Quarkus 数据库迁移顺序
• 在 Quarkus 中配置 Flyway clean migrate 或基线

工作流

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

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

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

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

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

按照参考模式和项目约定实施或重构配置/代码。对于有破坏性或对数据敏感的架构变更，默认采用 Parallel Change（扩展、迁移、收缩）作为安全做法。

4. 运行验证并报告结果

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

参考资料

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

• references/413-frameworks-quarkus-db-migrations-flyway.md
• references/413-frameworks-quarkus-db-migrations-flyway-antipatterns.md
• references/413-frameworks-quarkus-db-migrations-flyway-parallel-change.md