= 5.6 Migration Guide
:toc:

This guide discusses migration from Hibernate ORM version 5.5 to version 5.6.

For migration from other versions, see https://github.com/hibernate/hibernate-orm/wiki/Migration-Guides .

== Known changes

This version is very similar to Hibernate ORM 5.5, with the exception of having removed some long standing deprecated features.

=== Javassist removed

It is no longer an option to choose Javassist as implementation used for the bytecode enhancement of entities.
Byte Buddy has been the default for some time, and Javassist has been deprecated for some time and now has been removed.

This should have no functional impact on applications; the only exception being that it's not longer valid to
configure `hibernate.bytecode.provider=javassist`: remove the property if you're using this.

A side effect is that Hibenate ORM no longer lists javassist among its dependencies.

=== Changes to the DDL type for CLOB in PostgreSQL81Dialect and its subclasses

As of 5.6.2, the default PostgreSQL DDL type for CLOB columns i.e. fields annotated with `@Lob` or with the type `java.sql.Clob`
will be the `oid` type whereas before, the type `text` was used. The `text` type does not support streaming data
and is, even if TOASTed, materialized eagerly by the server, which is not what one would expect for LOB types.

All PostgreSQL JDBC drivers unfortunately just store the `oid` it created for a `java.sql.Clob` into the `text` column.
Although reading back the value with the CLOB API works, PostgreSQL has no knowledge of the reference to the LOB,
because the `oid` is not known to PostgreSQL, leading to data loss when `vacuumlo` (the utility to clean up unused LOBs) runs.
To avoid the data loss, it is required to use the `oid` type so that `vacuumlo` can see the reference.

Updating to 5.6.2 does not require any schema or application changes by default, but we highly recommend
that you migrate existing `text` columns for LOBs to `oid` to prevent data loss due to the activity of `vacuumlo`.

[source,sql]
----
alter table test_entity
alter column clobfield
set data type oid using clobfield::oid
----

If you are overriding the `JdbcTypeDescriptor` for `CLOB` to use e.g. `VarcharTypeDescriptor` in a custom PostgreSQL dialect,
beware that you will also have to override the column type in the custom dialect, as with "pgjdbc",
it is not possible to read/write an `oid` column with the JDBC `ResultSet#getString/Statement#setString` methods.

[source,java]
----
registerColumnType( Types.CLOB, "text" );
----

Alternatively, you can remove the `JdbcTypeDescriptor` override and migrate to `oid` with

[source,sql]
----
alter table test_entity
alter column clobfield
set data type oid using lo_from_bytea(0, cast(clobfield as bytea))
----

The switch to `oid` might have a negative impact on performance for small values that are fetched often,
because the value is stored in a different file system page than the row, even for small values
The benefit of the `oid` type is that it allows streaming the content and reduces the row size.

Users that just want a large text type but don't care about streaming should use the Hibernate type `text`:

[source,java]
----
@Entity
public class TestEntity {

    @org.hibernate.annotations.Type( type = "text" )
    String clobField;

	//...
}
----

This will map to `java.sql.Types.LONGVARCHAR` for which Hibernate dialects register a DDL type that supports access
via the `ResultSet#getString/Statement#setString` methods i.e. in case of PostgreSQL the type `text`.

The `@Lob` annotation should only be used to force the use of the `ResultSet#getClob/Statement#setClob` JDBC driver methods,
which is in turn necessary for streaming data.