125 lines
6.0 KiB
Plaintext
125 lines
6.0 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=true
|
|
----
|
|
|
|
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)")`.
|
|
|
|
|
|
[[jdbc-metadata-on-boot]]
|
|
== hibernate.boot.allow_jdbc_metadata_access
|
|
|
|
6.5 adds a new setting named `hibernate.boot.allow_jdbc_metadata_access` as a supported replacement for
|
|
the legacy `hibernate.temp.use_jdbc_metadata_defaults` setting which was only ever considered internal and
|
|
unsupported for use by applications (as should have been obvious from the name).
|
|
|
|
This setting controls whether Hibernate should be allowed to access the JDBC `DatabaseMetaData` during bootstrapping.
|
|
With this setting enabled (the default), Hibernate will access the `DatabaseMetaData` to perform some internal
|
|
configuration based on the reported capabilities of the underlying database. Disabling this setting requires
|
|
explicit settings for this configuration. At a minimum this includes:
|
|
|
|
* `hibernate.dialect` or `jakarta.persistence.database-product-name` to indicate the type of database
|
|
* `jakarta.persistence.database-product-version` to indicate the database version
|
|
|
|
|
|
|
|
[[sql-expectation]]
|
|
== SQL Execution Expectation
|
|
|
|
6.5 moves away from an enumeration approach to specifying the expected outcome of specific SQL executions to
|
|
a more flexible approach of directly specifying the `Expectation` implementation to use.
|
|
`ExecuteUpdateResultCheckStyle` and `ResultCheckStyle` approaches are still available, though deprecated.
|
|
|
|
|
|
[[uk-naming]]
|
|
== Unique Key Naming
|
|
|
|
Previous 6.x versions did not apply `ImplicitNamingStrategy` when determining the name of a unique key implicitly.
|
|
|
|
|
|
[[annotation-problems]]
|
|
== Annotation Problems
|
|
|
|
6.5 makes various problems in annotations errors (fail fast) as opposed to logged warnings.
|
|
|
|
|
|
[[annotation-processor-rename]]
|
|
== Annotation Processor Rename
|
|
|
|
The name of Hibernate's Annotation Processor has been changed to `org.hibernate.processor.HibernateProcessor`.
|
|
This change will not affect most users as such processors are normally discovered from the `javac` "processor path", but is important to know for users using the processor manually.
|
|
|
|
[[jakarta-data]]
|
|
== Jakarta Data
|
|
|
|
6.5 adds support for the Jakarta Data specification, though this support is considered tech preview as the specification is still being actively developed.
|
|
|