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. 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. ## Mapping surface | Concern | Quarkus (Panache) | Spring Data | |---------|-------------------|-------------| | Entity | `@Entity` + `PanacheEntityBase` or plain `@Entity` | `@Entity` | | Repository | `implements PanacheRepository<Task>` | `extends JpaRepository<Task, UUID>` | | Query | `find("status", s)` / HQL | derived methods / `@Query` | | Transaction | `@Transactional` on the service | `@Transactional` on the service | ## 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`, and verify with SQL logging in a test. - **Bound every list query.** Page (`Page`/`Pageable`, Panache `page(...)`) — never `findAll()` on a growing table. - **Migrations own the sc...