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

Building

Starting with version 7.2, Gradle 9 and Java 25 are required to build the project. However, the produced artifacts are still compatible with Java 17 and the produced Gradle plugin is still compatible with Gradle 8.

New Features

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

Changes to API

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

Session.contains(String,Object) deprecated

The method contains(String,Object) of Session was deprecated. Use contains(Object) instead.

SharedSessionBuilder.noInterceptor()

The behavior of SharedSessionBuilder.noInterceptor() was changed to reflect its documented semantics.

@Jpa (hibernate-testing)

The following methods have been removed from the @Jpa test utility, located in the hibernate-testing project:

  • jpaComplianceEnabled()

  • queryComplianceEnabled()

  • transactionComplianceEnabled()

  • closedComplianceEnabled()

  • orderByMappingComplianceEnabled()

  • proxyComplianceEnabled()

  • cacheComplianceEnabled()

  • generatorScopeComplianceEnabled()

  • loadByIdComplianceEnabled()

The default value for these settings is still false.

To indicate a specific flag setting, or to override the generic value that was set with JpaComplianceSettings.JPA_COMPLIANCE, @Jpa 's integrationSettings array should be used.

Example:

@Jpa(annotatedClasses =
	...,
	integrationSettings = {
		// set all jpa compliance flags to true
		@Setting(name = JpaComplianceSettings.JPA_COMPLIANCE, value = "true"),
		// override or set a specific flag value to false
		@Setting(name = JpaComplianceSettings.JPA_PROXY_COMPLIANCE, value = "false")
	}
)

Changes to SPI

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

Registry Generic Signatures

Some operations of TypeConfiguration, JavaTypeRegistry, and BasicTypeRegistry had previously used unbound type parameters in the return type. The generic signatures of these methods have been changed for improved type safety.

AzureSQLServerDialect Deprecation

org.hibernate.dialect.AzureSQLServerDialect was deprecated; use org.hibernate.dialect.SQLServerDialect instead.

If you set hibernate.boot.allow_jdbc_metadata_access=false for offline startup, remember to also set the targeted database version through jakarta.persistence.database-product-version - this would be 16.0 for SQL Server 2022 or 17.0 for SQL Server 2025.

Changes in Behavior

Child Session Flush/Close Behavior

Session and StatelessSession which share transactional context with a parent now have slightly different semantics in regard to flushing and closing -

  • when the parent is flushed, the child is flushed

  • when the parent is closed, the child is closed

This led to a change in triggering of flush events for both -

  • SessionEventListener registrations

  • JFR events

In both cases, the events are now triggered regardless of whether any entities or collections were actually flushed. Each already carried the number of entities and the number of collections which were actually flushed. Previously, when no entities and no collections were flushed to the database no event was generated; the event is now generated and both values will be zero.

Interestingly, this now also aligns with handling for auto-flush events which already always triggered these events.

Child Session No-Interceptor Behavior

The behavior of noInterceptor() for SharedSessionBuilder and (the new) SharedStatelessSessionBuilder was aligned with the preexisting semantics of this method on SessionBuilder and StatelessSessionBuilder. The previous behavior may be recovered by calling noSessionInterceptorCreation().

JUnit BytecodeEnhancedTestEngine

With this version, BytecodeEnhancedTestEngine will be disabled by default. To be able to run the tests annotated with @BytecodeEnhanced, this engine has to be explicitly enabled via a system property:

hibernate.testing.bytecode.enhancement.extension.engine.enabled=true

For a Maven-based project this can be done as part of the failsafe/surefire plugin configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <systemPropertyVariables>
            <hibernate.testing.bytecode.enhancement.extension.engine.enabled>true</hibernate.testing.bytecode.enhancement.extension.engine.enabled>
            <!-- Any other system properties required by your tests -->
        </systemPropertyVariables>
        <!-- The rest of the testing plugin configuration -->
        <!-- ... -->
    </configuration>
</plugin>

While for a Gradle-based project this can be done in multiple ways, it essentially comes down to configuring the systemProperties of a Test task:

tasks.withType(Test.class) {
    // Enable bytecode enhanced engine:
    systemProperties.systemProperties['hibernate.testing.bytecode.enhancement.extension.engine.enabled'] = true
    // Any other test task configurations
    // ...
}

Also, this engine is expected to only work with the exact version of JUnit that org.hibernate.orm:hibernate-testing depends on. While it may work with other versions as well, there is no guarantee of that.

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.

Changes in Dependencies

This section describes changes to dependencies used by Hibernate ORM.

JUnit 6 update

Hibernate ORM test utils distributed as org.hibernate.orm:hibernate-testing are now based on JUnit 6.0. In general, this update is compatible with previous JUnit 5 versions unless the tests depended on the @BytecodeEnhanced extension.