AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

java-hibernate-jpa

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.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--java-hibernate-jpa at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/identifiers-and-entity-design.md

Identifiers and entity design

Identifier generation

| Strategy | Batch inserts | Notes | | --- | --- | --- | | SEQUENCE | Yes | Best default on PostgreSQL, Oracle, SQL Server, MariaDB, H2, Db2. | | IDENTITY | No (Hibernate must execute each insert to get the id) | Use when the DB has no sequences (older MySQL); accept slower bulk inserts. | | TABLE | Yes but contended | Avoid. | | AUTO | Depends on dialect | Hibernate 6+ picks a sequence when the dialect supports it; be explicit. | | UUID | Yes | Client-generated; no round-trip. |

Sequence with pooled optimizer

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "order_seq")
@SequenceGenerator(name = "order_seq", sequenceName = "order_seq", allocationSize = 50)
private Long id;
  • allocationSize (default 50) must equal the sequence's INCREMENT BY in the database. A mismatch causes duplicate-key errors or wasteful gaps. Hibernate uses a pooled optimizer by default: one sequence call reserves allocationSize ids.
  • Other applications or SQL scripts inserting rows must use the same increment, or draw ids from the sequence in a compatible way.
  • Create the sequence in the migration (CREATE SEQUENCE order_seq START WITH 1 INCREMENT BY 50).

UUID

@Id
@GeneratedValue(strategy = GenerationType.UUID)   // Jakarta Persistence 3.1+
private UUID id;

Random v4 UUIDs fragment B-tree indexes on large tables; prefer time-ordered ids (UUIDv7) generated by the application or Hibernate's @UuidGenerator(style = UuidGenerator.Style.TIME) (Hibernate 6.x; check the docs of your version for the v7 option). Store as native uuid columns, not varchar(36).

Anti-patterns

  • IDENTITY on a table you bulk-load.
  • Natural keys that change; use a surrogate id plus a unique constraint, or @NaturalId.
  • @GenericGenerator (Hibernate-specific, deprecated in 6.5+): use @SequenceGenerator, @UuidGenerator, or the newer id generator annotations documented for your version.

equals and hashCode

Problems: the id is null until persist; default identity equality breaks Set semantics across detached/merged instances; Hibernate proxies are subclasses, so getClass() comparisons fail.

Option A (generated id, recommended pattern):

@Override
public final boolean equals(Object o) {
    if (this == o) return true;
    if (o == null) return false;
    Class<?> oClass = o instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getPersistentClass() : o.getClass();
    Class<?> thisClass = this instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getPersistentClass() : getClass();
    if (thisClass != oClass) return false;                  // proxy-safe, symmetric
    Book other = (Book) o;
    Object thisId = this instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getInternalIdentifier() : getId();
    Object otherId = other instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getInternalIdentifier() : other.getId();
    return thisId != null && thisId.equals(otherId);
}

@Override
public final int hashCode() {
    return this instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getPersistentClass().hashCode()
            : getClass().hashCode();   // constant per persistent class; stable before/after persist
}

Keep both methods final so Hibernate does not intercept them and initialize the proxy before the method body runs. Use getInternalIdentifier() for proxies: unlike getIdentifier() or an intercepted getId(), it does not initialize them even with JPA proxy compliance enabled. This is a Hibernate-specific pattern, not a provider-portable JPA recipe.

Constant hashCode is fine for entity sets of modest size (hundreds); large in-memory sets of entities are a design smell anyway. getClass() on a proxy returns the generated subclass, so both methods resolve the persistent class first (Hibernate.getClass(x) does the same but initializes the proxy). The class comparison keeps equals symmetric and consistent with hashCode; for entity hierarchies where a subclass should equal its parent type, compare against the root entity class instead.

Validate with two distinct transient books (not equal), the same book before/after persist (hash unchanged), and an uninitialized em.getReference(Book.class, id) after closing its entity manager. Adding that detached proxy to a HashSet, comparing it to a detached book with the same id in both directions, and calling contains must not throw or initialize the proxy. Also check zero additional SQL while the proxy is still attached, including with hibernate.jpa.compliance.proxy=true.

Option B (business/natural key): compare an immutable, unique attribute (ISBN, email), using getters. Implement hashCode on the same field. Mark it @NaturalId. Never use mutable fields.

Option C (client-assigned UUID id): compare/hash the UUID; it exists from construction.

Never include associations or lazy collections in equals/hashCode/toString.

Lombok on entities

  • Do not use @Data, @EqualsAndHashCode, @ToString (default) on entities: they touch lazy collections (triggering loads or LazyInitializationException), cause infinite recursion in bidirectional associations, and make hashCode change after persist.
  • Use @Getter/@Setter selectively (setters on collections and ids usually should not exist), and @ToString(onlyExplicitlyIncluded = true) with basic fields only.
  • @Builder and @AllArgsConstructor bypass invariants and require a protected no-arg constructor (@NoArgsConstructor(access = AccessLevel.PROTECTED)); initialize collections with @Builder.Default.
  • Entities must be non-final with a non-private no-arg constructor (Hibernate proxies); do not make fields final.

Records vs entities

  • Java records cannot be entities: entities need a no-arg constructor, mutability, and non-final classes. (Hibernate 6+ does support records as @Embeddable components and as projection/DTO types.)
  • Use records for DTOs, projections, and embeddables; keep entities as classes.

Enums and converters

  • @Enumerated(EnumType.STRING) (readable, resilient to reordering). ORDINAL breaks when constants are reordered or inserted.
  • Add a DB check constraint or a native/PostgreSQL enum mapping if invalid values must be rejected at storage level.
  • Custom types: AttributeConverter<X, Y> with @Converter(autoApply = false) and @Convert on the attribute. Converters must be stateless and null-safe, and are not applied to ids or in some JPQL comparisons; test queries that compare converted attributes.
  • Prefer java.time types over java.util.Date; Instant/OffsetDateTime with UTC (hibernate.jdbc.time_zone=UTC).
  • BigDecimal columns: set precision and scale.

Other design points

  • Embedded value objects with @Embeddable instead of loose columns.
  • Use @Version for optimistic locking on aggregate roots (locking-transactions-caching.md).
  • Mark read-only reference entities @Immutable.
  • @ElementCollection for small value sets only; large or queried collections deserve their own entity.
  • Prefer Long/UUID wrapper ids (null means transient).