5.3 Migration Guide
- Known changes
- Changes to positional query parameter handling
- Change in the
- Second-level cache provider SPI changes
- Statistics changes
- Drop hibernate-infinispan module
- EnhancementTask changes
- Many-to-one association in embeddable collection elements and composite IDs
- 5.3 → 6.0 compatibility changes
This guide discusses migration from Hibernate ORM version 5.2 to version 5.3. For migration from earlier versions, see any other pertinent migration guides as well.
Hibernate 5.3 adds support for the JPA 2.2 specification
Changes to positional query parameter handling
This really breaks down into 2 related changes:
Support for JDBC-style parameter declarations in HQL/JPQL queries has been removed. This feature has been deprecated since 4.1 and removing it made implementing the second change, so we decided to remove that support. JDBC-style parameter declaration is still supported in native-queries.
Since JPA positional parameters really behave more like named parameters (they can be repeated, declared in any order, etc.) Hibernate used to treat them as named parameters - it relied on Hibernate’s JPA wrapper to interpret the JPA setParameter calls and properly handle delegating to the named variant. This is actually a regression in 5.2 as it causes
For JDBC-style parameter declarations in native queries, we have also moved to using one-based
instead of zero-based parameter binding to be consistent with JPA. That can temporarily be
reverted by setting the
hibernate.query.sql.jdbc_style_params_base setting to
reverts to expecting zero-based binding.
Change in the
@TableGenerator stored value
In order to be compliant with the JPA specification, the sequence value stored by Hibernate 5.3 in the database table used by the
is the last generated value. Previously, Hibernate stored the next sequence value.
For backward compatibility, a new setting called
hibernate.id.generator.stored_last_used was introduced, which gives you the opportunity to fall back to the old Hibernate behavior.
Existing applications migrating to 5.3 and using the
Second-level cache provider SPI changes
Hibernate’s second-level cache SPI needed to be redesigned to match with expectations between Hibernate and the various caching providers. And the SPI did not really clarify the intention. These mis-matched expectations certainly had the potential to lead to bugs. Although it was originally slated for 6.0 to delay the SPI changes, we decided to back-port the work to 5.3 to address a number of bugs that could have been avoided with a clarified SPI.
The changes also allow the caching providers to perform serious optimizations based on the users configuration of domain data caching in Hibernate.
Details can be seen on the HHH-11356 Jira issue
One potential upgrade concern is any custom
org.hibernate.cache.spi.QueryCacheFactory was meant as a means to allow service providers the
ability to define query result caching, generally with more stale-tolerant query result invalidation handling.
However, the contract also bound it to the old second level cache contracts so they had to be
updated. Its responsibilities also changed so we also decided to "rename it" to
Another specific change to be aware of is accessing cache entries via
NaturalIdCacheStatistics#getEntries. These methods have been deprecated, however the new
caching SPI does not really require caching providers to support this. As of 5.3 these methods
inherently return an empty Map (
Collections#emptyMap). This has always been something that providers
did not implement "correctly" anyway
The change for HHH-11356 required changes in its consumers. One such consumer is the Hibernate Statistics system….
Drop hibernate-infinispan module
Support for using Infinispan as a Hibernate 2nd-level cache provider has been moved to the Infinispan project so
hibernate-infinispan module has been dropped.
A relocation pom which is pointing to
org.infinispan:infinispan-hibernate-cache dependency is still generated,
therefore, avoiding the need of updating any library dependency.
The relocation pom may be dropped in a future release.
The API of the
org.hibernate.tool.enhance.EnhancementTask Ant task was changed, specifically
#addFileset method was dropped in favor of
See details on the HHH-11795 Jira issue.
The main gist is that EnhancementTask was fixed (through a contribution) to actually work with
BytecodeProvider. Previously it had not. And part of fixing that required this
Many-to-one association in embeddable collection elements and composite IDs
A bug introduced in 4.3 caused many-to-one associations in embeddable collection elements and composite IDs to be eagerly fetched, even when explicitly mapped as lazy.
This bug does not affect many-to-one associations that are not in a composite ID or embeddable collection element.
In 5.3.2, this bug was fixed. As a result, such associations will be fetched as specified by their mappings.
Many-to-one associations mapped by using native HBM xml are lazy by default. In order to keep the associations eager in 5.3.2 and later, mappings will need to explicitly specify that they are non-lazy.
When mapped with annotations, many-to-one associations use
FetchType.EAGER by default.
Starting in 5.3.2, if an association is mapped with
FetchType.LAZY, the assocation will
be lazily fetched, as expected.
See details on the HHH-12687 Jira issue.
5.3 → 6.0 compatibility changes
The original driving force behind these series of changes is an effort to be as proactive as possible about designing compatibility between 5.3 and 6.0.
Type system changes
Use of NavigableRole, back-ported from 6.0 rather than plain String