This guide discusses migration to Hibernate ORM version 7.1. For migration from earlier versions, see any other pertinent migration guides as well.

Requirements

See the website for the list of requirements for the 7.1 series.

New Features

See the website for the list of new features in the 7.1 series.

Changes to API

This section describes changes to contracts (classes, interfaces, methods, etc.) which are considered API.

LockOptions

7.0 begins the process of reducing the visibility of org.hibernate.LockOptions. This class was originally exposed as an API, even though it is more properly an SPI. From an API perspective, FindOption, LockOption and RefreshOption are much better ways to specify this information. The class itself, as well as API methods which expose it, have been deprecated.

However, 2 aspects of LockOptions have been completely removed. First, LockOptions previously defined a number of constants which have been removed. Secondly, the ability to define different LockModes for individual aliases has been removed.

ALias-specific LockModes was a very misleading feature, as Hibernate would only ever use the "greatest" LockMode.
We plan to add the ability to specify a list of aliases to be locked in a later release.
See https://hibernate.atlassian.net/browse/HHH-19664 for details.

Application code using org.hibernate.LockOptions should migrate to using FindOption, LockOption and RefreshOption to control the various aspects of locking. E.g.

LockOptions lockOptions = new LockOptions();
lockOptions.setLockMode(PESSIMISTIC_WRITE);
lockOptions.setTimeout(1000);
session.refresh(book, lockOptions);

can instead be written as

session.refresh(book,
    PESSIMISTIC_WRITE,
    Timeout.milliseconds(1000));

Bytecode Enhancement Options

We plan to remove two options of bytecode enhancement and have currently marked them as deprecated.

First is bidirectional association management. Applications should instead manage both sides of such associations directly as we have always recommended.

Second is a little-known feature called "extended" enhancement. Applications should instead use proper object-oriented encapsulation, exposing managed state via getters and setters.

Additionally, attempting to re-enhance a class with different options is no longer allowed and will result in a FeatureMismatchException.

The Gradle plugin configuration has changed slightly. When using the default setup:

hibernate { enhancement }

it should be updated to:

hibernate {
    enhancement {}
}

in order to properly enable Bytecode Enhancement.

Session#getLobHelper

The Session#getLobHelper method has been marked as deprecated in favor of the static Hibernate#getLobHelper and will be removed in a future major version.

WAIT, NO WAIT and SKIP LOCKED for H2

The for-update clause enhancements of H2 2.2.220 are now reflected in the Hibernate ORM dialect, allowing applications to use wait, no wait and skip locked options.

Changes to SPI

Force-increment Locking for Version with Custom Generator

A new event type (FORCE_INCREMENT) has been added to org.hibernate.generator.EventType to support OPTIMISTIC_FORCE_INCREMENT and PESSIMISTIC_FORCE_INCREMENT when used with @Version mappings with custom generators.

Pessimistic Locking

A number of changes have been made to pessimistic locking support.

  • Introduction of org.hibernate.dialect.lock.spi.LockingSupport which represents a Dialect’s support for pessimistic locking.

  • Introduction of org.hibernate.sql.ast.spi.LockingClauseStrategy to integrate into SQL AST translation.

  • Changed standard implementation of org.hibernate.dialect.lock.LockingStrategy for pessimistic locking to one using SQL AST.

  • Changes to LockOptions as already discussed.

More changes related to pessimistic locking are coming in later 7.x releases. We’ve opted to tackle these in stages since they all relate and build on top of each other. See https://hibernate.atlassian.net/browse/HHH-19551 for details.

JSON FormatMapper Enhancements

JSON mappings on Oracle 21+ will now try to leverage driver built-in OSON decoding to improve JSON parsing performance. In case of trouble, this can be disabled with the hibernate.dialect.oracle.oson_format_disabled configuration option.

Enhancement Option Granularity

The actual enhancements written into bytecode were previously allowed to vary by class and sometimes even by attribute. However, all Hibernate tooling only supported setting those "globally" per enhancement. To this end, all org.hibernate.bytecode.enhance.spi.EnhancementContext methods which determine whether certain aspects of enhancement are applied have changed to no longer accept class/attribute. Specifically:

  • doDirtyCheckingInline(UnloadedClass classDescriptor) → doDirtyCheckingInline()

  • doExtendedEnhancement(UnloadedClass classDescriptor) → doExtendedEnhancement()

  • doBiDirectionalAssociationManagement(UnloadedField field) → doBiDirectionalAssociationManagement()

See also Bytecode Enhancement Options.

Changes to DDL generation

This section describes changes to DDL generated by the schema export tooling. Such changes typically do not impact programs using a relational schema managed externally to Hibernate.

Automatic check constraints with single table inheritance mappings

Previously, the non-nullability of the column mapped by an attribute declared optional=false by a subclass in a single table inheritance hierarchy was not enforced by the database. Hibernate now automatically generates DDL check constraints to enforce the non-nullability of such columns.

Changes in Dependencies

This section describes changes to dependencies used by Hibernate ORM.

Inclusion of Agroal Pool

agroal-pool is now a transitive implementation (runtime) dependency of the hibernate-agroal module. Applications using hibernate-agroal no longer need to manually depend on it.