Caching, Connection Pooling & Migrations

#Introduction

Three pieces of infrastructure sit under every JPA application in production:

• the second-level cache, which can avoid repeated database reads;
• the connection pool, which decides how many queries can run at once;
• schema migrations, which keep every environment's tables in step with the entities.

#The Two Cache Levels

#Enabling the Second-Level Cache

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-jcache</artifactId>
</dependency>
<dependency>
    <groupId>org.ehcache</groupId>
    <artifactId>ehcache</artifactId>
    <classifier>jakarta</classifier>
</dependency>

spring.jpa.properties.hibernate.cache.use_second_level_cache=true
spring.jpa.properties.hibernate.cache.region.factory_class=jcache
spring.jpa.properties.hibernate.javax.cache.provider=org.ehcache.jsr107.EhcacheCachingProvider
# only entities marked @Cacheable are cached (this is the default)
spring.jpa.properties.jakarta.persistence.sharedCache.mode=ENABLE_SELECTIVE

@Entity
@Cacheable
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Country {
    @Id
    private String code;
    private String name;

    @OneToMany(mappedBy = "country")
    @org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
    private Set<State> states;   // collections are cached separately, and only if annotated
}

A collection cache stores only the ids of its elements. For it to help, the element entity (State) must be cached too.

Concurrency Strategies

The Query Cache

spring.jpa.properties.hibernate.cache.use_query_cache=true

@QueryHints(@QueryHint(name = "org.hibernate.cacheable", value = "true"))
List<Country> findByRegion(String region);

The query cache stores the result ids for a query and its parameters, and the entities come from the entity cache. Any write to a table the query uses invalidates all cached queries on that table, so it only pays off for rarely changing tables.

When to Use It, and When Not To

• Reference and lookup data that is read constantly and changed rarely: countries, product categories, configuration.
• Frequently updated or very large tables: you pay invalidation and memory costs for few hits.
• Data that is also changed outside Hibernate (other services, scripts, bulk SQL): the cache doesn't know and serves stale data. Bulk JPQL updates evict the whole affected region.
• ⚠️ With several application instances, a local cache (Ehcache on-heap) can differ between nodes. Use a distributed provider (Infinispan, Hazelcast, Redis via Redisson) or keep the TTLs short.

#Connection Pooling with HikariCP

Opening a database connection takes milliseconds: TCP, TLS and authentication. A connection pool keeps connections open and lends them out. Spring Boot uses HikariCP by default.

spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=10
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.max-lifetime=1800000
spring.datasource.hikari.leak-detection-threshold=20000

Sizing the Pool

Bigger isn't better. The database can only run a few queries truly in parallel, roughly one per CPU core, plus some overlap for disk and network waits. HikariCP's starting formula is:

connections = (database CPU cores × 2) + effective disk spindles

That gives about 10–20 connections for a typical database server. Also remember the total across all instances: 10 pods × 20 connections = 200 connections to one database, which may exceed its max_connections.

Symptoms of Pool Exhaustion

HikariPool-1 - Connection is not available, request timed out after 30000ms
(total=10, active=10, idle=0, waiting=37)

Common causes:

• Long transactions: remote API calls, file processing or slow queries inside @Transactional.
• Open Session in View holding a connection for the whole HTTP request, including JSON serialization.
• REQUIRES_NEW taking a second connection while the first is still held. Under load this can deadlock the pool.
• Leaks from manual JDBC code that never closes connections. Turn on leak-detection-threshold to find them.

Watch the hikaricp_connections_active and hikaricp_connections_pending metrics (exposed through Actuator and Micrometer).

#Schema Migrations

ddl-auto=update can't rename columns, migrate data, or tell you what changed. Production schemas are managed with versioned migration scripts stored in Git and applied automatically at startup or in the deployment pipeline.

Flyway

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>   <!-- database module for MySQL; PostgreSQL uses flyway-database-postgresql -->
</dependency>

-- V2__add_email_to_employee.sql
ALTER TABLE employee ADD COLUMN email VARCHAR(255);
CREATE UNIQUE INDEX uk_employee_email ON employee (email);

spring.jpa.hibernate.ddl-auto=validate
spring.flyway.enabled=true
# for an existing database that predates Flyway
spring.flyway.baseline-on-migrate=true

How it works:

1. At startup, Spring Boot runs Flyway before JPA initialises.
2. Flyway reads the flyway_schema_history table to see which versions have already been applied.
3. It runs any new V… scripts in version order, each in a transaction where the database allows it, and records them with a checksum.
4. Hibernate's validate then checks that the entities match the resulting schema.

Liquibase

# src/main/resources/db/changelog/db.changelog-master.yaml
databaseChangeLog:
  - changeSet:
      id: 1
      author: devnotes
      changes:
        - createTable:
            tableName: employee
            columns:
              - column: { name: id, type: BIGINT, autoIncrement: true, constraints: { primaryKey: true } }
              - column: { name: name, type: VARCHAR(100), constraints: { nullable: false } }

Both are well supported by Spring Boot. Pick one per project.

Zero-Downtime Changes

During a rolling deployment, old and new versions of the application run at the same time, so schema changes must work with both. Use expand and contract:

Avoid renaming or dropping a column in the same release as the code change.

#Key Takeaways

• The L2 cache is for read-mostly data, looked up by id. The query cache is rarely worth it.
• Choose the cache concurrency strategy by how often the data changes, and beware of multiple nodes.
• HikariCP: small fixed pools, max-lifetime below the database timeout, and leak detection turned on.
• Pool exhaustion usually means transactions held too long.
• Flyway or Liquibase owns the schema, Hibernate only validates it, and changes follow expand and contract.