spring-data-jpa

Spring Data JPA Implementation

Purpose

Use this skill when the task is specifically about persistence design or implementation in a Spring Boot codebase. This skill adds value through aggregate-root guidance, query-pattern selection, CQRS read-model decisions, and the bundled repository and relationship templates.

Critical rules

• Never create repositories for every entity. Create repositories only for aggregate roots.
• Never rely on long derived query method names when the query has become non-trivial.
• Never use save() blindly when entity state transitions matter; understand persist versus merge behavior.
• Prefer projections or dedicated query services for read-heavy paths.
• Keep transaction boundaries in the service layer unless the existing architecture intentionally does otherwise.

Workflow

Step 1: Identify the persistence problem

Collect the minimum context first:

1. Is the type an aggregate root or an internal entity?
2. Is the task primarily read-side, write-side, or both?
3. Is the query simple lookup, filtered search, aggregation, projection, or dynamic criteria?
4. Is the path performance-sensitive?
5. Are there module-boundary or loose-coupling constraints that affect relationship modeling?

Step 2: Choose the implementation pattern

Use this table to decide what to load next.

Pattern	Use when	Read
Simple repository	Basic CRUD and 1-2 simple lookups	Existing code or none
@Query repository	Multiple filters, joins, sorting, readable JPQL	references/query-patterns.md
DTO projection	Read-only and performance-critical responses	references/dto-projections.md
Custom repository	Criteria API, bulk operations, EntityManager logic	references/custom-repositories.md
CQRS query service	Separate read and write models, reporting, specialized read paths	references/cqrs-query-service.md

Use this decision guide:

Need	Simple	@Query	DTO	Custom	CQRS
Basic CRUD	Yes	Yes	No	Yes	Yes
Custom filters	No	Yes	Yes	Yes	Yes
Best read performance	No	Sometimes	Yes	Sometimes	Yes
Complex dynamic logic	No	No	No	Yes	Yes
Clear read/write split	No	No	Sometimes	Sometimes	Yes

Step 3: Load the matching reference

Load only the references needed for the current task:

• references/query-patterns.md
• references/dto-projections.md
• references/custom-repositories.md
• references/cqrs-query-service.md
• references/relationships.md
• references/performance-guide.md

Step 4: Apply the matching asset

Use the bundled templates in assets/ instead of rebuilding the pattern from scratch:

• assets/query-repository.java
• assets/dto-projection.java
• assets/custom-repository.java
• assets/query-service.java
• assets/relationship-patterns.java

Templates use the same placeholder convention as creating-springboot-projects — {{PACKAGE}}, {{MODULE}}, {{NAME}}, {{TABLE_NAME}}, {{TYPE}}, {{FIELD}}. See creating-springboot-projects/SKILL.md#placeholder-convention for the full table.

Step 5: Validate relationships and transaction boundaries

Before finalizing the change, check:

• repository exists only at the aggregate-root boundary
• lazy-loading behavior is intentional
• pagination or projections are used where row counts can grow
• @ManyToMany has not been introduced when a join entity is more appropriate
• read services use @Transactional(readOnly = true) where appropriate
• write operations stay in service-layer transactions

Step 6: Validate performance-sensitive paths

Read references/performance-guide.md when the task includes:

• N+1 risks
• fetch-plan problems
• unbounded queries
• batch operations
• heavy read views that should use projections

High-value patterns to prefer

Repository boundaries

• Aggregate roots get repositories.
• Internal child entities usually do not.

Query style

• Use derived query methods for simple lookups.
• Use @Query for joins, readable text blocks, or multiple filters.
• Use DTO projections when the response does not need entities.
• Use a CQRS query service when the read model differs from the write model.

Relationships

• Prefer @ManyToOne over @OneToMany when possible.
• Use IDs instead of entity references when loose coupling is more important than navigation.
• Treat @ManyToMany as a warning sign; prefer an explicit join entity.

Output format

When proposing or implementing a persistence change, return:

## Recommended pattern
- Pattern:
- Why:

## Files to change
- `path/to/file`

## References used
- `references/...`

## Risks to verify
- ...

When not to use this skill

• Generic SQL or database administration work outside Spring Data JPA
• Whole-project migration planning
• Broad project scaffolding that belongs in creating-springboot-projects