Hibernate / JPA

JPA (Jakarta Persistence API) is a specification — interfaces, annotations, and contracts defined by the Jakarta EE standard. It covers entity mapping, JPQL, the EntityManager lifecycle, and transaction handling. Hibernate is the most widely used JPA implementation. It provides the actual SQL generation, caching, lazy loading proxies, dirty checking, and session management behind those interfaces. The distinction matters because: - Portability: code written against JPA interfaces can theoretically switch providers (EclipseLink, DataNucleus), though this rarely happens in practice. - Extensions: Hibernate adds features beyond the spec — HQL, @BatchSize, Envers, spatial types. Using them creates Hibernate lock-in. - Spring Data JPA sits above JPA, generating repository implementations from method names. It delegates to Hibernate but abstracts the EntityManager.

Best practice: code to JPA interfaces; use Hibernate extensions only when JPA cannot express what you need.

Transient: object created with new, unknown to Hibernate, no DB row. Garbage collected when dereferenced. Persistent (Managed): associated with an open Session. Hibernate tracks all changes via dirty checking and flushes them to the DB on commit or explicit flush(). LAZY association access works here. Detached: the Session was closed or evict() was called. The entity has a DB row but is no longer tracked. Accessing LAZY associations throws LazyInitializationException. Re-attach via merge() (copies state onto a new persistent instance) or Hibernate's update() (reattaches the exact object). Removed: remove() called on a persistent entity. The DB row will be deleted at flush/commit. Key implication: dirty checking only works on persistent entities. Modifications to detached entities are silently lost unless explicitly merged back.

The problem: loading N parent entities and then accessing a LAZY collection per entity fires 1 initial query + N subsequent queries: java List<Order> orders = repo.findAll(); // 1 query orders.forEach(o -> notify(o.getLineItems())); // N queries Detection: enable spring.jpa.properties.hibernate.generate_statistics=true and check StatisticsImpl.getQueryExecutionCount() per request. Or use datasource-proxy / p6spy to count raw JDBC calls. Fix strategies: - JOIN FETCH (per-query): SELECT o FROM Order o JOIN FETCH o.lineItems — one query. Watch for Cartesian products when joining multiple collections. - @BatchSize(size=25) on the collection: when any proxy is accessed, Hibernate fetches up to 25 others with an IN clause — reduces to ceil(N/25)+1 queries. - @EntityGraph: per-repository override of fetch plan without altering defaults. - DTO projections: SELECT new OrderDTO(o.id, o.total) FROM Order o — don't load the entity graph at all.

Never "fix" N+1 by changing the fetch type to EAGER globally — that trades N+1 in some queries for over-fetching in all queries.

Defaults: - @ManyToOne → EAGER - @OneToOne → EAGER - @OneToMany → LAZY - @ManyToMany → LAZY @ManyToOne defaulting to EAGER means: every time you load an entity with a @ManyToOne field, Hibernate JOINs the associated table — even if you never use that association in the current use case. With a chain of EAGER associations (Order → Customer → Address → Country), a simple order load becomes a 4-table JOIN. Best practice: explicitly set everything to LAZY and use JOIN FETCH / @EntityGraph per query to load only what that specific query needs: java @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "customer_id") private Customer customer; This makes the data access explicit and prevents silent performance regressions as the entity graph grows.

At Session open, Hibernate snapshots the state of each managed entity. At flush time (before commit, or on explicit flush()), it compares current field values against the snapshot. Any changed field generates a SQL UPDATE for that entity's row. This is automatic — you don't call save(): java @Transactional public void changeEmail(Long id, String email) { User user = em.find(User.class, id); user.setEmail(email); // automatically flushed at commit } Trap: setting a field inside a transaction for a local purpose accidentally persists it. Always be intentional about modifications inside @Transactional methods. Performance: dirty checking compares every field of every managed entity at flush time. For bulk processing loading thousands of entities this is expensive. Solutions: use @Transactional(readOnly=true) (Hibernate skips dirty checking), call em.clear() periodically in batch loops, or use StatelessSession for bulk operations.

The first-level cache is an identity map scoped to the current Session. Within one Session, loading the same entity by PK returns the exact same Java object instance — no duplicate SELECT is fired: java User a = em.find(User.class, 1L); User b = em.find(User.class, 1L); assert a == b; // true — only one SELECT It is always on and cannot be disabled. This guarantees object identity consistency within a transaction. Problem in batch processing: loading tens of thousands of entities in a loop accumulates them all in the L1 cache, causing memory pressure and eventually OOM. Fix: call em.flush(); em.clear() every N iterations to release the cache while still committing work. The L1 cache is not shared between Sessions. Cross-Session caching requires the optional second-level (L2) cache.

Thrown when a LAZY-loaded proxy is accessed after the Hibernate Session that created it has been closed. The proxy cannot issue the SELECT needed to initialise itself. Common causes: - REST controller returning a detached entity — Jackson serialisation accesses LAZY fields outside the @Transactional service method boundary - @Async thread receiving an entity passed from the parent request thread - OSIV disabled but service returns entities instead of DTOs Prevention (pick the appropriate one): 1. DTOs / projections: map entities to records inside the transaction — no proxies cross the boundary 2. JOIN FETCH: load all associations you'll need within the active transaction scope 3. Hibernate.initialize(entity.getCollection()): explicit initialisation before the Session closes (use sparingly) 4. @Transactional boundary: ensure all lazy access happens within the transaction Do NOT enable OSIV to suppress this error — it hides the symptom while causing N+1 queries at scale.

Configured via @Inheritance(strategy = InheritanceType.XXX) on the root entity. SINGLE_TABLE (default): all subclasses share one table with a discriminator column. Pros: simplest queries, no JOINs, best read performance. Cons: all subclass-specific columns are nullable; cannot enforce NOT NULL constraints on subtype fields; poor third normal form. JOINED: parent class in one table; each subclass in its own table linked by PK/FK. Pros: fully normalised, enforces constraints per subtype, clean schema. Cons: polymorphic queries JOIN across all subtype tables. TABLE_PER_CLASS: each concrete class gets its own complete table. Pros: no JOINs for single concrete-type queries. Cons: polymorphic queries require UNION — unindexable and slow. Generally avoid. Decision guide: - Few subtypes with many shared fields, few unique fields → SINGLE_TABLE - Many distinct fields per subtype, data integrity matters → JOINED - Polymorphic queries across all subtypes are never needed → could use TABLE_PER_CLASS, but JOINED is usually safer

@Version on a Long or Timestamp field enables optimistic locking: java @Entity public class Product { @Version private Long version; private int stock; } Hibernate adds AND version = ? to every UPDATE: sql UPDATE product SET stock = ?, version = 2 WHERE id = ? AND version = 1 If another transaction committed in between, 0 rows are updated → Hibernate throws OptimisticLockException. The caller should catch and retry the operation, or surface a 409 Conflict to the client. Choose optimistic when: low-to-moderate write contention, reads heavily outnumber writes, and retry cost is acceptable. Choose pessimistic (LockModeType.PESSIMISTIC_WRITE → SELECT ... FOR UPDATE) when: high write contention makes retries impractical (inventory, seat booking, financial balances), or when you cannot tolerate even momentary inconsistency. Pessimistic locking serialises access at the DB level — correct, but reduces throughput and risks deadlocks if not applied consistently across all code paths.

Both reattach a detached entity, but differ in semantics: EntityManager.merge(detached) (JPA-standard): - Loads the persistent copy from the Session L1 cache or DB - Copies the detached entity's state onto the persistent instance - Returns the managed instance — the original argument remains detached - Safe when another transaction may have modified the entity since detachment Session.update(detached) (Hibernate-specific): - Reattaches the exact same object instance to the Session - Throws NonUniqueObjectException if a different instance with the same ID already exists in the Session - Does not check for concurrent modifications Always prefer merge() for JPA code — it's portable and safe by default. Use update() only when you need Hibernate-specific semantics and fully control the Session state (rare).

Detection pipeline: 1. Hibernate Statistics (hibernate.generate_statistics=true): exposes QueryExecutionCount, EntityLoadCount, CollectionFetchCount per SessionFactory. Wire into a Spring HandlerInterceptor to log counts per HTTP request.

1. datasource-proxy / p6spy: intercepts JDBC at the DataSource level. Gives exact SQL and counts regardless of ORM. Assert in integration tests: java assertThat(QueryCountHolder.getGrandTotal().getSelect()).isLessThanOrEqualTo(3);

2. APM agents (Datadog, Dynatrace): trace JDBC spans per transaction in production. Set an alert when any endpoint exceeds, e.g., 10 queries per request.

Fix hierarchy (apply in order): 1. JOIN FETCH in the repository query for the specific endpoint 2. @EntityGraph for per-method overrides without modifying entity defaults 3. @BatchSize(size=25) for collections too large to JOIN (Cartesian product risk) 4. DTO projections for read-only endpoints — bypass entity hydration entirely 5. spring.jpa.properties.hibernate.default_batch_fetch_size=25 as a safety net Prevention: add query-count assertions to every integration test for collection-loading endpoints. Gate new collection endpoints with a fetch strategy checklist in PR reviews.

Choose jOOQ when: - Complex reporting queries with aggregations, window functions, CTEs — JPQL can't express them and native queries in JPA lose type safety and IDE support. - You want compile-time SQL validation against the real schema. - The query logic is complex enough that "what SQL will this generate?" should be obvious from the code, not a debugging exercise.

Choose Spring Data JDBC when: - The aggregate is narrow (1–3 tables) with a clear DDD boundary. - You want predictable, explicit SQL: save() always issues an INSERT or UPDATE, no dirty checking, no proxy, no Session lifecycle surprises. - A team new to JPA wants data access without Hibernate's footguns. In practice, mix them within one application: Hibernate for the domain write path and rich object graphs; jOOQ or JDBC for reporting endpoints, analytics, or bulk export jobs. They share the same DataSource and @Transactional infrastructure. The decisive question: does the Unit of Work / entity graph model add value here, or does it add accidental complexity?

How it works: - Scoped to the SessionFactory — shared across all Sessions in the same JVM. - Annotate entities with @Cache(usage = CacheConcurrencyStrategy.READ_WRITE) and configure a provider (EhCache, Caffeine via JCache, Hazelcast). - Hibernate checks L2 before querying the DB for em.find() calls. - L2 entries are evicted automatically when Hibernate executes an UPDATE or DELETE through its own Session.

Multi-node risks: - Stale data: direct JDBC updates, another service writing to the same table, or DB migrations bypass Hibernate's eviction. The L2 cache serves stale data. - Per-node isolation: without a distributed cache, each node has its own L2 region. Writes on Node A are invisible to Node B's cache — inconsistent reads. - Fix: use a distributed provider (Hazelcast cluster, Redis via Redisson) so invalidation propagates cluster-wide. - Memory pressure: caching large or frequently updated entities wastes heap and increases GC pause times.

Safe L2 candidates: slowly changing reference data — product categories, country codes, configuration values. Avoid caching inventory levels, user sessions, or anything requiring tight consistency.

Hibernate's default Session is not designed for batch workloads — dirty checking and L1 cache accumulate all loaded entities in memory. Strategy by use case: Bulk UPDATE/DELETE without loading entities (fastest): java em.createQuery("UPDATE Product p SET p.price = p.price * 1.1 WHERE p.category = :c") .setParameter("c", "electronics").executeUpdate(); Bypasses L1/L2 and lifecycle callbacks. Manually evict L2 regions if needed. Processing entities in chunks (flush-and-clear): java for (int i = 0; i < entities.size(); i++) { process(entities.get(i)); if (i % 50 == 0) { em.flush(); em.clear(); } } Prevents L1 cache bloat. Enable JDBC batching (hibernate.jdbc.batch_size=50) to group the resulting INSERTs/UPDATEs into batch round-trips. Hibernate StatelessSession: no L1 cache, no dirty checking, no lazy loading proxy — pure CRUD. Ideal for high-volume imports where you don't need lifecycle hooks. Spring Batch: for production-grade jobs, use JpaPagingItemReader / JdbcCursorItemReader with chunk-oriented processing. Provides restartability, skip/retry policies, and partitioned parallel execution — critical for large datasets.

The decision turns on five factors evaluated per service, not once for the whole system: 1. Domain complexity: a rich object graph with deep relationships and lifecycle rules (orders → line items → inventory → fulfilment) justifies Hibernate's entity model. A service with two tables and a few foreign keys does not. 2. Write vs read ratio: Hibernate excels on the write path. For read-heavy reporting or analytics endpoints, jOOQ or raw SQL projections are faster, more expressive, and easier to reason about. 3. Team capability: Hibernate's footguns (N+1, OSIV, detached state, cache invalidation) require sustained discipline. A team without JPA expertise will consistently hit them in production. A simpler tool may be safer. 4. Schema ownership: if the service owns its schema end-to-end, full ORM is reasonable. If it must write to a legacy schema with stored procedures or unusual column types, jOOQ or MyBatis preserves full SQL control. 5. Service boundary width: microservices owning one or two aggregates get little value from Hibernate. Spring Data JDBC or JDBC templates are faster to start, easier to test, and have lower cognitive overhead. Pattern that works at scale: Hibernate for the domain write path, CQRS projections or jOOQ for the read path, and JDBC for batch exports. The mistake is applying one tool uniformly across all use cases.

Single-node L2 cache (EhCache in local heap) fails in multi-instance deployments: each node has an independent cache region. A write on Node A invalidates A's cache but not B's — inconsistent reads across the cluster. Architectural options: 1. Distributed L2 cache: configure Hibernate's JCache SPI with a distributed provider — Hazelcast (native Hibernate 6 integration) or Redis via Redisson. Writes propagate invalidation messages to all nodes. Tradeoff: network latency per cache read vs DB hit savings. Works well for reference data with high read/write ratios. 2. Read model separation (CQRS): project write-side entity changes into a dedicated read store (Redis, Elasticsearch, materialised views) via domain events. The read side is purpose-built for query patterns, has no entity lifecycle issues, and scales independently of the write store. 3. Service-layer cache (@Cacheable): explicitly manage a Redis or Caffeine cache for coarse entities using Spring Cache abstraction. Evict via @CacheEvict on write operations. Simpler to reason about than Hibernate L2 but requires manual coordination. 4. What NOT to cache: high-write or tightly consistent data — inventory, financial balances, user sessions. Invalidation complexity outweighs the read savings; tight DB indexes serve these better. Operational concern: cold cache after a rolling deploy triggers a thundering herd. Mitigate with lazy warming + circuit breakers, or a background cache pre-warming job at startup before the instance enters the load balancer rotation.