In Relation To

Back to home

Hibernate ORM 5.6.2.Final released

Posted by    |       Hibernate ORM Releases

Hibernate ORM version 5.6.2.Final is now available.

This is a maintenance release of the latest stable branch 5.6; speaking of branches, it’s worth highlight that our main branch is now pointing to the sources of the upcoming version 6.0.

Deprecations in prepation for Hibernate ORM 6

In version 5.6.1.Final we had marked some types as deprecated, with the goal of preparing you all for Hibernate ORM 6.

Among others, we had org.hibernate.EntityMode, org.hibernate.tuple.Tuplizer, org.hiberante.tuple.entity.EntityTuplizer, org.hibernate.tuple.component.ComponentTuplizer marked as deprecated in version 5.6.1.Final but many users highlighted that this deprecation was confusing as it’s not "actionable": since there is no replacement API yet, they had no way to resolve such deprecations other than ignoring them.

For this reason and even though that’s not necessarily how deprecations are intended, we decided to listen to feedback and are going to revert these deprecations; some of these have been resolved but a couple deprecations are still there at the time of releasing; most notably org.hibernate.annotations.Type is still marked as deprecated: we’ll fix that in the next micro.

In the meantime, no need to panic: it still is the best way to define a custom type mapping - the use of this deprecation warning is to call attention to it as this particular API will be different in version 6; it’s ok to ignore this for now.

Changes to the DDL type for CLOB in PostgreSQL dialects

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.

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.

registerColumnType(Types.CLOB, "text");

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

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:

@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.

Getting 5.6.2.Final, detailed changelogs

All details are available and up to date on the dedicated page on hibernate.org.

Full changelog for 5.6.2.Final.

Feedback, issues, ideas?

To get in touch, use the usual channels:

Back to top