The persistence context, dirty checking and flush

Every JPA EntityManager owns a persistence context: a map from entity id to the one managed instance for that id. In a Spring application the persistence context normally lives exactly as long as the transaction. Three behaviours follow from it.

Identity. Inside one transaction, findById(1) twice returns the same object, and the second call does not query the database — the entity is already in the map (this map is often called the first-level cache).

Dirty checking. When an entity is loaded, Hibernate keeps a snapshot of its state. At flush time it compares every managed entity with its snapshot and issues an UPDATE for each one that changed. There is no need to call save() for an entity you loaded in the same transaction; changing a field is enough. The comparison is of values, not of calls: set a field and set it back before the flush, and there is nothing to update. By default the UPDATE writes every mapped column; @DynamicUpdate on the entity limits it to the changed ones.

@Transactional
public void rename(long id, String name) {
    Customer c = customers.findById(id).orElseThrow();
    c.setName(name);          // no save(): the UPDATE is sent at commit
}

Write-behind. persist and remove do not send SQL straight away. The changes are queued and sent at flush: before commit, on an explicit flush(), and (in the default AUTO mode) before a query whose result the pending changes could affect.

1import java.util.*;2 3public class Solution {4    static final class Customer {5        final long id; String name;6        Customer(long id, String name) { this.id = id; this.name = name; }7    }8 9    static final class PersistenceContext {10        final Map<Long, String> database;11        final Map<Long, Customer> managed = new LinkedHashMap<>();12        final Map<Long, String> snapshots = new HashMap<>();13        final List<String> sql = new ArrayList<>();14        PersistenceContext(Map<Long, String> database) { this.database = database; }15 16        Customer find(long id) {17            Customer c = managed.get(id);18            if (c != null) return c;                       // first-level cache hit19            sql.add("select customer " + id);20            c = new Customer(id, database.get(id));21            managed.put(id, c);22            snapshots.put(id, c.name);23            return c;24        }25 26        void flush() {27            for (Customer c : managed.values()) {28                if (!Objects.equals(c.name, snapshots.get(c.id))) {   // dirty check29                    sql.add("update customer " + c.id + " set name='" + c.name + "'");30                    database.put(c.id, c.name);31                    snapshots.put(c.id, c.name);32                }33            }34        }35    }36 37    public static List<String> run() {38        PersistenceContext pc = new PersistenceContext(new HashMap<>(Map.of(1L, "Ana", 2L, "Ben")));39        Customer a = pc.find(1);40        Customer again = pc.find(1);41        pc.find(2);                       // loaded but never changed42        a.name = "Anna";                  // no save() call anywhere43        pc.flush();                       // what commit does44        List<String> out = new ArrayList<>(pc.sql);45        out.add("same instance: " + (a == again));46        return out;47    }48}

Flush order is not call order

When it flushes, Hibernate does not replay your calls in sequence. Its action queue runs the work by kind: entity inserts first, then updates, then collection changes, and the deletions you requested with remove() last, whatever order you called them in. That surprises people in one classic case: delete a row and insert a replacement with the same unique value in one transaction. The INSERT runs first, while the old row still exists, and the unique constraint fails.

1import java.util.*;2 3public class Solution {4    public static List<String> run() {5        List<String> inserts = new ArrayList<>(), updates = new ArrayList<>(), deletes = new ArrayList<>();6        List<String> calls = new ArrayList<>();7 8        // The code, in the order it was written:9        calls.add("remove(user 7, email=ana@example.com)");10        deletes.add("delete from users where id=7");11        calls.add("persist(user 8, email=ana@example.com)");12        inserts.add("insert into users (id, email) values (8, 'ana@example.com')");13 14        // At flush the queue is executed by category, not by call order.15        List<String> out = new ArrayList<>();16        out.add("calls: " + String.join(" then ", calls));17        List<String> flushed = new ArrayList<>(inserts);18        flushed.addAll(updates);19        flushed.addAll(deletes);20        for (int i = 0; i < flushed.size(); i++) out.add("sql " + (i + 1) + ": " + flushed.get(i));21        return out;22    }23}

The fix is to force the delete out first with an explicit flush() (repository.flush() or entityManager.flush()) between the two operations — or to update the existing row instead.

One exception to write-behind: with GenerationType.IDENTITY, the database generates the id, so inside a transaction Hibernate runs the INSERT as soon as you persist to learn it (and cannot batch those inserts). Sequence-generated ids do not have this restriction.

EntityManager.clear() empties the persistence context without flushing: every entity becomes detached, and changes not yet flushed are lost.

What save() does

SimpleJpaRepository.save(entity) asks whether the entity is new. By default that means: if the entity has a @Version field of a wrapper type, whether the version is null; otherwise whether the id is null (or 0 for a primitive id). A new entity is passed to persist and becomes managed. Any other entity is passed to merge, which copies its state onto a managed instance and returns that instance; the object you passed in stays detached. Keep using the return value of save.

Common mistakes

• Calling on an entity loaded in the same transaction "to make sure": harmless, but it shows the dirty checking was not understood.