From 70d97e5ca8bdfa19c53cf1b59855d4a5905cdfcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Bre=C3=B1a=20Moral?= Date: Mon, 1 Jun 2026 10:54:07 +0200 Subject: [PATCH] feat(mongock): Adding initial support for Mongock for Spring Boot, Quarkus & Micronaut --- .../resources/skill-indexes/316-skill.xml | 53 ++++ .../resources/skill-indexes/416-skill.xml | 53 ++++ .../resources/skill-indexes/516-skill.xml | 53 ++++ ...orks-spring-mongodb-migrations-mongock.xml | 223 +++++++++++++++++ ...rks-quarkus-mongodb-migrations-mongock.xml | 236 ++++++++++++++++++ ...s-micronaut-mongodb-migrations-mongock.xml | 236 ++++++++++++++++++ .../src/main/resources/skills.xml | 15 ++ 7 files changed, 869 insertions(+) create mode 100644 skills-generator/src/main/resources/skill-indexes/316-skill.xml create mode 100644 skills-generator/src/main/resources/skill-indexes/416-skill.xml create mode 100644 skills-generator/src/main/resources/skill-indexes/516-skill.xml create mode 100644 skills-generator/src/main/resources/skill-references/316-frameworks-spring-mongodb-migrations-mongock.xml create mode 100644 skills-generator/src/main/resources/skill-references/416-frameworks-quarkus-mongodb-migrations-mongock.xml create mode 100644 skills-generator/src/main/resources/skill-references/516-frameworks-micronaut-mongodb-migrations-mongock.xml diff --git a/skills-generator/src/main/resources/skill-indexes/316-skill.xml b/skills-generator/src/main/resources/skill-indexes/316-skill.xml new file mode 100644 index 00000000..b33b34bb --- /dev/null +++ b/skills-generator/src/main/resources/skill-indexes/316-skill.xml @@ -0,0 +1,53 @@ + + + + Juan Antonio Breña Moral + 0.15.0 + Apache-2.0 + Use when you need to add or review Mongock MongoDB data migrations in a Spring Boot application — including Maven coordinates, Spring Data MongoDB drivers, migration scan packages, @ChangeUnit classes, lock/transaction settings, and Testcontainers verification. This should trigger for requests such as Add Mongock migrations in Spring Boot; Review Spring MongoDB data migrations; Configure Mongock change units for Spring Data MongoDB. + + + Spring - MongoDB migrations (Mongock) + + + + Compile before Mongock or MongoDB migration changes; verify after changes. + + **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change + **SAFETY**: If compilation fails, stop immediately + **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements + **BEFORE APPLYING**: Read the reference for detailed rules and good/bad patterns + **EDGE CASE**: If the project Spring Data MongoDB version is not compatible with the selected Mongock driver, stop and ask whether to pin/upgrade Mongock or use a lower driver generation + + + + + + Add Mongock migrations in Spring Boot + Review Spring MongoDB data migrations + Configure Mongock change units for Spring Data MongoDB + + + + + Read reference and inspect MongoDB setupRead `references/316-frameworks-spring-mongodb-migrations-mongock.md` and inspect `pom.xml`, Spring Boot version, MongoDB configuration, and existing `@315-frameworks-spring-mongodb` persistence patterns. + Choose runner, driver, and execution policySelect Mongock coordinates compatible with the active Spring Data MongoDB generation, configure migration scan packages, and decide startup vs controlled-job execution. + Apply framework-aligned migrationsImplement/refactor `@ChangeUnit` classes with idempotent operations, explicit ordering, rollback hooks, and safe lock/transaction settings. + Run verification and report resultsExecute build/tests, including Testcontainers-backed MongoDB migration checks where feasible, and summarize outcomes and follow-up risks. + + diff --git a/skills-generator/src/main/resources/skill-indexes/416-skill.xml b/skills-generator/src/main/resources/skill-indexes/416-skill.xml new file mode 100644 index 00000000..56658725 --- /dev/null +++ b/skills-generator/src/main/resources/skill-indexes/416-skill.xml @@ -0,0 +1,53 @@ + + + + Juan Antonio Breña Moral + 0.15.0 + Apache-2.0 + Use when you need to add or review Mongock MongoDB data migrations in a Quarkus application — including the Quarkiverse Mongock extension, Quarkus MongoDB client configuration, migrate-at-start, @ChangeUnit classes, lock/transaction settings, and Quarkus test verification. This should trigger for requests such as Add Mongock migrations in Quarkus; Configure quarkus-mongock; Review Quarkus MongoDB data migrations. + + + Quarkus - MongoDB migrations (Mongock) + + + + Compile before Mongock or MongoDB migration changes; verify after changes. + + **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change + **SAFETY**: If compilation fails, stop immediately + **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements + **BEFORE APPLYING**: Read the reference for detailed rules and good/bad patterns + **EDGE CASE**: If the application uses multiple MongoDB clients, verify Quarkiverse Mongock support before applying a default-client migration design + + + + + + Add Mongock migrations in Quarkus + Configure quarkus-mongock + Review Quarkus MongoDB data migrations + + + + + Read reference and inspect MongoDB setupRead `references/416-frameworks-quarkus-mongodb-migrations-mongock.md` and inspect `pom.xml`, Quarkus MongoDB configuration, and existing `@415-frameworks-quarkus-mongodb` persistence patterns. + Choose extension and execution policyConfigure `quarkus-mongock`, MongoDB connection settings, migration scan behavior, and startup vs explicit `MongockFactory` execution. + Apply framework-aligned migrationsImplement/refactor `@ChangeUnit` classes with idempotent operations, explicit ordering, rollback hooks, and safe lock/transaction settings. + Run verification and report resultsExecute build/tests, including Quarkus tests with Dev Services or Testcontainers MongoDB where feasible, and summarize outcomes and follow-up risks. + + diff --git a/skills-generator/src/main/resources/skill-indexes/516-skill.xml b/skills-generator/src/main/resources/skill-indexes/516-skill.xml new file mode 100644 index 00000000..b13c56b8 --- /dev/null +++ b/skills-generator/src/main/resources/skill-indexes/516-skill.xml @@ -0,0 +1,53 @@ + + + + Juan Antonio Breña Moral + 0.15.0 + Apache-2.0 + Use when you need to add or review Mongock MongoDB data migrations in a Micronaut application — including Mongock runner/driver selection, Micronaut bean wiring, migration scan packages, @ChangeUnit classes, lock/transaction settings, and Testcontainers verification. This should trigger for requests such as Add Mongock migrations in Micronaut; Review Micronaut MongoDB data migrations; Configure Mongock change units with Micronaut Data MongoDB. + + + Micronaut - MongoDB migrations (Mongock) + + + + Compile before Mongock or MongoDB migration changes; verify after changes. + + **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change + **SAFETY**: If compilation fails, stop immediately + **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements + **BEFORE APPLYING**: Read the reference for detailed rules and good/bad patterns + **EDGE CASE**: If a Micronaut-specific Mongock runner is unavailable or incompatible, use an explicit standalone runner bean/job and document that trade-off + + + + + + Add Mongock migrations in Micronaut + Review Micronaut MongoDB data migrations + Configure Mongock change units with Micronaut Data MongoDB + + + + + Read reference and inspect MongoDB setupRead `references/516-frameworks-micronaut-mongodb-migrations-mongock.md` and inspect `pom.xml`, Micronaut MongoDB configuration, and existing `@515-frameworks-micronaut-mongodb` persistence patterns. + Choose runner, driver, and execution policySelect compatible Mongock coordinates, wire the runner through Micronaut beans, configure migration scan packages, and decide startup vs controlled-job execution. + Apply framework-aligned migrationsImplement/refactor `@ChangeUnit` classes with idempotent operations, explicit ordering, rollback hooks, and safe lock/transaction settings. + Run verification and report resultsExecute build/tests, including `@MicronautTest` with Testcontainers MongoDB where feasible, and summarize outcomes and follow-up risks. + + diff --git a/skills-generator/src/main/resources/skill-references/316-frameworks-spring-mongodb-migrations-mongock.xml b/skills-generator/src/main/resources/skill-references/316-frameworks-spring-mongodb-migrations-mongock.xml new file mode 100644 index 00000000..d1ac78b5 --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/316-frameworks-spring-mongodb-migrations-mongock.xml @@ -0,0 +1,223 @@ + + + + Juan Antonio Breña Moral + 0.15.0 + Apache-2.0 + Spring - MongoDB migrations (Mongock) + Use when you need to add or review Mongock MongoDB data migrations in a Spring Boot application - including Mongock BOM/dependencies, Spring Data MongoDB driver selection, migration scan packages, `@ChangeUnit` classes, lock and transaction behavior, and Testcontainers validation. For general Spring Data MongoDB persistence use `@315-frameworks-spring-mongodb`. + + + You are a Senior software engineer with extensive experience in Spring Boot, Spring Data MongoDB, and code-first MongoDB migrations with Mongock + + + + + + Before applying any recommendations, ensure the project is in a valid state by running Maven compilation. + Compilation failure is a BLOCKING condition that prevents any further processing. + + + **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change + **PREREQUISITE**: Project must compile successfully before Mongock, MongoDB, or migration edits + **CRITICAL SAFETY**: If compilation fails, IMMEDIATELY STOP and DO NOT CONTINUE + **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements; include a MongoDB-backed migration test where feasible + **COMPATIBILITY**: Verify the Mongock runner and driver generation against the active Spring Boot and Spring Data MongoDB versions before adding dependencies + + + + + + + + + Maven coordinates + Use the Mongock BOM and select the runner/driver generation that matches Spring Data MongoDB + + + + + + + + io.mongock + mongock-bom + ${mongock.version} + pom + import + + + + + + + io.mongock + mongock-springboot-v3 + + + io.mongock + mongodb-springdata-v4-driver + + + org.springframework.boot + spring-boot-starter-data-mongodb + +]]> + + + + + io.mongock + mongock-springboot + 5.0.0 + + + io.mongock + mongodb-springdata-v2-driver + 5.5.1 +]]> + + + + + + + Spring Boot configuration + Declare migration scan packages and make startup behavior explicit + + + + + + + + + + + + + + + ChangeUnit design + Use MongoTemplate or low-level operations instead of repositories tied to changing domain models + + + + + + + + repository.save(order.withStatus("PENDING"))); + } +}]]> + + + + + + + Testing migrations + Exercise startup migration against real MongoDB with Testcontainers + + + + + assertThat(order).containsKey("status")); + } +}]]> + + + + + + + + + + + **ANALYZE** Spring Boot MongoDB setup: Boot version, Spring Data MongoDB generation, Mongock BOM, runner, driver, scan package, and startup policy + **CATEGORIZE** migration risks (COMPATIBILITY, LOCKING, IDEMPOTENCY, DOMAIN COUPLING, TEST GAP) by impact + **APPLY** Spring-aligned fixes: compatible dependencies, focused `mongock.*` properties, stable `@ChangeUnit` classes, and Testcontainers checks + **ALIGN** with `@315-frameworks-spring-mongodb` for normal document/repository design while keeping migrations independent + **VALIDATE** with `./mvnw compile` before changes and `./mvnw clean verify` after changes + + + + + + **DO NOT EDIT APPLIED MIGRATIONS**: Once a `@ChangeUnit` has run in a shared environment, add a new ordered change instead of modifying it + **IDEMPOTENCY**: Write migrations so interrupted non-transactional execution can safely continue on the next run + **LOCKING**: Do not hide lock acquisition failures in clustered deployments unless there is a documented external migration coordinator + **DOMAIN MODEL DRIFT**: Avoid repositories and mutable domain models inside old migrations; use stable collection/field operations + **BLOCKING SAFETY CHECK**: Run `./mvnw compile` before recommending dependency or migration changes + + + diff --git a/skills-generator/src/main/resources/skill-references/416-frameworks-quarkus-mongodb-migrations-mongock.xml b/skills-generator/src/main/resources/skill-references/416-frameworks-quarkus-mongodb-migrations-mongock.xml new file mode 100644 index 00000000..b67cf9d3 --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/416-frameworks-quarkus-mongodb-migrations-mongock.xml @@ -0,0 +1,236 @@ + + + + Juan Antonio Breña Moral + 0.15.0 + Apache-2.0 + Quarkus - MongoDB migrations (Mongock) + Use when you need to add or review Mongock MongoDB data migrations in a Quarkus application - including the Quarkiverse Mongock extension, Quarkus MongoDB client configuration, `quarkus.mongock.*` settings, `@ChangeUnit` classes, lock and transaction behavior, and Quarkus test validation. For general Quarkus MongoDB persistence use `@415-frameworks-quarkus-mongodb`. + + + You are a Senior software engineer with extensive experience in Quarkus, Quarkus MongoDB client/Panache Mongo, and code-first MongoDB migrations with Mongock + + + + + + Before applying any recommendations, ensure the project is in a valid state by running Maven compilation. + Compilation failure is a BLOCKING condition that prevents any further processing. + + + **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change + **PREREQUISITE**: Project must compile successfully before Mongock, MongoDB, or migration edits + **CRITICAL SAFETY**: If compilation fails, IMMEDIATELY STOP and DO NOT CONTINUE + **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements; include a MongoDB-backed Quarkus test where feasible + **COMPATIBILITY**: Verify the Quarkiverse Mongock extension version against the active Quarkus platform before adding dependencies + **DEFAULT CLIENT LIMIT**: If the application uses multiple MongoDB clients, confirm the extension supports that topology before implementing migrations + + + + + + + + + Maven extension + Add Quarkiverse Mongock with the Quarkus MongoDB client + + + + + + 0.6.0 + + + + + io.quarkus + quarkus-mongodb-client + + + io.quarkiverse.mongock + quarkus-mongock + ${quarkus-mongock.version} + +]]> + + + + + io.quarkiverse.mongock + quarkus-mongock + 0.6.0 +]]> + + + + + + + application.properties + Configure MongoDB and make migrate-at-start intentional + + + + + + + + + + + + + + + ChangeUnit design + Use stable MongoDB collection operations rather than mutable Panache entity APIs + + + + + + + + { + order.status = "PENDING"; + order.update(); + }); + } +}]]> + + + + + + + Explicit execution + Use MongockFactory when startup execution is not the right operational model + + + + + + + + + + + + + + + Testing migrations + Run migrations with @QuarkusTest and real MongoDB infrastructure + + + + + orders = mongoClient.getDatabase("orders") + .getCollection("orders") + .find() + .into(new ArrayList<>()); + + assertThat(orders).allSatisfy(order -> assertThat(order).containsKey("status")); + } +}]]> + + + + + + + + + + + **ANALYZE** Quarkus MongoDB setup: platform version, Quarkiverse Mongock version, default MongoDB client, migration execution mode, and tests + **CATEGORIZE** migration risks (EXTENSION COMPATIBILITY, DEFAULT CLIENT, LOCKING, IDEMPOTENCY, DOMAIN COUPLING, TEST GAP) by impact + **APPLY** Quarkus-aligned fixes: extension coordinates, `quarkus.mongock.*` properties, stable `@ChangeUnit` classes, and Quarkus MongoDB tests + **ALIGN** with `@415-frameworks-quarkus-mongodb` for normal MongoDB/Panache Mongo design while keeping migrations independent + **VALIDATE** with `./mvnw compile` before changes and `./mvnw clean verify` after changes + + + + + + **DO NOT EDIT APPLIED MIGRATIONS**: Once a `@ChangeUnit` has run in a shared environment, add a new ordered change instead of modifying it + **IDEMPOTENCY**: Write migrations so interrupted non-transactional execution can safely continue on the next run + **LOCKING**: Keep lock acquisition failures visible in clustered deployments unless an external coordinator is documented + **EXTENSION LIMITS**: Re-check Quarkiverse Mongock limitations for multiple clients, native mode, and transaction behavior during upgrades + **BLOCKING SAFETY CHECK**: Run `./mvnw compile` before recommending dependency or migration changes + + + diff --git a/skills-generator/src/main/resources/skill-references/516-frameworks-micronaut-mongodb-migrations-mongock.xml b/skills-generator/src/main/resources/skill-references/516-frameworks-micronaut-mongodb-migrations-mongock.xml new file mode 100644 index 00000000..d50794f1 --- /dev/null +++ b/skills-generator/src/main/resources/skill-references/516-frameworks-micronaut-mongodb-migrations-mongock.xml @@ -0,0 +1,236 @@ + + + + Juan Antonio Breña Moral + 0.15.0 + Apache-2.0 + Micronaut - MongoDB migrations (Mongock) + Use when you need to add or review Mongock MongoDB data migrations in a Micronaut application - including Mongock runner/driver selection, Micronaut bean wiring, migration scan packages, `@ChangeUnit` classes, lock and transaction behavior, and Testcontainers validation. For general Micronaut MongoDB persistence use `@515-frameworks-micronaut-mongodb`. + + + You are a Senior software engineer with extensive experience in Micronaut, Micronaut Data MongoDB, and code-first MongoDB migrations with Mongock + + + + + + Before applying any recommendations, ensure the project is in a valid state by running Maven compilation. + Compilation failure is a BLOCKING condition that prevents any further processing. + + + **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change + **PREREQUISITE**: Project must compile successfully before Mongock, MongoDB, or migration edits + **CRITICAL SAFETY**: If compilation fails, IMMEDIATELY STOP and DO NOT CONTINUE + **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements; include a MongoDB-backed Micronaut test where feasible + **COMPATIBILITY**: Verify whether the selected Mongock version documents a compatible Micronaut runner before recommending Micronaut-specific runner coordinates + + + + + + + + + Maven coordinates + Use the Mongock BOM with the standalone runner and MongoDB sync driver when no compatible Micronaut runner is verified + + + + + + + + io.mongock + mongock-bom + ${mongock.version} + pom + import + + + + + + + io.mongock + mongock-standalone + + + io.mongock + mongodb-sync-v4-driver + + + io.micronaut.mongodb + micronaut-mongo-sync + +]]> + + + + + io.mongock + mongock-micronaut + 5.5.1 +]]> + + + + + + + Runner bean + Wire a controlled Mongock standalone runner through Micronaut + + + + + + + + + + + + + + + ChangeUnit design + Use stable MongoDB operations rather than Micronaut Data repositories + + + + + + + + repository.update(order.withStatus("PENDING"))); + } +}]]> + + + + + + + Testing migrations + Run Micronaut migration wiring against Testcontainers MongoDB + + + + + orders = mongoClient.getDatabase("orders") + .getCollection("orders") + .find() + .into(new ArrayList<>()); + + assertThat(orders).allSatisfy(order -> assertThat(order).containsKey("status")); + } +}]]> + + + + + + + + + + + **ANALYZE** Micronaut MongoDB setup: Micronaut version, MongoDB client type, available Mongock runner, driver, scan package, and startup policy + **CATEGORIZE** migration risks (RUNNER COMPATIBILITY, LOCKING, IDEMPOTENCY, DOMAIN COUPLING, STARTUP TIME, TEST GAP) by impact + **APPLY** Micronaut-aligned fixes: compatible Mongock dependencies, explicit runner bean/job, stable `@ChangeUnit` classes, and Testcontainers checks + **ALIGN** with `@515-frameworks-micronaut-mongodb` for normal document/repository design while keeping migrations independent + **VALIDATE** with `./mvnw compile` before changes and `./mvnw clean verify` after changes + + + + + + **DO NOT EDIT APPLIED MIGRATIONS**: Once a `@ChangeUnit` has run in a shared environment, add a new ordered change instead of modifying it + **IDEMPOTENCY**: Write migrations so interrupted non-transactional execution can safely continue on the next run + **STARTUP TIME**: Do not run long backfills in a startup listener if probes or rollout windows can interrupt them repeatedly + **RUNNER CLAIMS**: Do not invent Micronaut-specific Mongock coordinates; verify official artifacts or use the standalone runner pattern + **BLOCKING SAFETY CHECK**: Run `./mvnw compile` before recommending dependency or migration changes + + + diff --git a/skills-generator/src/main/resources/skills.xml b/skills-generator/src/main/resources/skills.xml index 6bb6a261..eabc6f12 100644 --- a/skills-generator/src/main/resources/skills.xml +++ b/skills-generator/src/main/resources/skills.xml @@ -267,6 +267,11 @@ 315-frameworks-spring-mongodb + + + 316-frameworks-spring-mongodb-migrations-mongock + + 321-frameworks-spring-boot-testing-unit-tests @@ -327,6 +332,11 @@ 415-frameworks-quarkus-mongodb + + + 416-frameworks-quarkus-mongodb-migrations-mongock + + 421-frameworks-quarkus-testing-unit-tests @@ -387,6 +397,11 @@ 515-frameworks-micronaut-mongodb + + + 516-frameworks-micronaut-mongodb-migrations-mongock + + 521-frameworks-micronaut-testing-unit-tests