This guide discusses migration to Hibernate ORM version 7.3. 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.3 series.

New Features

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

Changes to API

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

The obsolete @Columns annotation was removed, since this is no longer used.

Changes to SPI

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

Classmate removal

The dependency on Classmate was removed, which had a minor impact on certain SPIs. In particular, ClassmateContext was completely removed.

Raw types in JPA Bootstrap

Raw Map types were eliminated from the signatures of methods of the class org.hibernate.jpa.boot.spi.Bootstrap.

Changes in Behavior

This section describes changes in behavior that applications should be aware of.

Result deduplication

In Hibernate 6.x query result lists with duplicate results were handled in an ad hoc and inconsistent way by getSingleResult() and getSingleResultOrNull(). As of Hibernate 7.3, these methods always throw when the result list contains more than one element (which is faithful to the documented semantics of these methods). If automatic deduplication is required, use:

query.setResultListTransformer(ResultListTransformer.uniqueResultTransformer())

which collapses duplicate results according to value equality.

Envers association not-audited target mode

Previously, if an association of an Envers @Audited entity pointing to another @Audited entity was defined as:

@ManyToOne
@Audited(targetAuditMode = RelationTargetAuditMode.NOT_AUDITED)
private OtherEntity otherEntity;

the targetAuditMode = RelationTargetAuditMode.NOT_AUDITED setting was ignored, and when reading a historic version of the owning entity, the associated OtherEntity was also read from its historic audit table (at the relevant revision). As of Hibernate 7.3, the NOT_AUDITED setting is now respected: the associated OtherEntity is read from its current state, not from its historic audit table.

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.

Columns matched by @Version fields are now declared not null by default.

Changes in Dependencies

This section describes changes to dependencies used by Hibernate ORM.