Problem -> anti-pattern -> fix library for entity mapping and querying. Framework-neutral: it covers EntityManager/Session behavior, JPQL/HQL, and mapping annotations. If the project uses Spring Boot and the java-springboot and spring-boot-testing skills are installed, use them for Spring Data repositories, transaction wiring, and @DataJpaTest; for Panache and reactive persistence see the Quarkus skills. Integration tests against a real database: java-testcontainers.
pom.xml/build.gradle (or the dependency tree) for hibernate-core and the persistence API: jakarta.persistence (Hibernate 6+/Jakarta EE 9+) vs javax.persistence (Hibernate 5, see javax-to-jakarta-migration).references/tooling-and-versions.md). Hibernate 6.0-6.1 implement Jakarta Persistence 3.0, 6.2+ implement 3.1, 7.x implements 3.2, and Hibernate 7 needs Java 17+.references/tooling-and-versions.md) before "optimizing" anything: measure statement counts.| Symptom | Likely cause | Go to |
|---|---|---|
| Many similar SELECTs for one request | N+1 on lazy association | references/fetching-and-n-plus-one.md |
LazyInitializationException | Lazy access outside session | references/fetching-and-n-plus-one.md |
HHH000104 / HHH90003004 warning, big memory use | Pagination with collection fetch join | references/queries-pagination-batching.md |
| Inserts slow, no JDBC batching | IDENTITY ids or batching not configured | references/identifiers-and-entity-design.md, references/queries-pagination-batching.md |
Duplicate rows / lost children / Set anomalies | Bad equals/hashCode or cascade misuse | references/identifiers-and-entity-design.md, references/associations-and-cascade.md |
| Lost updates, deadlocks | Missing locking strategy | references/locking-transactions-caching.md |
| Stale or surprising data with caches | Second-level/query cache misuse | references/locking-transactions-caching.md |
Schema drift, ddl-auto in prod | No migration tool | references/tooling-and-versions.md |
@ManyToOne/@OneToOne default to EAGER; declare fetch = FetchType.LAZY explicitly. @OneToMany/@ManyToMany are LAZY by default and should stay so. Choose fetching per query (JOIN FETCH, entity graph), not by making mappings EAGER.@ManyToOne owning side plus a bidirectional @OneToMany(mappedBy=...) only when needed; keep both sides in sync through helper methods.Set or List for collections? Use Set for @ManyToMany; a unidirectional @OneToMany with @JoinColumn or List without an order has costly update patterns.CascadeType.REMOVE/ALL on @ManyToOne or @ManyToMany. Use orphanRemoval only on a true parent-owned child collection.SEQUENCE (pooled optimizer, allocationSize matching the DB increment) for generated numeric ids; IDENTITY disables JDBC insert batching; use UUIDs (time-ordered preferred) when ids must be generated client-side.@Data/@EqualsAndHashCode/@ToString over associations; implement equals/hashCode deliberately.ORDER BY including a unique tiebreaker; never combine setMaxResults with a collection JOIN FETCH.This is the single rule other skills refer to by name:
hibernate.hbm2ddl.auto=update (or create-drop for throwaway tests) is acceptable.hibernate.hbm2ddl.auto=validate (or none). Add them when the user wants versioned migrations or the app is headed to production.none (or validate); do not add a migration tool.Check statement counts for N+1, explicit LAZY on to-one associations, sequence-based ids with matching allocationSize, and equals/hashCode stable across transient to persistent. Version-dependent details (Hibernate 5/6/7): references/tooling-and-versions.md.
references/fetching-and-n-plus-one.md: N+1 detection and fixes, lazy vs eager, LazyInitializationException, open-session-in-view, DTO projections.references/identifiers-and-entity-design.md: id generation, equals/hashCode, Lombok, records vs entities, enums and converters, value types.references/associations-and-cascade.md: bidirectional helpers, cascade, orphanRemoval, collection choice, @ManyToMany.references/queries-pagination-batching.md: pagination (offset, keyset, in-memory warning), bulk operations, JDBC batching, StatelessSession.references/locking-transactions-caching.md: optimistic/pessimistic locking, transaction boundaries, flush modes, second-level cache.references/tooling-and-versions.md: SQL logging, statistics, tests, connection pool sizing, migrations, Hibernate 5/6/7 differences.Canonical docs: Hibernate ORM user guide
Upgrading (fetch the page for the target version; prefer it over this skill): migration guides