Java Hibernate Jpa

GitHubOfficialFirst committed by jduboisDistributed by GitHub

Skill
Guidelines
Software development
MIT
No issues found

From the author

Diagnose and fix Hibernate ORM / Jakarta Persistence problems in plain Java: N+1 queries, lazy loading errors, identifier generation, entity equals/hashCode, cascades, pagination, batching, locking, caching, Lombok on entities, and Hibernate 6/7 differences. Use when reviewing or writing JPA entities, mappings, and queries. Framework-neutral.

— the description by jdubois

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to identifying and fixing common Hibernate ORM and Jakarta Persistence (JPA) issues. It covers entity mapping, association management, query optimization, and transaction handling. The content is framework-neutral, focusing on the behavior of the EntityManager, Session, JPQL/HQL, and mapping annotations across different Hibernate versions.

What it does

Detects N+1 query problems and provides optimization strategies like JOIN FETCH and batch fetching.
Provides rules for entity design, including identifier generation and equals/hashCode implementation.
Explains how to manage associations, cascades, and orphan removal to prevent data anomalies.
Offers guidance on schema management and versioned migrations.
Helps resolve LazyInitializationException and other common persistence errors.
Details differences between Hibernate versions and Jakarta Persistence specifications.

When to use it

When debugging performance issues related to database queries.
During code reviews of JPA entities and persistence logic.
When configuring Hibernate for new projects or upgrading between versions.
When encountering unexpected behavior in entity state management or transaction boundaries.

Advantages

Provides a clear decision table for common persistence symptoms.
Offers specific, actionable rules for mapping and association management.
Includes guidance on testing strategies to verify statement counts and behavior.
Maintains a framework-neutral perspective applicable to various Java environments.

Usage examples

“How do I fix an N+1 query issue in my Hibernate application?”: The agent will explain how to detect the issue using SQL logging and provide solutions such as JOIN FETCH, entity graphs, or batch fetching.
“What are the best practices for implementing equals and hashCode in JPA entities?”: The agent will provide rules for stable equality, warning against using generated IDs in hashCode and advising on Lombok usage with associations.
“How should I handle schema management in production with Hibernate?”: The agent will recommend using versioned migration tools like Flyway or Liquibase and setting hibernate.hbm2ddl.auto to validate or none.
“Why am I getting a LazyInitializationException?”: The agent will explain that the session has closed before the lazy association was accessed and suggest loading the required data within the transaction boundary.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/github/java-hibernate-jpa/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip java-hibernate-jpa.zip -d .agents/skills

Documentation by jdubois

Hibernate ORM and Jakarta Persistence

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.

First: detect the stack

Read 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).
Note the Hibernate major version; behavior differs (see 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+.
Note the database and whether the schema is managed by Flyway/Liquibase.
Turn on SQL logging and statistics in a test (see references/tooling-and-versions.md) before "optimizing" anything: measure statement counts.

Quick decision table

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`

Top rules (apply during review)

Associations: @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.
Prefer @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.
Never use CascadeType.REMOVE/ALL on @ManyToOne or @ManyToMany. Use orphanRemoval only on a true parent-owned child collection.
Ids: 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.
Entities: no Lombok @Data/@EqualsAndHashCode/@ToString over associations; implement equals/hashCode deliberately.
Return DTOs/projections from read endpoints rather than entities; never expose entities (lazy proxies) directly in an API.
Paginate with a stable ORDER BY including a unique tiebreaker; never combine setMaxResults with a collection JOIN FETCH.
Keep transactions short, at the service boundary; no remote calls or user interaction inside one.
Write and flush in batches for bulk work and clear the persistence context periodically.
Verify behavior with statement counts in tests against the real database engine.
Follow the schema management rule below.

Schema management rule

This is the single rule other skills refer to by name:

Prototype/local: hibernate.hbm2ddl.auto=update (or create-drop for throwaway tests) is acceptable.
Production (default): versioned migrations with Flyway or Liquibase, and hibernate.hbm2ddl.auto=validate (or none). Add them when the user wants versioned migrations or the app is headed to production.
Externally managed schema: none (or validate); do not add a migration tool.

Review focus

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

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 https://docs.hibernate.org/orm/current/userguide/html_single/ and Jakarta Persistence https://jakarta.ee/specifications/persistence/. Deep background articles: https://vladmihalcea.com/.

Upgrading (fetch the page for the target version; prefer it over this skill): migration guides https://hibernate.org/orm/documentation/migrate/ (6.6: https://docs.hibernate.org/orm/6.6/migration-guide/, 7.0: https://docs.hibernate.org/orm/7.0/migration-guide/), release notes https://hibernate.org/orm/releases/.

Files

ATTRIBUTION.mdAdded by AutoGineer867 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md6.5 KiB
references/associations-and-cascade.md4.4 KiB
references/fetching-and-n-plus-one.md5.8 KiB
references/identifiers-and-entity-design.md7.1 KiB
references/locking-transactions-caching.md5.7 KiB
references/queries-pagination-batching.md6.8 KiB
references/tooling-and-versions.md6.1 KiB

references/associations-and-cascade.md

Associations, cascade, collections

Bidirectional associations with helpers

The owning side holds the foreign key (@ManyToOne). The inverse side uses mappedBy. Keep both sides in sync in the domain model, otherwise the in-memory graph and the database diverge.

@Entity
class Order {
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderLine> lines = new ArrayList<>();

    public void addLine(OrderLine line) {
        lines.add(line);
        line.setOrder(this);
    }

    public void removeLine(OrderLine line) {
        lines.remove(line);
        line.setOrder(null);
    }

    public List<OrderLine> getLines() {
        return Collections.unmodifiableList(lines);
    }
}

@Entity
class OrderLine {
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id")
    private Order order;
}

Rules:

Only the @ManyToOne side writes the FK; changing only the inverse collection does nothing to the database.
Expose the collection read-only (or defensively copied); initialize it once and never replace the reference (order.setLines(new ArrayList<>()) breaks orphan removal and confuses Hibernate's collection tracking: mutate with clear()/add()).
Prefer unidirectional @ManyToOne and query the many side when you never navigate parent -> children.

Unidirectional @OneToMany anti-pattern

A @OneToMany without mappedBy and without @JoinColumn creates a join table and extra SQL. With @JoinColumn it issues an INSERT then an UPDATE for the FK. Make the relationship bidirectional (or @ManyToOne only).

Cascade pitfalls

Pitfall	Fix
`CascadeType.ALL`/`REMOVE` on `@ManyToOne` or `@ManyToMany`: deleting one child deletes the shared parent or related rows	Cascade only parent -> owned child.
`CascadeType.REMOVE` for a large collection loads and deletes row by row	Flush pending changes, execute a bulk `DELETE ... WHERE parent_id = :id`, then clear the context; alternatively use DB `ON DELETE CASCADE` with `@OnDelete(action = OnDeleteAction.CASCADE)`.
`CascadeType.PERSIST` on a detached child: `PersistentObjectException: detached entity passed to persist`	Use `merge` (or load the entity first); do not set a detached instance on a persist-cascaded association.
`CascadeType.MERGE` overwrites state with stale DTO data	Copy only allowed fields onto a managed entity.
`orphanRemoval = true` on a shared child	Only for exclusive, parent-owned children; removing from the collection deletes the row.
Replacing a collection with `setX(newList)` on an `orphanRemoval` mapping	`A collection with cascade="all-delete-orphan" was no longer referenced`; mutate in place.

orphanRemoval also implies removal when the parent is removed.

Collection type choice

@ManyToMany: use Set. With a List (a bag), removing one element deletes all join-table rows and re-inserts the rest.
Avoid @ManyToMany for anything beyond a plain link; model the join as an entity (with @ManyToOne on both sides) as soon as it has attributes or you query it.
@OneToMany List with @OrderColumn rewrites index columns on removal from the head; use @OrderBy for read-time ordering instead.
Collections with possibly thousands of rows should not be mapped at all; query them with pagination.
Never call collection.size() or contains() on a large lazy collection to count/check; run a count/exists query (@LazyCollection(EXTRA) is deprecated).

Equality in collections

Set semantics rely on equals/hashCode (see identifiers-and-entity-design.md). A HashSet of entities whose hashCode depends on the generated id will lose elements after persist.

One-to-one

Prefer a shared primary key (@MapsId) for a true one-to-one: no extra index, lazy-loadable from the owning side, and one-query find. Without it, the inverse side (mappedBy) is usually loaded eagerly, because Hibernate must query to know whether it is null; it can be a lazy proxy only when optional = false guarantees the row exists, or with bytecode enhancement.

Delete and update patterns

Removing a parent with children: either cascade REMOVE (small, owned collections), DB-level cascade, or explicit bulk delete in order (children first).
Bulk JPQL/HQL update/delete bypass the persistence context and version columns; flush before, and clear() afterwards or refresh entities.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs network access

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by

jdubois

Publisher

GitHub (Official)

Distributed by

GitHub

Source

github/awesome-copilot · skills/java-hibernate-jpa · commit 797337f

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Contributors