Skip to content

Latest commit

 

History

History
73 lines (55 loc) · 3.86 KB

migration-guide.adoc

File metadata and controls

73 lines (55 loc) · 3.86 KB
Raw

6.5 Migration Guide

Table of Contents

This guide discusses migration to Hibernate ORM version 6.5. For migration from earlier versions, see any other pertinent migration guides as well.

Java Time Handling

6.5 adds support for marshalling Java Time objects directly through the JDBC driver as defined by JDBC 4.2. In previous versions, Hibernate would handle Java Time objects using java.sql.Date, java.sql.Time or java.sql.Timestamp references as intermediate forms.

Another behavioral change with this is handling for timezones. OffsetDateTime, OffsetTime and ZonedDateTime all encode explicit timezone information. With direct marshalling, Hibernate simply passes along the value as-is. In the legacy behavior, since the java.sql variants do not encode timezone information, Hibernate generally has to specially handle timezones when converting to those intermediate forms.

For 6.5 this behavior is disabled by default. To opt-in,

hibernate.type.prefer_java_type_jdbc_types=false

It is expected the default will flip for 7.0.

Query cache layout change

In Hibernate ORM 6.0 the query cache layout changed from a "shallow" representation of entities and collections, to a "full" representation. This was done to enable to re-materialize join fetched data from just the query cache data.

Storing the full data in the query cache leads to a higher memory consumption, which in turn might also hurt application throughput due to a higher garbage collection activity.

Hibernate ORM 6.5 introduces means to configure the query cache layout globally via the hibernate.cache.query_cache_layout property, and also for an entity type or persistent collection with the @QueryCacheLayout annotation.

The global hibernate.cache.query_cache_layout setting defaults to the AUTO value, which will automatically choose SHALLOW or FULL for an entity/collection, depending on whether the entity/collection is cacheable.

Applications that want to retain the FULL cache layout that Hibernate ORM 6.0 used should configure the global property hibernate.cache.query_cache_layout=FULL. Applications that want the cache layout that Hibernate ORM 5 and older versions used should configure the global property hibernate.cache.query_cache_layout=SHALLOW.

Note that even with the shallow cache layout, the association eagerness implied through join fetches will be respected, and associations will be eagerly initialized, so there is no change of behavior when choosing a different cache layout.

Datatype for enums

Hibernate ORM 6.5 now uses the ENUM datatype for @Enumerated(EnumType.STRING) enumeration mappings by default on H2, just like ORM 6.2 already started doing for MySQL/MariaDB.

The change is backwards compatible, though schema validation might produce an error now as the expected type is enum, whereas it was varchar of char before. To revert to the original mapping, annotate the enum attribute with @JdbcTypeCode(SqlTypes.VARCHAR) or @Column(columnDefinition = "varchar(255)").