74 lines
3.9 KiB
Plaintext
74 lines
3.9 KiB
Plaintext
= 6.5 Migration Guide
|
|
:toc:
|
|
:toclevels: 4
|
|
:docsBase: https://docs.jboss.org/hibernate/orm
|
|
:versionDocBase: {docsBase}/6.5
|
|
:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
|
|
:javadocsBase: {versionDocBase}/javadocs
|
|
:fn-instant: footnote:instant[JDBC 4.2, curiously, does not define support for Instant to be directly marshalled through the driver.]
|
|
|
|
This guide discusses migration to Hibernate ORM version 6.5. For migration from
|
|
earlier versions, see any other pertinent migration guides as well.
|
|
|
|
* link:{docsBase}/6.4/migration-guide/migration-guide.html[6.4 Migration guide]
|
|
* link:{docsBase}/6.3/migration-guide/migration-guide.html[6.3 Migration guide]
|
|
* link:{docsBase}/6.2/migration-guide/migration-guide.html[6.2 Migration guide]
|
|
* link:{docsBase}/6.1/migration-guide/migration-guide.html[6.1 Migration guide]
|
|
* link:{docsBase}/6.0/migration-guide/migration-guide.html[6.0 Migration guide]
|
|
|
|
|
|
[[java-time]]
|
|
== 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,
|
|
|
|
[source]
|
|
----
|
|
hibernate.type.prefer_java_type_jdbc_types=false
|
|
----
|
|
|
|
It is expected the default will flip for 7.0.
|
|
|
|
[[query-cache-layout]]
|
|
== 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.
|
|
|
|
[[ddl-implicit-datatype-enum]]
|
|
== Datatype for enums
|
|
Hibernate ORM 6.5 now uses the `ENUM` datatype for `@Enumerated(EnumType.STRING)` enumeration mappings by default on H2,
|
|
just like link:{docsBase}/6.2/migration-guide/migration-guide.html#ddl-implicit-datatype-enum[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)")`.
|