Hibernate Second-Level Caching: The Good, The Bad, and The Production Nightmares

Let me be blunt: if you think Hibernate second-level caching is a magic performance boost you just turn on with a single property, you are in for a world of pain. I've seen this blow up in production when a team enabled caching on an entire entity hierarchy without considering invalidation. The result? Users saw stale account balances for 10 minutes during a Black Friday sale. The CEO's phone rang off the hook. The fix? A full cache flush and a hot-patch deploy. That's not a good day.

In this advanced guide, we'll cover Hibernate 6.3's second-level cache (L2) with Spring Boot 3.2+, using Redis as the cache store. We'll go beyond the happy-path tutorials and talk about the real-world gotchas: cache stampedes, write-through vs. write-behind, query cache invalidation, and debugging strategies. By the end, you'll know when to use L2 caching, when to avoid it, and how to implement it without waking up at 3 AM.

Setting Up Hibernate L2 Cache with Spring Boot 3.2+ and Redis

Stop doing XML-based cache configuration in 2024. Spring Boot 3.2+ with Hibernate 6.3 makes L2 cache setup almost trivial, but you need to understand what each property does.

First, add the dependencies: spring-boot-starter-cache, spring-boot-starter-data-redis, and hibernate-jcache (the JCache bridge). Hibernate 6.3 removed the deprecated Ehcache 2.x support, so you must use JCache-compatible providers.

Configure your application.yml with spring.cache.type=redis and Hibernate-specific properties like hibernate.cache.use_second_level_cache=true, hibernate.cache.region.factory_class=jcache, and hibernate.cache.use_query_cache=true. The query cache is a trap that will burn you — I'll explain why in section 2.

Here's a basic entity configuration. Notice the @Cache annotation with CacheConcurrencyStrategy.READ_WRITE. This is the most common strategy, but it's not safe for all scenarios.

import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;
import javax.persistence.*;

@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE, region = "product")
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private double price;
    private int stock;

    // getters and setters
}

What the Official Docs Won't Tell You

Let me be blunt: the official Hibernate documentation is great for explaining how the cache works in isolation, but it glosses over the real-world integration nightmares. Here's what the docs won't tell you:

1. Query cache is a trap. The query cache caches query results, not the entities themselves. If you cache a query that returns Product entities, Hibernate caches the entity identifiers. Then, it loads each entity from the L2 cache (or database). If the query cache is stale, you get stale identifiers — and if those entities are not in L2, you hit the database anyway. The query cache is only useful for read-only, frequently repeated queries with identical parameters. In my experience, it causes more invalidation headaches than performance gains.
2. Cache invalidation is not transactional. When you update an entity within a transaction, Hibernate evicts the cache entry at commit time. But if the transaction rolls back, the eviction still happened — you now have a stale cache entry for the old value. There is no rollback mechanism for the L2 cache.
3. RegionFactory matters. The default jcache region factory in Hibernate 6.3 works, but it treats each cache region as a separate Redis key. If you don't configure TTLs per region, you can accidentally cache sensitive data (e.g., user passwords) for hours.

I've seen this blow up in production when a team enabled query caching on a search endpoint without considering that the underlying data changed frequently. Users saw outdated search results for 5 minutes. The fix was to disable query caching entirely and rely on entity caching with short TTLs.

spring:
  cache:
    type: redis
  redis:
    host: localhost
    port: 6379
    timeout: 2000ms
    lettuce:
      pool:
        max-active: 16
        max-idle: 8
        min-idle: 4

hibernate:
  cache:
    use_second_level_cache: true
    region.factory_class: jcache
    use_query_cache: false  # OFF by default, keep it off unless you know what you're doing
    missing_cache_strategy: create-warn

Configuring Cache Concurrency Strategies

Hibernate 6.3 offers four concurrency strategies: READ_ONLY, READ_WRITE, NONSTRICT_READ_WRITE, and TRANSACTIONAL. Here's the blunt truth: only READ_ONLY is truly safe. Everything else is a compromise.

• READ_ONLY: Use for reference data (country codes, product categories). No updates allowed. Fastest and safest.
• READ_WRITE: Uses soft locks and versioning. Works well under moderate concurrency but can lead to stale reads under high contention. Hibernate uses a timestamp-based mechanism to detect conflicts.
• NONSTRICT_READ_WRITE: No soft locks. Cache entries are updated asynchronously (write-behind). If two transactions update the same entity concurrently, the last writer wins — but the cache may have the previous writer's value for a short window. This is what you want for high-write entities where eventual consistency is acceptable.
• TRANSACTIONAL: Requires JTA and a cache provider that supports XA transactions (e.g., Infinispan). Overkill for most applications.

Stop using READ_WRITE for high-write entities. I've seen this blow up in production when a team used READ_WRITE on a UserSession entity that was updated on every request. The soft lock contention caused database deadlocks and cascading failures.

import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;
import javax.persistence.*;

@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE, region = "user_session")
public class UserSession {
    @Id
    private String sessionId;

    private long lastAccessTime;
    private String userAgent;

    // getters and setters
}

Cache Stampede Prevention and Mitigation

A cache stampede (or thundering herd) occurs when a cached entry expires and multiple concurrent requests try to regenerate it simultaneously, all hitting the database. This can bring down your database in seconds.

Hibernate's L2 cache does not have built-in stampede protection. You need to implement it yourself or use the cache provider's features. Redis, for example, doesn't have native stampede prevention, but you can use a distributed lock or a probabilistic early expiration.

The best approach is to use a cache-aside pattern with a mutex lock for regeneration. Alternatively, use early expiration with a background refresh. Spring's @Cacheable supports sync=true, which blocks concurrent accessors until the first one completes. However, this only works for single-node caches; in a multi-node environment, you need a distributed lock.

Here's a production-proven pattern using Redis distributed locks with Redisson.

import org.redisson.api.RLock;
import org.redisson.api.RedissonClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;

import java.util.concurrent.TimeUnit;

@Service
public class ProductService {

    @Autowired
    private RedissonClient redisson;

    @Autowired
    private ProductRepository repository;

    public Product getProductWithStampedeProtection(Long id) {
        String lockKey = "lock:product:" + id;
        RLock lock = redisson.getLock(lockKey);
        try {
            // Try to acquire lock with 2 second wait, 5 second lease
            if (lock.tryLock(2, 5, TimeUnit.SECONDS)) {
                // Double-check cache (not shown for brevity)
                return repository.findById(id).orElseThrow();
            } else {
                // Fallback: wait for first request to complete
                Thread.sleep(100);
                return getProductWithStampedeProtection(id); // recursive retry
            }
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return repository.findById(id).orElseThrow();
        } finally {
            if (lock.isHeldByCurrentThread()) {
                lock.unlock();
            }
        }
    }
}

Invalidation Strategies: When and How to Evict

If you're doing cache invalidation by restarting the application, you're doing it wrong. Cache invalidation must be programmatic and precise.

Hibernate's L2 cache eviction can be done via the SessionFactory.evict() methods. However, in a Spring-managed environment, you typically use @CacheEvict annotations on repository or service methods.

But here's the critical nuance: @CacheEvict only works on Spring Cache abstraction, not directly on Hibernate's L2 cache. If you use @CacheEvict on a method that updates an entity, Spring will evict the cache entry from the Spring Cache (which may be Redis). But Hibernate's L2 cache (also Redis) will still have the old value if you didn't configure them to share the same cache store.

Solution: Use a single cache manager. Configure Spring Cache to use the same Redis instance as Hibernate's L2 cache. Or, better yet, use Hibernate's @Cache annotations and let Hibernate manage eviction via CacheConcurrencyStrategy. But as we discussed, that's not reliable.

My recommendation: Use explicit eviction in your service layer with @CacheEvict and also call SessionFactory.evict() programmatically for critical entities.

import org.hibernate.SessionFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class ProductService {

    @Autowired
    private SessionFactory sessionFactory;

    @Autowired
    private ProductRepository repository;

    @Transactional
    @CacheEvict(value = "product", key = "#product.id")
    public Product updateProduct(Product product) {
        Product updated = repository.save(product);
        // Also evict from Hibernate L2 cache directly
        sessionFactory.getCache().evictEntityData(Product.class, product.getId());
        sessionFactory.getCache().evictEntityRegion(Product.class);
        return updated;
    }
}

Monitoring and Debugging L2 Cache in Production

You can't fix what you can't see. Hibernate provides statistics via hibernate.generate_statistics=true and hibernate.cache.use_structured_entries=true. In Spring Boot, you can expose these via Actuator endpoints.

But here's the hard truth: most teams enable statistics, look at the numbers once, and never check again. You need to set up alerts on cache hit ratio, eviction count, and put count. A sudden drop in hit ratio often indicates a cache stampede or a misconfigured eviction.

Use JMX to monitor Hibernate cache regions in real-time. Connect with JConsole or VisualVM. Look for CacheRegionStatistics MBeans. If you see HitCount dropping while MissCount rising, investigate immediately.

Also, enable slow query logging in Redis to see which cache keys are being accessed most. Use redis-cli --bigkeys to find large cache entries that might indicate entity bloat.

spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true
        cache:
          use_structured_entries: true
          region_prefix: myapp

management:
  endpoints:
    web:
      exposure:
        include: health,info,caches,metrics
  metrics:
    export:
      redis:
        enabled: true

Advanced: Custom Cache Region Factories and TTLs

Hibernate 6.3 allows you to implement a custom RegionFactory to control how cache regions are created and configured. This is useful when you need per-region TTLs, serialization strategies, or custom eviction policies.

For example, you might want a 5-minute TTL for product entities, 1-hour for reference data, and 30 seconds for user sessions. The default jcache region factory does not support per-region configuration via properties; you have to configure it programmatically.

Here's how to create a custom RegionFactory that reads TTLs from application.yml and applies them to each region. This is an advanced pattern that gives you fine-grained control.

import org.hibernate.cache.jcache.JCacheRegionFactory;
import org.hibernate.cache.spi.CacheDataDescription;
import org.hibernate.cache.spi.RegionFactory;
import org.hibernate.cache.spi.access.AccessType;
import org.hibernate.cfg.AvailableSettings;
import org.hibernate.internal.util.config.ConfigurationHelper;

import javax.cache.Cache;
import javax.cache.CacheManager;
import javax.cache.configuration.MutableConfiguration;
import javax.cache.expiry.Duration;
import javax.cache.expiry.TouchedExpiryPolicy;
import java.util.Map;
import java.util.concurrent.TimeUnit;

public class CustomRegionFactory extends JCacheRegionFactory {

    private Map<String, Long> regionTtls;

    @Override
    public void start(SessionFactoryOptions settings, Map<String, Object> properties) {
        super.start(settings, properties);
        // Read TTLs from properties (e.g., hibernate.cache.region_ttls.product=300)
        regionTtls = ConfigurationHelper.extractMap(
            properties, "hibernate.cache.region_ttls", ",", ":"
        );
    }

    @Override
    protected Cache<Object, Object> createCache(String regionName, CacheManager cacheManager, CacheDataDescription metadata) {
        MutableConfiguration<Object, Object> config = new MutableConfiguration<>();
        config.setTypes(Object.class, Object.class);
        config.setStoreByValue(false);
        config.setStatisticsEnabled(true);
        
        if (regionTtls.containsKey(regionName)) {
            long ttlSeconds = regionTtls.get(regionName);
            config.setExpiryPolicyFactory(
                TouchedExpiryPolicy.factoryOf(new Duration(TimeUnit.SECONDS, ttlSeconds))
            );
        }
        
        return cacheManager.createCache(regionName, config);
    }
}

Testing and Validating Cache Behavior

Stop testing caching in unit tests with in-memory databases. You need integration tests with Redis (or your cache provider) to catch real issues like serialization failures, cache stampedes, and TTL expiration.

Use Testcontainers to spin up a Redis container in your tests. Write tests that verify cache hits and misses, concurrent access, and eviction. Also test the edge case where the cache provider is down — your application should degrade gracefully, not throw exceptions.

Here's a sample test that verifies the L2 cache is working and that eviction happens correctly.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
@Testcontainers
public class CacheIntegrationTest {

    @Container
    static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
            .withExposedPorts(6379);

    @DynamicPropertySource
    static void redisProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.redis.host", redis::getHost);
        registry.add("spring.redis.port", () -> redis.getMappedPort(6379));
    }

    @Autowired
    private ProductService productService;

    @Autowired
    private ProductRepository repository;

    @Test
    void testCacheHitAfterFirstLoad() {
        Product product = new Product();
        product.setName("Test Product");
        product.setPrice(10.0);
        product = repository.save(product);

        // First load: cache miss
        Product firstLoad = productService.getProduct(product.getId());
        assertThat(firstLoad).isNotNull();

        // Second load: cache hit
        Product secondLoad = productService.getProduct(product.getId());
        assertThat(secondLoad).isSameAs(firstLoad); // same instance if L1, but L2 will be deserialized
    }

    @Test
    void testEviction() {
        Product product = new Product();
        product.setName("Evict Me");
        product = repository.save(product);

        productService.getProduct(product.getId()); // loads into cache
        productService.updateProduct(product); // evicts

        // After eviction, next load should be a miss
        Product reloaded = productService.getProduct(product.getId());
        assertThat(reloaded).isNotNull();
    }
}