| name | persistence-jpa |
| description | Use this skill when working with JPA entities, repositories, and persistence logic in a Spring Boot project. Combines domain-driven persistence design with Java correctness, performance awareness, and testability. |
Persistence & JPA
Scope
Apply this skill when working on:
- JPA entities
- Spring Data repositories
- persistence-related service logic
- database mappings and relationships
- transaction boundaries
Persistence architecture
- Keep persistence concerns in entities and repositories.
- Keep business logic in services, not repositories.
- Do not expose JPA entities directly via REST APIs.
- Use DTOs for API boundaries.
- Keep repository interfaces focused on data access.
Entity design
- Model entities clearly and align them with domain concepts.
- Define explicit constraints: nullability, length, uniqueness.
- Prefer simple relationships unless complexity is required.
- Avoid mixing persistence logic with transport concerns.
- Avoid large, bloated entities.
Identifier and mapping rules
- Use a clear primary key strategy.
- Prefer explicit column and table mappings where clarity is needed.
- Align entity structure with actual database constraints.
- Be explicit about timestamps and auditing fields.
Repository rules
- Use Spring Data JPA repositories for standard operations.
- Prefer derived query methods before custom queries.
- Avoid placing business logic inside repositories.
- Keep queries readable and intention-revealing.
Transaction boundaries
- Define transactions at the service layer.
- Keep write operations explicit and controlled.
- Avoid spreading persistence logic across multiple layers.
Null safety in persistence
- Avoid returning null collections; return empty collections.
- Use Optional for nullable entity lookups.
- Validate inputs before persistence operations.
- Be explicit about nullable fields in entities.
Exception handling
- Use domain-specific exceptions (e.g., NotFound, Conflict).
- Do not swallow persistence exceptions.
- Preserve root cause when rethrowing exceptions.
- Avoid leaking internal database details in API responses.
Collections and relationships
- Do not modify collections while iterating.
- Be careful with bidirectional relationships (avoid infinite recursion).
- Avoid unnecessary eager loading.
- Prefer lazy loading with clear boundaries.
Performance awareness (JPA-specific)
- Avoid N+1 query problems.
- Use fetch joins or entity graphs where necessary.
- Avoid loading large collections unnecessarily.
- Prefer pagination for large result sets.
- Avoid inefficient loops over database results.
General Java performance awareness
- Avoid string concatenation in loops.
- Avoid repeated expensive operations (e.g., regex, conversions).
- Be cautious with streams in hot paths.
- Optimize only after measuring.
Concurrency awareness
- Avoid shared mutable state in persistence logic.
- Be careful with concurrent updates (consider locking strategies).
- Keep transactions short and predictable.
Schema change awareness
- When modifying entities, clearly indicate required schema changes.
- Align entity changes with migration strategy (e.g., Flyway).
- Do not assume schema updates happen automatically.
PostgreSQL awareness
- Assume PostgreSQL as the target database.
- Avoid H2-specific shortcuts.
- Align mappings with real production behavior.
Testability
- Keep persistence logic testable via repository and integration tests.
- Avoid tight coupling between persistence and business logic.
- Prefer clear, deterministic behavior for easier testing.
Output expectations
When generating persistence-related code:
- include entity + repository where relevant
- keep DTO boundaries separate
- ensure PostgreSQL-friendly mappings
- highlight potential performance issues (e.g., N+1)
- mention schema implications when applicable
- follow clean code and maintainability principles
