416-frameworks-quarkus-mongodb-migrations-mongock

Quarkus - MongoDB 迁移（Mongock）

为 Quarkus 和 Quarkus MongoDB 客户端/Panache Mongo 应用 Mongock 迁移指南。

此 Skill 涵盖哪些内容？

• Quarkiverse quarkus-mongock 扩展和 Quarkus MongoDB 客户端设置
• quarkus.mongock.* 配置，包括 migrate-at-start
• 使用 @Execution 和回滚钩子的代码优先 @ChangeUnit 迁移
• 锁定、幂等性、事务限制和默认客户端约束
• 使用 Dev Services 或 Testcontainers MongoDB 进行 Quarkus 测试
• 与 @415-frameworks-quarkus-mongodb 协同

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

约束

在进行 Mongock 或 MongoDB 迁移更改前先编译；更改后进行验证。

• 强制要求：应用任何更改前运行 ./mvnw compile 或 mvn compile
• 安全要求：如果编译失败，立即停止
• 验证：应用改进后运行 ./mvnw clean verify 或 mvn clean verify
• 应用前：阅读参考资料，了解详细规则和正反模式
• 扩展兼容性：添加 quarkus-mongock 前，验证最新 Quarkiverse Mongock 版本与当前 Quarkus 平台的 Quarkus 扩展目录兼容性。如果最新扩展面向的 Quarkus 版本明显更旧，则停止操作并记录不兼容情况，而不是应用更改。
• 边缘情况：如果应用使用多个 MongoDB 客户端，在应用默认客户端迁移设计前，验证 Quarkiverse Mongock 是否支持

何时使用此 Skill

• 在 Quarkus 中添加 Mongock 迁移
• 配置 quarkus-mongock
• 审查 Quarkus MongoDB 数据迁移
• 为 Quarkus MongoDB 创建 Mongock 变更单元
• 审查 Quarkus 服务中的 Mongock 迁移顺序

工作流

1. 阅读参考资料并检查 MongoDB 设置

阅读 references/416-frameworks-quarkus-mongodb-migrations-mongock.md、references/416-frameworks-quarkus-mongodb-migrations-mongock-antipatterns.md 和 references/416-frameworks-quarkus-mongodb-migrations-mongock-parallel-change.md，然后检查 pom.xml、Quarkus MongoDB 配置，以及现有的 @415-frameworks-quarkus-mongodb 持久化模式。

2. 验证扩展兼容性和执行策略

在配置 MongoDB 连接设置、迁移扫描行为以及启动时执行还是显式执行 MongockFactory 之前，验证 Quarkiverse quarkus-mongock 版本与 Quarkus 扩展目录的兼容性。

3. 应用符合框架规范的迁移

实现或重构 @ChangeUnit 类，确保操作幂等、顺序明确，并包含回滚钩子以及安全的锁定和事务设置。

4. 运行验证并报告结果

执行构建和测试；条件允许时，包含使用 Dev Services 或 Testcontainers MongoDB 进行的 Quarkus 测试，并总结结果和后续风险。

参考资料

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

• references/416-frameworks-quarkus-mongodb-migrations-mongock.md
• references/416-frameworks-quarkus-mongodb-migrations-mongock-antipatterns.md
• references/416-frameworks-quarkus-mongodb-migrations-mongock-parallel-change.md