Persistence Jpa

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