Hibernate 5 to 7 Migration Guide and Cheat Sheet: What Breaks, What Changed, What to Write Now

import java.io.Serializable;
import java.util.List;

import org.hibernate.Criteria;
import org.hibernate.FlushMode;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.criterion.Restrictions;

/** Hibernate 5 style calls that use no persistence annotations. Compiled by scripts/compile-old-apis.sh against 5.6.15 and 7.4.14. */
@SuppressWarnings({"deprecation", "rawtypes"})
class OldHibernate {

    Serializable save(Session s, Object o) {
        return s.save(o);
    }

    void update(Session s, Object o) {
        s.update(o);
    }

    void saveOrUpdate(Session s, Object o) {
        s.saveOrUpdate(o);
    }

    void delete(Session s, Object o) {
        s.delete(o);
    }

    Object load(Session s) {
        return s.load(Object.class, 1L);
    }

    List criteria(Session s) {
        Criteria c = s.createCriteria(Object.class).add(Restrictions.eq("name", "x"));
        return c.list();
    }

    List sql(Session s) {
        return s.createSQLQuery("select 1").list();
    }

    void flushMode(Session s) {
        s.setFlushMode(FlushMode.AUTO);
    }

    Object metadata(SessionFactory sf) {
        return sf.getClassMetadata(Object.class);
    }
}

Source: OldHibernate.java.

import java.util.List;

import org.hibernate.FlushMode;
import org.hibernate.Session;

/** The replacements for OldHibernate that exist on both 5.6.15 and 7.4.14, so they can be made before the upgrade. */
class NewHibernate {

    void persist(Session s, Object o) {
        s.persist(o);
    }

    Object merge(Session s, Object o) {
        return s.merge(o);
    }

    void remove(Session s, Object o) {
        s.remove(o);
    }

    Object find(Session s) {
        return s.find(Object.class, 1L);
    }

    Object reference(Session s) {
        return s.getReference(Object.class, 1L);
    }

    List<Object> query(Session s) {
        return s.createQuery("from Object o where o.name = :n", Object.class).setParameter("n", "x").getResultList();
    }

    List<?> nativeQuery(Session s) {
        return s.createNativeQuery("select 1").getResultList();
    }

    void flushMode(Session s) {
        s.setHibernateFlushMode(FlushMode.AUTO);
    }
}

Source: NewHibernate.java.

Hibernate 5.6.15, compiling NewHibernate.java
javac exit status: 0

Hibernate 7.4.14, compiling NewHibernate.java
src/compat/NewHibernate.java:34: warning: [deprecation] createNativeQuery(String) in Session has been deprecated
        return s.createNativeQuery("select 1").getResultList();
                ^
1 warning
javac exit status: 0

Output: 04-new-hibernate-apis-5.6.15.txt and 04-new-hibernate-apis-7.4.14.txt. On 7.4.14 the one-argument createNativeQuery compiles with a deprecation warning, so prefer the overload that takes a result class once you are there.

import org.hibernate.annotations.GenericGenerator;
import org.hibernate.annotations.Type;
import org.hibernate.annotations.Where;

/** Hibernate 5 annotation attributes. The annotations are applied to a plain class, so no persistence import is needed. */
@SuppressWarnings("deprecation")
@Where(clause = "deleted = false")
class OldAnnotations {

    @Type(type = "yes_no")
    boolean flag;

    @GenericGenerator(name = "g", strategy = "increment")
    Long id;
}

Source: OldAnnotations.java.

Hibernate 5.6.15, compiling OldAnnotations.java
javac exit status: 0

Hibernate 7.4.14, compiling OldAnnotations.java
src/compat/OldAnnotations.java:3: error: cannot find symbol
import org.hibernate.annotations.Where;
                                ^
  symbol:   class Where
  location: package org.hibernate.annotations
src/compat/OldAnnotations.java:7: error: cannot find symbol
@Where(clause = "deleted = false")
 ^
  symbol: class Where
src/compat/OldAnnotations.java:10: error: cannot find symbol
    @Type(type = "yes_no")
          ^
  symbol:   method type()
  location: @interface Type
src/compat/OldAnnotations.java:10: error: annotation @Type is missing a default value for the element 'value'
    @Type(type = "yes_no")
    ^
src/compat/OldAnnotations.java:13: warning: [removal] GenericGenerator in org.hibernate.annotations has been deprecated and marked for removal
    @GenericGenerator(name = "g", strategy = "increment")
     ^
src/compat/OldAnnotations.java:13: warning: [removal] strategy() in GenericGenerator has been deprecated and marked for removal
    @GenericGenerator(name = "g", strategy = "increment")
                                  ^
4 errors
2 warnings
javac exit status: 1

Output: 05-old-annotations-5.6.15.txt and 05-old-annotations-7.4.14.txt.

import org.hibernate.annotations.JdbcTypeCode;
import org.hibernate.annotations.SQLRestriction;
import org.hibernate.type.SqlTypes;

/** The Hibernate 6 and 7 spelling of the same ideas. This does not compile on 5.6.15. */
@SQLRestriction("deleted = false")
class NewAnnotations {

    @JdbcTypeCode(SqlTypes.CHAR)
    boolean flag;
}

Source: NewAnnotations.java.

Hibernate 5.6.15, compiling NewAnnotations.java
src/compat/NewAnnotations.java:1: error: cannot find symbol
import org.hibernate.annotations.JdbcTypeCode;
                                ^
  symbol:   class JdbcTypeCode
  location: package org.hibernate.annotations
src/compat/NewAnnotations.java:2: error: cannot find symbol
import org.hibernate.annotations.SQLRestriction;
                                ^
  symbol:   class SQLRestriction
  location: package org.hibernate.annotations
src/compat/NewAnnotations.java:3: error: cannot find symbol
import org.hibernate.type.SqlTypes;
                         ^
  symbol:   class SqlTypes
  location: package org.hibernate.type
src/compat/NewAnnotations.java:6: error: cannot find symbol
@SQLRestriction("deleted = false")
 ^
  symbol: class SQLRestriction
src/compat/NewAnnotations.java:9: error: cannot find symbol
    @JdbcTypeCode(SqlTypes.CHAR)
     ^
  symbol:   class JdbcTypeCode
  location: class NewAnnotations
src/compat/NewAnnotations.java:9: error: cannot find symbol
    @JdbcTypeCode(SqlTypes.CHAR)
                  ^
  symbol:   variable SqlTypes
  location: class NewAnnotations
6 errors
javac exit status: 1

Hibernate 7.4.14, compiling NewAnnotations.java
javac exit status: 0

Output: 06-new-annotations-5.6.15.txt and 06-new-annotations-7.4.14.txt. @SQLRestriction takes the place of @Where. The @JdbcTypeCode line only shows that the annotation exists: I did not check which JDBC type reproduces what @Type(type = "yes_no") stored, so look that up before you replace it.

package com.ankurm.migration;

import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
import jakarta.persistence.Enumerated;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;

import java.math.BigDecimal;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDateTime;
import java.util.UUID;

/** One field of each type whose default column mapping is worth comparing, and a generated id. */
@Entity
public class Probe {

    @Id
    @GeneratedValue
    Long id;

    String name;
    boolean active;
    Instant createdAt;
    LocalDateTime occurredAt;
    UUID uuid;
    Duration span;
    BigDecimal price;
    byte[] payload;

    @Enumerated(EnumType.ORDINAL)
    Colour byOrdinal;

    @Enumerated(EnumType.STRING)
    Colour byName;

    public enum Colour { RED, GREEN }

    public Probe() {
    }

    Probe(String name) {
        this.name = name;
    }
}

Source: Probe.java. The 5.6.15 module has the same class with javax.persistence imports.

package com.ankurm.migration;

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

import java.util.List;

import org.hibernate.Hibernate;
import org.hibernate.Session;
import org.hibernate.StatelessSession;
import org.junit.jupiter.api.Test;

/** Snippets for the cheat sheet. Each test prints what it did to ../output/1N-cheat-*.txt and asserts the same values. */
class CheatSheetTest {

    @Test
    void sessionApi() {
        try (Db db = new Db(Author.class, Book.class); Transcript t = new Transcript("10-cheat-session-api")) {
            Long id;
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                Author a = new Author("[email protected]", "Ann");
                s.persist(a);
                id = a.id;
                s.getTransaction().commit();
                t.line("persist(a)               -> id assigned on the object: " + id);
            }
            try (Session s = db.sessionFactory.openSession()) {
                db.clear();
                Author found = s.find(Author.class, id);
                t.line("find(Author, id)         -> " + found.name + "  (" + db.sql.size() + " select)");
                assertThat(found.name).isEqualTo("Ann");
                assertThat(db.sql).hasSize(1);
            }
            try (Session s = db.sessionFactory.openSession()) {
                db.clear();
                Author ref = s.getReference(Author.class, id);
                t.line("getReference(Author, id) -> initialized: " + Hibernate.isInitialized(ref) + "  (" + db.sql.size() + " selects)");
                assertThat(Hibernate.isInitialized(ref)).isFalse();
                assertThat(db.sql).isEmpty();
            }
            try (Session s = db.sessionFactory.openSession()) {
                Author detached = new Author("[email protected]", "Ann Smith");
                detached.id = id;
                s.beginTransaction();
                Author managed = s.merge(detached);
                t.line("merge(detached)          -> returns a different instance: " + (managed != detached) + ", name now " + managed.name);
                s.getTransaction().commit();
                assertThat(managed).isNotSameAs(detached);
                assertThat(managed.name).isEqualTo("Ann Smith");
            }
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                Author extra = new Author("[email protected]", "Bob");
                s.persist(extra);
                s.getTransaction().commit();
                Long bobId = extra.id;
                List<Author> many = s.findMultiple(Author.class, List.of(id, bobId, 999L));
                t.line("findMultiple(ids 3)      -> " + many.size() + " entries, missing id gives: " + many.get(2));
                assertThat(many).hasSize(3);
                assertThat(many.get(2)).isNull();
            }
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                Author a = s.find(Author.class, id);
                s.remove(a);
                s.getTransaction().commit();
                t.line("remove(a)                -> find afterwards: " + s.find(Author.class, id));
                assertThat(s.find(Author.class, id)).isNull();
            }
        }
    }

    @Test
    void hql() {
        try (Db db = new Db(Author.class, Book.class); Transcript t = new Transcript("11-cheat-hql")) {
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                Author ann = new Author("[email protected]", "Ann");
                Author bob = new Author("[email protected]", "Bob");
                s.persist(ann);
                s.persist(bob);
                s.persist(new Book("Alpha", 100, ann));
                s.persist(new Book("Beta", 300, ann));
                s.persist(new Book("Gamma", null, bob));
                s.getTransaction().commit();
            }
            try (Session s = db.sessionFactory.openSession()) {
                List<String> named = s.createSelectionQuery("select b.title from Book b where b.pages > :min order by b.title", String.class)
                        .setParameter("min", 150).getResultList();
                t.line("named parameter           : " + named);
                assertThat(named).containsExactly("Beta");

                List<String> ordinal = s.createSelectionQuery("select b.title from Book b where b.pages > ?1 order by b.title", String.class)
                        .setParameter(1, 50).getResultList();
                t.line("?1 parameter              : " + ordinal);
                assertThat(ordinal).containsExactly("Alpha", "Beta");

                List<String> page = s.createSelectionQuery("select b.title from Book b order by b.title limit 2 offset 1", String.class).getResultList();
                t.line("limit 2 offset 1 in HQL   : " + page);
                assertThat(page).containsExactly("Beta", "Gamma");

                List<String> nulls = s.createSelectionQuery("select b.title from Book b order by b.pages desc nulls last", String.class).getResultList();
                t.line("order by ... nulls last   : " + nulls);
                assertThat(nulls).containsExactly("Beta", "Alpha", "Gamma");

                Book none = s.createSelectionQuery("from Book b where b.title = 'Nope'", Book.class).getSingleResultOrNull();
                t.line("getSingleResultOrNull()   : " + none);
                assertThat(none).isNull();

                List<Book> fetched = s.createSelectionQuery("select b from Book b join fetch b.author where b.title = 'Alpha'", Book.class).getResultList();
                t.line("join fetch                : author initialized = " + Hibernate.isInitialized(fetched.get(0).author));
                assertThat(Hibernate.isInitialized(fetched.get(0).author)).isTrue();

                Long count = s.createSelectionQuery("select count(b) from Book b where b.author.name = :n", Long.class).setParameter("n", "Ann").getSingleResult();
                t.line("count over an association : " + count);
                assertThat(count).isEqualTo(2L);
            }
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                int updated = s.createMutationQuery("update Book b set b.pages = b.pages + 1 where b.pages is not null").executeUpdate();
                s.getTransaction().commit();
                t.line("createMutationQuery update: " + updated + " rows");
                assertThat(updated).isEqualTo(2);
            }
        }
    }

    @Test
    void statelessSession() {
        try (Db db = new Db(Author.class); Transcript t = new Transcript("12-cheat-stateless-session")) {
            try (StatelessSession s = db.sessionFactory.openStatelessSession()) {
                s.beginTransaction();
                for (int i = 1; i <= 3; i++) {
                    s.insert(new Author("user" + i + "@example.com", "User " + i));
                }
                s.getTransaction().commit();
                t.line("insert x3 (no persistence context) done");
            }
            try (StatelessSession s = db.sessionFactory.openStatelessSession()) {
                Author a1 = s.get(Author.class, 1L);
                Author a1again = s.get(Author.class, 1L);
                t.line("get twice -> same instance: " + (a1 == a1again) + " (a stateless session has no first-level cache)");
                assertThat(a1).isNotNull();
                assertThat(a1).isNotSameAs(a1again);
                t.line("rows in table: " + db.jdbc("select count(*) from Author"));
                assertThat(db.jdbc("select count(*) from Author")).containsExactly("3");
            }
        }
    }

    @Test
    void naturalId() {
        try (Db db = new Db(Author.class); Transcript t = new Transcript("13-cheat-natural-id")) {
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                s.persist(new Author("[email protected]", "Ann"));
                s.getTransaction().commit();
            }
            try (Session s = db.sessionFactory.openSession()) {
                db.clear();
                Author a = s.bySimpleNaturalId(Author.class).load("[email protected]");
                t.line("bySimpleNaturalId(...).load -> " + a.name);
                t.line("sql: " + db.sql.get(0));
                assertThat(a.name).isEqualTo("Ann");
                assertThat(db.sql.get(0)).contains("email");
            }
        }
    }

    @Test
    void softDelete() {
        try (Db db = new Db(Note.class); Transcript t = new Transcript("14-cheat-soft-delete")) {
            Long id;
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                Note n = new Note("remember");
                s.persist(n);
                id = n.id;
                s.getTransaction().commit();
            }
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                db.clear();
                s.remove(s.find(Note.class, id));
                s.getTransaction().commit();
                t.line("remove(note) ran: " + db.sql.get(db.sql.size() - 1));
                assertThat(db.sql.get(db.sql.size() - 1)).startsWith("update");
            }
            try (Session s = db.sessionFactory.openSession()) {
                t.line("find afterwards       : " + s.find(Note.class, id));
                t.line("row still in the table: " + db.jdbc("select * from Note"));
                assertThat(s.find(Note.class, id)).isNull();
                assertThat(db.jdbc("select count(*) from Note")).containsExactly("1");
            }
        }
    }

    @Test
    void recordEmbeddable() {
        try (Db db = new Db(Shop.class); Transcript t = new Transcript("15-cheat-record-embeddable")) {
            Long id;
            try (Session s = db.sessionFactory.openSession()) {
                s.beginTransaction();
                Shop shop = new Shop("Corner", new Address("1 Main St", "Pune"));
                s.persist(shop);
                id = shop.id;
                s.getTransaction().commit();
            }
            try (Session s = db.sessionFactory.openSession()) {
                Shop shop = s.find(Shop.class, id);
                t.line("loaded: " + shop.address);
                t.line("columns: " + db.jdbc("select column_name from information_schema.columns where table_name = 'SHOP' order by column_name"));
                assertThat(shop.address).isEqualTo(new Address("1 Main St", "Pune"));
            }
        }
    }
}

Source: CheatSheetTest.java.

persist(a)               -> id assigned on the object: 1
find(Author, id)         -> Ann  (1 select)
getReference(Author, id) -> initialized: false  (0 selects)
merge(detached)          -> returns a different instance: true, name now Ann Smith
findMultiple(ids 3)      -> 3 entries, missing id gives: null
remove(a)                -> find afterwards: null

Output: 10-cheat-session-api.txt. persist puts the id on the object you passed in. find runs one select. getReference in a fresh session runs none and returns an uninitialized proxy. merge returns a different, managed instance. findMultiple returns null in the slot of an id that does not exist.

named parameter           : [Beta]
?1 parameter              : [Alpha, Beta]
limit 2 offset 1 in HQL   : [Beta, Gamma]
order by ... nulls last   : [Beta, Alpha, Gamma]
getSingleResultOrNull()   : null
join fetch                : author initialized = true
count over an association : 2
createMutationQuery update: 2 rows

Output: 11-cheat-hql.txt. Selections go through createSelectionQuery(hql, Class) and updates through createMutationQuery(hql). limit, offset and nulls last are written in the HQL itself. getSingleResultOrNull() returns null instead of throwing.

insert x3 (no persistence context) done
get twice -> same instance: false (a stateless session has no first-level cache)
rows in table: [3]

Output: 12-cheat-stateless-session.txt. A stateless session has no first-level cache, so two get calls return two different instances.

bySimpleNaturalId(...).load -> Ann
sql: select a1_0.id,a1_0.email,a1_0.name from Author a1_0 where a1_0.email=?

Output: 13-cheat-natural-id.txt. bySimpleNaturalId(...).load(...) generates a select on the natural id column.

remove(note) ran: update Note set deleted=true where id=? and deleted=false
find afterwards       : null
row still in the table: [TRUE 1 remember]

Output: 14-cheat-soft-delete.txt. remove becomes an update of a deleted flag; the row stays in the table and find no longer returns it.

loaded: Address[street=1 Main St, city=Pune]
columns: [CITY, ID, NAME, STREET]

Output: 15-cheat-record-embeddable.txt. The record’s components become columns of the owning table, and the loaded value equals the original.

1. On 5.6.15, replace save, update, saveOrUpdate, delete, load, createSQLQuery and setFlushMode with the calls that compile on both versions.
2. Replace Criteria and org.hibernate.criterion with HQL.
3. Change the Maven coordinates to org.hibernate.orm:hibernate-core and every javax.persistence import to jakarta.persistence.
4. Replace @Where with @SQLRestriction, and look at every @Type(type = ...) and @GenericGenerator(strategy = ...).
5. Run schema validation against a copy of your real database and decide, column by column, whether to keep the old type or migrate it.
6. Check the id sequences: names and increments differ by default.
7. Run the tests and read the SQL.

No. In the test here a class annotated with javax.persistence.Entity compiled against 5.6.15 and failed against 7.4.14, and the jakarta.persistence version did the reverse. Every import has to change.

No. In the test here save, update, saveOrUpdate and delete no longer compile against 7.4.14. persist, merge and remove compiled on both 5.6.15 and 7.4.14, so you can switch before upgrading.

Not in the test here. Hibernate 7.4.14 with hbm2ddl validate refused a schema created by 5.6.15 for the same entity, reporting a bigint column where it expected numeric(21,0). Id sequences, enum, UUID, Instant and Duration columns all had different defaults on H2.

The old org.hibernate.Criteria and org.hibernate.criterion package are not: they did not compile against 7.4.14. I did not test the JPA Criteria API; an HQL query is the replacement that I verified.