hibernate-orm/migration-guide.adoc

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

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

* link:{docsBase}/6.5/migration-guide/migration-guide.html[6.5 Migration guide]
* 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]

[[oracle-implicit-array-types]]
== Oracle implicit array types

The names for implicitly created array types on Oracle have slightly changed to account for converted types.
Previously, the naming of implicit array types was only using the Java type simple name which could conflict
when the same Java type is used with different JDBC type codes or converters.
To avoid name clashes, the naming of implicitly created array types now also includes
the preferred Java type simple name of the JDBC type in case the preferred Java type differs from the field type.
In case of converted types, the converter Java class simple name is used instead.

The array type for a persistent property of type `BigInteger[]` was previously `BigIntegerArray`
and would now be `BigIntegerBigDecimalArray`, because the preferred Java type for the `NUMERIC`/`DECIMAL` JDBC type is `BigDecimal`.
To specify a custom array type name, annotate the persistent property with `@Column(columnDefinition = "BigIntegerArray")`.

[[user-defined-type]]
== Changes to `UserDefinedType`

`UserDefinedType` was renamed to `UserDefinedObjectType` and everything except access to column information
was abstracted in a new interface named `UserDefinedType`. This was done to allow modelling dependencies between
named arrays, modeled as `UserDefinedArrayType` extending the new `UserDefinedType` interface,
and `UserDefinedObjectType` i.e. arrays of structs.

`UserDefinedType` was not explicitly annotated with `@Incubating` before,
but it was introduced for the incubating `@Struct` feature in ORM 6.2,
which made it effectively incubating as well. To make this more clear,
the types were now also explicitly marked as `@Incubating`.

The changes affect users which previously queried or created `UserDefinedType` in a `Namespace`.
Methods that return or operate on `UserDefinedType` have been marked as `@Incubating`
to make it clear that these contracts might still evolve.

Another change is to the already incubating `ColumnOrderingStrategy`,
where the argument type of `orderUserDefinedTypeColumns` was changed from `UserDefinedType` to `UserDefinedObjectType`.

[[array-contains-array-deprecation]]
== Subset check for arrays to use `array_includes`

Support for `array_contains()` to accept an array as element argument is deprecated and will emit a warning.
To check if an array is a subset of another array, use the `array_includes()` function,
or the new `INCLUDES` predicate i.e. `array INCLUDES subarray`.


[[merge-versioned-deleted]]
=== Merge versioned entity when row is deleted
Previously, merging a detached entity resulted in a SQL `insert` whenever there was no matching row in the database (for example, if the object had been deleted in another transaction).
This behavior was unexpected and violated the rules of optimistic locking.

An `OptimisticLockException` is now thrown when it is possible to determine that an entity is definitely detached, but there is no matching row.
For this determination to be possible, the entity must have either:

- a generated `@Id` field, or
- a non-primitive `@Version` field.

For entities which have neither, it's impossible to distinguish a new instance from a deleted detached instance, and there is no change from the previous behavior.