Devops Monk

Introduction

The persistence context is the single most important concept in JPA. Everything else — lazy loading, dirty checking, transaction scope, detached entity exceptions — only makes sense once you understand what the persistence context is and how it works.

Many JPA bugs come from developers not understanding this concept. Understand it well and the rest of JPA becomes predictable.

What Is the Persistence Context?

The persistence context is an in-memory map of entities managed by the current EntityManager. Think of it as a cache that sits between your application and the database for the duration of a unit of work (usually one transaction).

Your Code
   │
   ▼
Persistence Context (EntityManager)      ← In-memory map of entities
   │  • tracks every loaded entity
   │  • detects changes (dirty checking)
   │  • batches SQL until flush
   │
   ▼
Database

When you load a Customer with findById(1L), it is:

1. Fetched from the database
2. Placed in the persistence context under key (Customer.class, 1L)
3. Returned to your code

If you call findById(1L) again in the same transaction, Hibernate returns the same object from the persistence context — no second SQL query is issued. This is the first-level cache.

The EntityManager

The EntityManager is the JPA interface that manages the persistence context. It is the gateway for all persistence operations.

@Service
@RequiredArgsConstructor
public class CustomerService {

    // Spring injects a proxy that routes to the current EntityManager
    @PersistenceContext
    private EntityManager em;

    @Transactional
    public Customer loadTwice(Long id) {
        Customer first  = em.find(Customer.class, id);   // SQL: SELECT
        Customer second = em.find(Customer.class, id);   // No SQL — cache hit

        System.out.println(first == second);  // true — same object
        return first;
    }
}

first == second is true because the persistence context returns the exact same Java instance — this is JPA’s identity guarantee: within one persistence context, each entity has exactly one instance.

Persistence Context Scope in Spring Boot

In a Spring Boot application:

• Each @Transactional method gets its own persistence context for the duration of the method
• The persistence context is opened when the transaction starts and closed when the transaction commits or rolls back
• After the persistence context closes, entities become detached (explained in Article 4)

@Service
public class OrderService {

    @Transactional
    public void processOrder(Long orderId) {
        // Persistence context is OPEN here
        Order order = orderRepository.findById(orderId).orElseThrow();
        order.setStatus("PROCESSING");
        // Hibernate detects the change — no explicit save() needed
        // Persistence context CLOSES here on commit → INSERT/UPDATE flushed
    }

    // After this method returns, the persistence context is GONE
    // The Order object is now DETACHED
}

Dirty Checking: The Magic of JPA

When you load an entity inside a transaction and modify it, Hibernate automatically detects the change and generates an UPDATE — without you calling save() or update().

This is called dirty checking:

@Transactional
public void updateCustomerEmail(Long id, String newEmail) {
    Customer customer = customerRepository.findById(id).orElseThrow();
    // customer is now MANAGED (inside the persistence context)

    customer.setEmail(newEmail);
    // No save() call — Hibernate will detect this change

    // At transaction commit: Hibernate compares current state vs. snapshot
    // and issues:  UPDATE customers SET email=? WHERE id=?
}

How dirty checking works internally

When Hibernate loads an entity, it takes a snapshot of its state. At flush time (before commit, by default), it compares the current state of every managed entity against its snapshot. Any differences produce UPDATE SQL.

Load Customer → snapshot: {id=1, name="Alice", email="old@example.com"}
customer.setEmail("new@example.com")
Flush → compare → email changed → UPDATE customers SET email=? WHERE id=?

This is automatic and precise — Hibernate only updates the columns that actually changed.

The First-Level Cache in Action

The first-level cache prevents redundant queries within the same transaction:

@Transactional
public void demonstrateFirstLevelCache(Long id) {
    // SQL: SELECT * FROM customers WHERE id = 1
    Customer c1 = customerRepository.findById(id).orElseThrow();

    // NO SQL — returned directly from persistence context
    Customer c2 = customerRepository.findById(id).orElseThrow();

    // Same instance
    assert c1 == c2;

    // Modifying c1 also affects c2 — they are the same object
    c1.setName("Updated");
    System.out.println(c2.getName()); // "Updated"
}

This means within a transaction, your entity graph is consistent — you always see the latest state of every loaded entity.

Flush: When Does SQL Actually Run?

Loading and modifying entities does not immediately run SQL. SQL runs when the persistence context flushes to the database.

Flush happens:

1. Before a query — to ensure the query sees your latest changes
2. On transaction commit — to write everything to the database
3. When you call em.flush() explicitly (rarely needed)

@Transactional
public void flushBehaviour() {
    Customer c = new Customer();
    c.setName("Bob");
    customerRepository.save(c);   // persisted in context — no SQL yet

    // SQL runs HERE — Hibernate flushes before executing this query
    // so the query can see the new customer
    List<Customer> all = customerRepository.findAll();
}

Flush modes

AUTO is correct for almost every use case. You might use COMMIT for read-heavy operations where you know no queries need to see uncommitted writes.

The Persistence Context as a Unit of Work

The persistence context implements the Unit of Work pattern. All your changes are collected in-memory and written to the database in one operation (the flush) — this keeps the number of database round trips low.

@Transactional
public void bulkUpdate(List<Long> ids, String newStatus) {
    for (Long id : ids) {
        Order order = orderRepository.findById(id).orElseThrow();
        order.setStatus(newStatus);
        // No database write yet
    }
    // All UPDATEs flushed together on commit — much more efficient
    // than a save() call inside the loop
}

Contrast this with calling save() or update() inside the loop, which sends a round-trip for each item.

When the Persistence Context Hurts: Memory Pressure in Batch Jobs

For batch jobs that process millions of records, keeping all entities in the persistence context uses too much memory. The solution is to periodically clear the context:

@Transactional
public void processBatch(List<Long> ids) {
    int count = 0;
    for (Long id : ids) {
        Order order = orderRepository.findById(id).orElseThrow();
        order.setStatus("PROCESSED");
        count++;

        if (count % 100 == 0) {
            em.flush();   // write current batch to DB
            em.clear();   // clear the context — entities become detached
        }
    }
}

After em.clear(), all entities are detached. Any reference you hold to them is now outside the persistence context, and Hibernate will no longer track them.

EntityManager vs. Spring Data Repositories

Spring Data JPA’s repository methods all use the EntityManager internally. When you call customerRepository.findById(1L), Spring Data calls em.find(Customer.class, 1L) under the hood.

You do not need to inject the EntityManager directly unless you need to:

• Call em.flush() or em.clear() in batch operations
• Execute a complex JPQL query not expressible as a repository method
• Write a custom repository implementation

In all other cases, use the repository interface.

Visualising the Persistence Context

Transaction START → Persistence Context OPENS
│
├── findById(1)       → Cache miss → SQL SELECT → entity added to context
├── findById(1)       → Cache hit  → no SQL     → same instance returned
├── entity.setX()     → context notes this entity is dirty
├── findAll()         → flush first (AUTO mode) → dirty entity's UPDATE runs
│                                                → then SELECT runs
├── new entity → save → entity added to context  → INSERT pending
│
Transaction COMMIT → flush remaining changes → INSERT/UPDATE/DELETE → context CLOSES

Key Takeaways

• The persistence context is an in-memory identity map that tracks every entity you load or save within a transaction
• It guarantees identity: within one transaction, each entity instance is unique — findById(1) always returns the same object
• Dirty checking automatically detects field changes and generates UPDATE — no explicit save() needed for managed entities
• SQL is not sent to the database immediately — it is batched and flushed before queries and on commit
• In Spring Boot, the persistence context lives exactly as long as the @Transactional transaction
• For batch processing, periodically flush and clear the context to avoid memory pressure

What’s Next

Article 4 covers the four entity lifecycle states — Transient, Managed, Detached, and Removed. Understanding these states is essential for knowing when JPA is tracking an entity and when it is not.