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.
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.
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 |
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 -
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.