Migration Guide from Hibernate 6.1 to 6.2

Migrating from Hibernate 6.1 to 6.2 introduces several significant changes and enhancements. This guide outlines the key changes and provides detailed instructions for a smooth migration.
Key Changes and Migration Steps
DDL Type Changes
OffsetTime Mapping Changes
OffsetTime
now depends on @TimeZoneStorage
and the hibernate.timezone.default_storage
setting. The default is now TimeZoneStorageType.DEFAULT
, meaning that if the database supports time zone types natively, SqlTypes.TIME_WITH_TIMEZONE
is used, mapping to time with time zone
.
Migration Steps
Update Schema:
ALTER TABLE tbl ALTER COLUMN time_col TYPE time with time zone USING cast(time_col AS time with time zone);
Retain Backward Compatibility:
hibernate.timezone.default_storage=NORMALIZE
UUID Mapping Changes on MariaDB and SQL Server
- MariaDB: The type code
SqlTypes.UUID
now refers touuid
. - SQL Server: The type code
SqlTypes.UUID
now refers touniqueidentifier
.
Migration Steps
MariaDB:
ALTER TABLE tbl ALTER COLUMN uuid_col TYPE uuid USING cast(uuid_col AS uuid);
SQL Server:
ALTER TABLE tbl ALTER COLUMN uuid_col TYPE uniqueidentifier USING cast(uuid_col AS uniqueidentifier);
Retain Backward Compatibility:
hibernate.type.preferred_uuid_jdbc_type=BINARY
JSON Mapping Changes on Oracle and H2
- Oracle 12.1+:
SqlTypes.JSON
now refers toblob
and on Oracle 21+ tojson
. - H2 1.4.200+:
SqlTypes.JSON
now refers tojson
.
Migration Steps
Oracle:
ALTER TABLE tbl ALTER COLUMN json_col TYPE json USING cast(json_col AS json);
H2:
ALTER TABLE tbl ALTER COLUMN json_col TYPE json USING cast(json_col AS json);
Retain Old Behavior:
@Column(definition = "clob")
private String jsonData;
Datatype for Enums
Enums are now stored as TINYINT
by default for enums with less than 128 entries. For more than 128 entries, SMALLINT
is used. On MySQL, enums use the ENUM
datatype by default.
Timezone and Offset Storage
The default storage for time zones is now DEFAULT
, which stores time zones if the database supports it. Otherwise, it normalizes to UTC.
Migration Steps
Revert to Old Behavior:
hibernate.timezone.default_storage=NORMALIZE
Byte[]/Character[] Mapping Changes
Handling of Byte[]
and Character[]
can now be configured:
- Disallow: Throws an error (default).
- Allow: Uses structured SQL types (
ARRAY
,SQLXML
). - Legacy: Uses
VARBINARY
andVARCHAR
, disallowing null elements.
Migration Steps
- Configure Handling:
hibernate.type.wrapper_array_handling=legacy
2. Update Domain Model:
@JavaType(ByteArrayJavaType.class)
private Byte[] byteArray;
Check Constraints for Boolean and Enum Mappings
Check constraints are now correctly generated for boolean and enum mappings.
UNIQUE Constraint for Optional One-to-One Mappings
UNIQUE constraints are now created for logical one-to-one associations marked as optional.
Migration Steps
- Add UNIQUE Constraint:
ALTER TABLE tbl ADD CONSTRAINT unique_constraint UNIQUE (fk_column);
Column Type Inference for number(n,0)
on Oracle
Columns of type number
with scale 0 are now interpreted as int
or bigint
depending on the precision.
Removal of Support for Legacy Database Versions
Support for legacy database versions has been moved to the hibernate-community-dialects
module.
CDI Handling Changes
A new boolean setting hibernate.cdi.extensions
controls the use of the CDI BeanManager
for resolving extensions.
Configure CDI Extensions
- Enable CDI Extensions:
hibernate.cdi.extensions=true
Enhancement Defaults and Deprecation
Defaults for enableLazyInitialization
and enableDirtyTracking
have been switched to true
and are now deprecated.
API / SPI / Internal Distinction
Ongoing cleanup of packages to distinguish between API, SPI, and internal contracts.
Changes in Integration Contracts (SPIs)
EntityPersister#lock
Changed from EntityPersister#lock(Object, Object, Object, LockMode, SharedSessionContractImplementor)
to EntityPersister#lock(Object, Object, Object, LockMode, EventSource)
.
EntityPersister#multiLoad
Changed to use EventSource
instead of SharedSessionContractImplementor
.
Native Query with Joins
A native query that uses a result set mapping requires unique select item aliases.
Example Query Update
Replace:
session.createNativeQuery(
"SELECT * FROM person p LEFT JOIN dog d on d.person_id = p.id", Person.class)
.getResultList();
With:
session.createNativeQuery(
"SELECT p.* FROM person p LEFT JOIN dog d on d.person_id = p.id", Person.class)
.getResultList();
Conclusion
Migrating to Hibernate 6.2 involves understanding and implementing changes in DDL type handling, enum storage, timezone management, and several other enhancements. By following the steps outlined in this guide, you can ensure a smooth and efficient transition to Hibernate 6.2.
This tutorial was generated using ChatGPT, specifically the Master Spring TER model. For more information, visit Master Spring TER.