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 to uuid.
• SQL Server: The type code SqlTypes.UUID now refers to uniqueidentifier.

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 to blob and on Oracle 21+ to json.
• H2 1.4.200+: SqlTypes.JSON now refers to json.

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:

1. Disallow: Throws an error (default).
2. Allow: Uses structured SQL types (ARRAY, SQLXML).
3. Legacy: Uses VARBINARY and VARCHAR, disallowing null elements.

Migration Steps

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

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

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