migration-guide.adoc

7.4 Migration Guide

Table of Contents

• Requirements
• New Features
• Changes to API
• Changes to SPI
• Changes in Behavior
  • MySQL default max fetch depth
  • Join fetching for eager @Any mappings
  • Schema actions now executed even without mapped entities
• Changes to DDL generation
  • Unique constraints for @ElementCollection sets
  • @CreationTimestamp and @UpdateTimestamp columns inferred not-null
• Changes in Dependencies

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

New Features

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

Changes to API

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

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.

MySQL default max fetch depth

Previously, MySQLDialect defined a dialect-level default value of 2 for the hibernate.max_fetch_depth configuration property.

As of Hibernate ORM 7.4, this dialect-specific default has been removed. MySQL now behaves consistently with other dialects and relies on Hibernate’s general defaults or explicit user configuration.

Applications that relied on the previous implicit default should explicitly set hibernate.max_fetch_depth if required.

Join fetching for eager @Any mappings

An @Any discriminated association mapping defaults to fetch=EAGER. Previously, such eager @Any associations were always fetched using a separate SELECT statement, which was inefficient. Eager @Any associations are now join fetched by default when an entity is loaded by id.

Schema actions now executed even without mapped entities

Previously, if a persistence unit had no @Entity classes, all schema management actions (including import.sql execution) were silently skipped, even when explicitly configured via hbm2ddl.auto or jakarta.persistence.schema-generation.database.action.

As of Hibernate 7.4, schema actions are now processed regardless of whether any entities are mapped. This is the correct behavior, but it means that applications which have an import.sql file on the classpath by accident may now see it executed when it was previously ignored.

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.

Unique constraints for @ElementCollection sets

A unique constraint is now added to the table mapped by an @ElementCollection set where appropriate.

@CreationTimestamp and @UpdateTimestamp columns inferred not-null

A column mapped by a @CreationTimestamp or @UpdateTimestamp generator now has a NOT NULL constraint added automatically.

Changes in Dependencies

This section describes changes to dependencies used by Hibernate ORM.