java-persistence

Java Persistence (JPA / Panache / Spring Data)

Overview

Persistence is where Java services most often leak — lazy-loading exceptions, N+1 queries, entities serialized over HTTP, pagination applied in memory. Keep persistence at the repository boundary and mapped deliberately.

Core principle: Entities are a persistence detail. They never cross the HTTP boundary and they never carry business logic that belongs in the domain. Every list query is bounded AND the bound is honored by the SQL, not by Java code truncating a full result set.

Mapping surface

Rules

• Transaction boundary = the service method, never the repository or the resource. One use-case = one transaction.
• Never return entities from a controller/resource. Map to a DTO inside the service (or a JPA projection). Returning entities causes lazy-init serialization errors and leaks the schema.
• Fetch deliberately to avoid N+1. A loop that touches a lazy collection per row issues a query per row. Use a JOIN FETCH / entity graph / @BatchSize or hibernate.default_batch_fetch_size, and verify with a query-count assertion in a test.
• Never paginate a collection JOIN FETCH. Hibernate applies LIMIT/OFFSET in memory when the query also fetches a *-to-many collection (warning HHH90003004) — it loads the whole table to paginate it. Set hibernate.query.fail_on_pagination_over_collection_fetch=true in the test profile so this fails loudly instead of shipping slow. Page the root entity's ids first (plain query, no fetch join), then fetch the page by id with the collection join, or rely on @BatchSize/hibernate.default_batch_fetch_size instead of a fetch join at all.
• Bound every list query. Page (Page/Pageable, Panache .page(...)) — never findAll()/listAll() on a growing table. Default and maximum page size live with the endpoint (api-design-conventions), not just the repository call.
• Migrations own the schema, not hibernate.hbm2ddl=update/Quarkus generate-schema. Set validate/none in non-test envs; schema changes go through a migration (postgres-migrations), never auto-DDL in production.
• Optimistic locking (@Version) on entities with concurrent updates; map OptimisticLockException/ObjectOptimisticLockingFailureException to 409 in the central error mapper (api-design-conventions), never let it surface as 500.
• spring.jpa.open-in-view=false (Spring) — Open Session In View hides N+1s in the view layer and that lazy access outside a clear transaction boundary is exactly the mistake this skill exists to prevent.