Skip to content
Skills Library
Programming · Building & coding

create-persistence-adapter

/create-persistence-adapter

Create or update the JPA persistence adapter for one domain aggregate: entity, Spring Data repository, mapper, the @Component implementing the outbound Repository port, its Flyway migration and its @DataJpaTest. Use when the user asks to create a persistence adapter, persist an aggregate, add a column or a query, or add an outbound db adapter.

Licence
MIT
Last repository change
07.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Create or update the JPA persistence adapter for one domain aggregate: entity, Spring Data repository, mapper, the @Component implementing the outbound Repository port, its Flyway migration and its @DataJpaTest. Use when the user asks to create a persistence adapter, persist an aggregate, add a column or a query, or add an outbound db adapter.

Arguments

/create-persistence-adapter [Repository port or domain aggregate]
Original author description

Create or update the JPA persistence adapter for one domain aggregate: entity, Spring Data repository, mapper, the @Component implementing the outbound Repository port, its Flyway migration and its @DataJpaTest. Use when the user asks to create a persistence adapter, persist an aggregate, add a column or a query, or add an outbound db adapter.

How it works

  1. Production pattern
  2. Test pattern
  3. Instructions
Original SKILL.md headings · 62 lines, 467 words
SKILL.md preview
---
name: create-persistence-adapter
argument-hint: "[Repository port or domain aggregate]"
description: "Create or update the JPA persistence adapter for one domain aggregate: entity, Spring Data repository, mapper, the @Component implementing the outbound Repository port, its Flyway migration and its @DataJpaTest. Use when the user asks to create a persistence adapter, persist an aggregate, add a column or a query, or add an outbound db adapter."
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# Skill: create-persistence-adapter

Files per aggregate in `adapter/outbound/db/` (package `io.miragon.blueprint` under
`service/example-service/src/main/`), the tests next to them in the test tree. The rules are in
`AGENTS.md` (Architecture, Testing) and [ADR-0010](../../../docs/adr/0010-flyway-for-database-migrations.md).

## Production pattern

Copy the shape of the existing adapters:

| Aggregate | Reference | Shows |
|---|---|---|
| `LeasingApplication` | `LeasingApplicationEntity`, `LeasingApplicationJpaRepository`, `LeasingApplicationEntityMapper`, `LeasingApplicationPersistenceAdapter` | a separate mapper, a filtered and paged query behind the port's own `Criteria`/`Page` |
| `Bike` | `BikeEntity`, `BikePortfolioJpaRepository`, `BikePortfolioPersistenceAdapter` | a small aggregate mapped inside the adapter |

- The adapter is a `@Component` implementing exactly the outbound `*Repository` port.
- **Spring Data types stop at the adapter.** The port owns `Criteria`/`Page`; the adapter translates
  (`PageRequest`, `Sort`) and returns the port's types.
- Columns are `snake_case`, enums `@Enumerated(EnumType.STRING)`, value objects are mapped to
  primitives and back (`ApplicationId(UUID)` ↔ `UUID`).
- **Flyway owns the schema.** Hibernate only validates (`ddl-auto: validate`), so every entity change
  ships with the next `service/example-service/src/main/resources/db/migration/V<n>__<what>.sql`;
  never edit an applied migration. A new filter or sort column gets an index.

## Test pattern

`@DataJpaTest` + `@ActiveProfiles("test")` + `@Import(<Adapter>)` (reference:
`LeasingApplicationPersistenceAdapterTest`), one test per port method and per filter, including the
empty result:

- **Round trip through a cleared context:** save, `flush()`, `clear()`, then read back, or the test only
  reads the first-level cache.
- **Read tests seed independently** of the adapter under test: an `@Sql` script in
  `service/example-service/src/test/resources/sql/` (see `leasing-application.sql` and the `findById`
  test), so a broken `save` cannot hide a broken read. The older `findAll` tests and
  `BikePortfolioPersistenceAdapterTest` still seed through `save`; don't copy that.
- **A new column** also goes into the seed script and into the defaults of the domain test factory
  (`TestObjectBuilder`). The test schema is generated from the entities (`ddl-auto: create-drop`), so
  a seed without the column still runs and the round trip silently compares `null`.
- Compare whole objects (`usingRecursiveComparison()`) built with the domain test factory
  (`TestObjectBuilder`). A separate mapper gets its own plain unit test for every field
  (`LeasingApplicationEntityMapperTest`).

Tests run against H2 with Flyway off; the migration is checked when the service starts against
Postgres, so start it once after a schema change.

## Instructions

1. **Resolve the aggregate** from `$ARGUMENTS` (a `*Repository` port in `application/port/outbound/` or
   an aggregate in `domain/`), else list the ports and ask.
2. **Derive the target state:** columns, value-object mapping, the queries the port needs. Add only
   what is missing to existing files.
3. **Write the tests first**, then entity, repository, mapper, adapter and migration.
4. **Verify:** the adapter and mapper tests by name, then the architecture tests (`AGENTS.md` →
   Verify After Each Task); with the stack running, start the service once so Hibernate validates the
   schema against the migrated Postgres.
<!-- variant:blueprint -->
5. **Both variants:** the same classes and tests in `kotlin-gradle/` and `java-maven/`; the migration
   is byte-identical in both.
<!-- /variant:blueprint -->

Versions

RepositoryScoreLicence
This page · Miragon/process-engine-blueprints100MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT
Miragon/process-engine-blueprints90MIT

Database snapshot: 13.11.2026 · package version 6ab27acb4aee (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100spring-data-jpa
    Add JPA persistence to an existing Spring Boot 4 Maven project — entities, repositories, auditing, Flyway migrations, and Testcontainers integration tests. Use when asked to add a database, JPA entities or repositories, or Flyway migrations. Assumes a feature-sliced layout like…
  • 100spring-data-jpa
    Use when generating JPA entities, repositories, queries, or anything touching the persistence layer. Covers entity conventions, N+1 prevention, projections, and query patterns.
  • 100spring-testing-persistence
    Test the persistence layer of Spring Boot apps - Spring Data repositories, derived and custom queries, JPA mappings, database constraints, schema migrations and transactions - with Testcontainers and @ServiceConnection, @DataJpaTest/@DataJdbcTest/@JdbcTest, @Sql and…
  • 100spring-data-jpa
    Spring Data JPA entity design, repository patterns, query methods, JPQL, Flyway/Liquibase migrations, and N+1 avoidance. Apply on Spring Boot projects with spring-boot-starter-data-jpa. Pairs with spring-boot-plugin:spring-conventions and java-foundation:java-conventions. Use…
  • 85ai-persistence/build-prisma-adapter
    Use when an app already runs Prisma and needs TanStack AI chat persistence — writes a chat-persistence.ts into the app against its existing PrismaClient and schema.prisma. Covers the four models, BigInt timestamps, JSON-as-string columns, upsert-with-empty-update idempotency, and model renaming.
  • 100repository
    Define a Protean repository, the persistence abstraction for aggregates in Domain-Driven Design. Repositories provide a collection-oriented interface to load and persist aggregates, hiding database details behind a clean domain API. Protean provides a default repository…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.