hibernate-orm/migration-guide.adoc

= 6.2 Migration Guide
:toc:
:toclevels: 4
:docsBase: https://docs.jboss.org/hibernate/orm/6.2
:userGuideBase: {docsBase}/userguide/html_single/Hibernate_User_Guide.html
:javadocsBase: {docsBase}/javadocs


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

* link:https://github.com/hibernate/hibernate-orm/blob/6.1/migration-guide.adoc[6.1 Migration guide]
* link:https://github.com/hibernate/hibernate-orm/blob/6.0/migration-guide.adoc[6.0 Migration guide]

== Default DDL type changes

=== UUID mapping changes on MariaDB

On MariaDB, the type code `SqlTypes.UUID` now by default refers to the DDL type `uuid`, whereas before it was using `binary(16)`.
Due to this change, schema validation errors could occur on existing databases.

The migration to `uuid` requires a migration expression like `cast(old as uuid)`.

To retain backwards compatibility, configure the setting `hibernate.type.preferred_uuid_jdbc_type` to `BINARY`.

=== UUID mapping changes on SQL Server

On SQL Server, the type code `SqlTypes.UUID` now by default refers to the DDL type `uniqueidentifier`, whereas before it was using `binary(16)`.
Due to this change, schema validation errors could occur on existing databases.

The migration to `uuid` requires a migration expression like `cast(old as uuid)`.

To retain backwards compatibility, configure the setting `hibernate.type.preferred_uuid_jdbc_type` to `BINARY`.

=== JSON mapping changes on Oracle

On Oracle 12.1+, the type code `SqlTypes.JSON` now by default refers to the DDL type `blob` and on 21+ to `json`, whereas before it was using `clob`.
Due to this change, schema validation errors could occur on existing databases.

The migration to `blob` and `json` requires a migration expression like `cast(old as blob)` and `cast(old as json)` respectively.

To get the old behavior, annotate the column with `@Column(definition = "clob")`.

This change was done because `blob` and `json` are way more efficient and because we don't expect wide usage of `SqlTypes.JSON` yet.

=== Column type inference for `number(n,0)` in native SQL queries on Oracle

Previously, since Hibernate 6.0, columns of type `number` with scale 0 on Oracle were interpreted as `boolean`, `tinyint`, `smallint`, `int`, or `bigint`,
depending on the precision.

Now, columns of type `number` with scale 0 are interpreted as `int` or `bigint` depending on the precision.

=== Removal of support for legacy database versions

This version introduces the concept of minimum supported database version for most of the database dialects that Hibernate supports. This implies that the legacy code for versions that are no longer supported by their vendors, has been removed from the hibernate-core module. It is, however, still available in the hibernate-community-dialects module.

The minimum supported dialect versions are as follows:

|===
|Dialect |Minimum supported version

|MySQL
|5.7

|SQL Server 2008
|10.0

|DB2
|10.5

|DB2i
|7.1

|DB2z
|12.1

|MariaDB
|10.3

|H2
|1.4.197

|Derby
|10.14.2

|Sybase
|16.0

|CockroachDB
|21.1

|PostgreSQL
|10.0

|Oracle
|11.2

|HSQLDB
|2.6.1
|===

=== Change enhancement defaults and deprecation

The `enableLazyInitialization` and `enableDirtyTracking` enhancement tooling options in the ANT task, Maven Plugin and Gradle Plugin,
as well as the respective `hibernate.enhancer.enableLazyInitialization` and `hibernate.enhancer.enableDirtyTracking` configuration settings,
switched their default values to `true` and the settings are now deprecated for removal without replacement.
See link:https://hibernate.atlassian.net/browse/HHH-15641[HHH-15641] for details.

The global property `hibernate.bytecode.use_reflection_optimizer` switched the default value to `true`
and the setting is now deprecated for removal without replacement. See link:https://hibernate.atlassian.net/browse/HHH-15631[HHH-15631] for details.