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.
Changes in Behavior
This section describes changes in behavior that applications should be aware of.
Collections belonging to read-only entities
Previously, collections belonging to an entity loaded in read-only mode were not marked as read-only and could be modified. This behavior was surprising and significantly undermined the benefits of the read-only mode. A collection is now set to read-only when its owning entity is read-only, and modifications to the collection result in an error.
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.
Timeout exceptions and transaction rollback
Previously, when a query or a lock timeout occurred, Hibernate would throw a
QueryTimeoutException or LockTimeoutException respectively. However, the
Jakarta Persistence API specifies that if such timeouts cause the transaction
to be marked for rollback by the database platform, a PersistenceException
should be thrown instead. As of Hibernate 7.3, Hibernate now adheres to the
spec and throws the appropriate exception type.
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.