---
name: infra-it-db-generator
description: "Use when generating DB integration tests (*IT) for infra mapper/store semantics with Flyway + Testcontainers Postgres."
---

# Infra IT DB Generator

## Overview
Generates Postgres-backed integration tests for mapper, store, and repository implementations using Flyway migrations and Testcontainers.
**REQUIRED:** Follow `GENERATOR_SKILL_STRUCTURE.md`. Variables in `VARIABLES.md`.

## When to Use
- DB integration tests for infra mapper/store/repository behavior.
- Typical targets: claim/release lease, status transition CAS, idempotency, migration guardrails.

### Don't use when
- The dependency is Redis — use `infra-it-cache-generator`.
- The dependency is HTTP — use `infra-it-http-generator`.
- The dependency is Kubernetes SDK — use `infra-it-k8s-generator`.
- The dependency is MQ — use `infra-it-mq-generator`.

## Inputs Required
- Target mapper/store and behavior matrix (`D1..D4` from plan).
- Related table names and unique/constraint assumptions.
- Whether to assert migration structure (table/index/constraint existence).

## Outputs
- `{{infraModuleDir}}/src/test/java/.../<Xxx>IT.java`
- Optional guardrail test under `infra/guardrail/*IT` or `*Test`.

## Naming & Packaging
- `*IT` suffix mandatory.
- Prefer package proximity to target infra component.

## Implementation Rules
- Use `@MybatisPlusTest` + Flyway baseline properties:
  - `spring.flyway.enabled=true`
  - `spring.flyway.locations=classpath:db/migration`
  - `spring.flyway.baseline-on-migrate=true`
  - `spring.flyway.baseline-version=0`
  - `spring.sql.init.mode=never`
- Use Testcontainers Postgres support class; no fixed localhost DSN.
- Always cleanup touched tables in `@BeforeEach`.
- Use unique ids/names per test.
- Assert behavior semantics (not SQL text snapshots).

## Template Blueprint
### 1. Integration Surface
- Relational DB (Postgres by default) via Testcontainers.
- Flyway migration execution in test lifecycle.
- Mapper/store/repository under test.

### 2. Required Annotations
- `@MybatisPlusTest` for MyBatis-Plus repository/store tests.
- Test property injection enabling Flyway and disabling SQL init conflicts.
- Container wiring style used by the project (for example `@ServiceConnection`).

### 3. Code Flow
- Arrange: migrate schema, clear touched tables, prepare unique records.
- Act: call mapper/store/repository methods for the target behavior matrix.
- Assert: verify persisted state transitions, CAS/idempotency semantics, and returned results.
- Cleanup: truncate/delete touched rows to keep test isolation.

## Tests
- IT-only gate:
  - `mvn -pl persimmon-scaffold/persimmon-scaffold-infra -Pit clean verify`
  - `-Pit` means Maven `-P it` (profile id is `it`).

## Common Mistakes
| Mistake | Why It Happens | Fix |
|---------|---------------|-----|
| Missing UUID type handler/imports in IT context | SpringBoot test slice doesn't auto-register all handlers | Explicitly register or import UUID type handler in test config |
| Relying on cross-test order or shared state | Tests assumed to run in isolation but share DB | Use unique ids per test and clean up in `@BeforeEach` |
| Mixing `spring.sql.init` with Flyway | Two schema init mechanisms conflict | Set `spring.sql.init.mode=never` when Flyway is enabled |

## Integration
- **Called by:** `scaffold-router`, `infra-integration-test-generator`
- **Pairs with:** `infra-bc-repository-generator`, `infra-store-implementation-generator`, `infra-flyway-migration-generator`

## Phase Commit Gate
- `mvn -pl persimmon-scaffold/persimmon-scaffold-infra clean test`
- `mvn -pl persimmon-scaffold/persimmon-scaffold-infra -Pit clean verify`