5. Flushing

Flushing is the process of synchronizing the state of the persistence context with the underlying database. The EntityManager and the Hibernate Session expose a set of methods, through which the application developer can change the persistent state of an entity.

The persistence context acts as a transactional write-behind cache, queuing any entity state change. Like any write-behind cache, changes are first applied in-memory and synchronized with the database during flush time. The flush operation takes every entity state change and translates it to an INSERT, UPDATE or DELETE statement.

	Because DML statements are grouped together, Hibernate can apply batching transparently. See the Batching chapter for more information.

The flushing strategy is given by the flushMode of the current running Hibernate Session. Although JPA defines only two flushing strategies (AUTO and COMMIT), Hibernate has a much broader spectrum of flush types:

ALWAYS
Flushes the Session before every query.
AUTO
This is the default mode and it flushes the Session only if necessary.
COMMIT
The Session tries to delay the flush until the current Transaction is committed, although it might flush prematurely too.
MANUAL
The Session flushing is delegated to the application, which must call Session.flush() explicitly in order to apply the persistence context changes.

5.1. `AUTO` flush

By default, Hibernate uses the AUTO flush mode which triggers a flush in the following circumstances:

prior to committing a Transaction
prior to executing a JPQL/HQL query that overlaps with the queued entity actions
before executing any native SQL query that has no registered synchronization

5.1.1. `AUTO` flush on commit

In the following example, an entity is persisted and then the transaction is committed.

Example 189. Automatic flushing on commit

entityManager = entityManagerFactory().createEntityManager();
txn = entityManager.getTransaction();
txn.begin();

Person person = new Person( "John Doe" );
entityManager.persist( person );
log.info( "Entity is in persisted state" );

txn.commit();

--INFO: Entity is in persisted state
INSERT INTO Person (name, id) VALUES ('John Doe', 1)

Hibernate logs the message prior to inserting the entity because the flush only occurred during transaction commit.

	This is valid for the `SEQUENCE` and `TABLE` identifier generators. The `IDENTITY` generator must execute the insert right after calling `persist()`. For details, see the discussion of generators in Identifier generators.

5.1.2. `AUTO` flush on JPQL/HQL query

A flush may also be triggered when executing an entity query.

Example 190. Automatic flushing on JPQL/HQL

Person person = new Person( "John Doe" );
entityManager.persist( person );
entityManager.createQuery( "select p from Advertisement p" ).getResultList();
entityManager.createQuery( "select p from Person p" ).getResultList();

SELECT a.id AS id1_0_ ,
       a.title AS title2_0_
FROM   Advertisement a

INSERT INTO Person (name, id) VALUES ('John Doe', 1)

SELECT p.id AS id1_1_ ,
       p.name AS name2_1_
FROM   Person p

The reason why the Advertisement entity query didn’t trigger a flush is because there’s no overlapping between the Advertisement and the Person tables:

Example 191. Automatic flushing on JPQL/HQL entities

@Entity(name = "Person")
public static class Person {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    public Person() {}

    public Person(String name) {
        this.name = name;
    }

    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

}

@Entity(name = "Advertisement")
public static class Advertisement {

    @Id
    @GeneratedValue
    private Long id;

    private String title;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }
}

When querying for a Person entity, the flush is triggered prior to executing the entity query.

Example 192. Automatic flushing on JPQL/HQL

Person person = new Person( "John Doe" );
entityManager.persist( person );
entityManager.createQuery( "select p from Person p" ).getResultList();

INSERT INTO Person (name, id) VALUES ('John Doe', 1)

SELECT p.id AS id1_1_ ,
       p.name AS name2_1_
FROM   Person p

This time, the flush was triggered by a JPQL query because the pending entity persist action overlaps with the query being executed.

5.1.3. `AUTO` flush on native SQL query

When executing a native SQL query, a flush is always triggered when using the EntityManager API.

Example 193. Automatic flushing on native SQL using EntityManager

assertTrue(((Number) entityManager
        .createNativeQuery( "select count(*) from Person")
        .getSingleResult()).intValue() == 0 );

Person person = new Person( "John Doe" );
entityManager.persist( person );

assertTrue(((Number) entityManager
        .createNativeQuery( "select count(*) from Person")
        .getSingleResult()).intValue() == 1 );

The Session API doesn’t trigger an AUTO flush when executing a native query

Example 194. Automatic flushing on native SQL using Session

assertTrue(((Number) entityManager
        .createNativeQuery( "select count(*) from Person")
        .getSingleResult()).intValue() == 0 );

Person person = new Person( "John Doe" );
entityManager.persist( person );
Session session = entityManager.unwrap(Session.class);

assertTrue(((Number) session
        .createSQLQuery( "select count(*) from Person")
        .uniqueResult()).intValue() == 0 );

To flush the Session, the query must use a synchronization:

Example 195. Automatic flushing on native SQL with Session synchronization

assertTrue(((Number) entityManager
        .createNativeQuery( "select count(*) from Person")
        .getSingleResult()).intValue() == 0 );

Person person = new Person( "John Doe" );
entityManager.persist( person );
Session session = entityManager.unwrap( Session.class );

assertTrue(((Number) session
        .createSQLQuery( "select count(*) from Person")
        .addSynchronizedEntityClass( Person.class )
        .uniqueResult()).intValue() == 1 );

5.2. `COMMIT` flush

JPA also defines a COMMIT flush mode, which is described as follows:

If FlushModeType.COMMIT is set, the effect of updates made to entities in the persistence context upon queries is unspecified.

— Section 3.10.8 of the JPA 2.1 Specification

When executing a JPQL query, the persistence context is only flushed when the current running transaction is committed.

Example 196. COMMIT flushing on JPQL

Person person = new Person("John Doe");
entityManager.persist(person);

entityManager.createQuery("select p from Advertisement p")
    .setFlushMode( FlushModeType.COMMIT)
    .getResultList();

entityManager.createQuery("select p from Person p")
    .setFlushMode( FlushModeType.COMMIT)
    .getResultList();

SELECT a.id AS id1_0_ ,
       a.title AS title2_0_
FROM   Advertisement a

SELECT p.id AS id1_1_ ,
       p.name AS name2_1_
FROM   Person p

INSERT INTO Person (name, id) VALUES ('John Doe', 1)

Because the JPA doesn’t impose a strict rule on delaying flushing, when executing a native SQL query, the persistence context is going to be flushed.

Example 197. COMMIT flushing on SQL

Person person = new Person("John Doe");
entityManager.persist(person);

assertTrue(((Number) entityManager
    .createNativeQuery("select count(*) from Person")
    .getSingleResult()).intValue() == 1);

INSERT INTO Person (name, id) VALUES ('John Doe', 1)

SELECT COUNT(*) FROM Person

5.3. `ALWAYS` flush

	The `ALWAYS` is only available with the native `Session` API.

The ALWAYS flush mode triggers a persistence context flush even when executing a native SQL query against the Session API.

Example 198. COMMIT flushing on SQL

Person person = new Person("John Doe");
entityManager.persist(person);

Session session = entityManager.unwrap( Session.class);
assertTrue(((Number) session
        .createSQLQuery("select count(*) from Person")
        .setFlushMode( FlushMode.ALWAYS)
        .uniqueResult()).intValue() == 1);

INSERT INTO Person (name, id) VALUES ('John Doe', 1)

SELECT COUNT(*) FROM Person

5.4. `MANUAL` flush

Both the EntityManager and the Hibernate Session define a flush() method that, when called, triggers a manual flush. Hibernate also defines a MANUAL flush mode, so the persistence context can only be flushed manually.

Example 199. MANUAL flushing

Person person = new Person("John Doe");
entityManager.persist(person);

Session session = entityManager.unwrap( Session.class);
session.setFlushMode( FlushMode.MANUAL);

assertTrue(((Number) entityManager
    .createQuery("select count(id) from Person")
    .getSingleResult()).intValue() == 0);

assertTrue(((Number) session
    .createSQLQuery("select count(*) from Person")
    .uniqueResult()).intValue() == 0);

SELECT COUNT(p.id) AS col_0_0_
FROM   Person p

SELECT COUNT(*)
FROM   Person

The INSERT statement was not executed because the persistence context because there was no manual flush() call.

| | This mode is useful when using multi-request logical transactions and only the last request should flush the persistence context. | | --- | --- |

5. Flushing

5.1. AUTO flush

5.1.1. AUTO flush on commit

5.1.2. AUTO flush on JPQL/HQL query

5.1.3. AUTO flush on native SQL query

5.2. COMMIT flush

5.3. ALWAYS flush

5.4. MANUAL flush