= 5.1 Migration Guide
:toc:

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

== Oracle12cDialect maps byte[] and Byte[] to BLOB

Previous versions of Hibernate have mapped `byte[]` and `Byte[]` to Oracle's `LONG RAW` data type (via the JDBC
LONGVARBINARY type).  Oracle have deprecated the `LONG RAW` data type for many releases - possibly as far back
as 8i.  Therefore it was decided to start having Hibernate map `byte[]` and `Byte[]` to `BLOB` for Oracle.

However, in the interest of backwards compatibility and not breaking existing applications it was also decided to
limit this change to just the Oracle12cDialect.  So starting in 5.1 applications using Oracle12cDialect and
implicitly mapping `byte[]` and `Byte[]` values will start seeing those handled as `BLOB` data rather than `LONG RAW`
data.  For existing applications that want to continue to use Oracle12cDialect and still continue to implicitly map
`byte[]` and `Byte[]` attributes to `LONG RAW`, there is a new configuration setting you can use to enable that:
`hibernate.dialect.oracle.prefer_longvarbinary`, which is false by default (map to `BLOB`).


== Changes to schema management tooling

The changes mainly focused on:

* Unifying handling of `hbm2ddl.auto` and Hibernate's JPA schema-generation support.
* Removing JDBC concerns from the SPI to facilitate true replacement (for OGM)

These changes will only be a migration concern for applications directly using any of the following classes:

* `org.hibernate.tool.hbm2ddl.SchemaExport`
* `org.hibernate.tool.hbm2ddl.SchemaUpdate`
* `org.hibernate.tool.hbm2ddl.SchemaValidator`
* `org.hibernate.tool.schema.spi.SchemaManagementTool` or any of its delegates


In 5.1.4, a new strategy for retrieving database tables was introduced that improves SchemaMigrator and SchemaValidator
performance. This strategy executes a single `java.sql.DatabaseMetaData#getTables(String, String, String, String[])`
call to determine if each `javax.persistence.Entity` has a mapped database table.
This strategy is the default, and uses the property setting `hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped`.
This strategy may require `hibernate.default_schema` and/or `hibernate.default_catalog` to be provided.

To use the old strategy, which executes a `java.sql.DatabaseMetaData#getTables(String, String, String, String[])` call for
each javax.persistence.Entity, use the property setting `hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually`.


=== Many-to-one association in embeddable collection elements and composite IDs

A bug introduced in 4.3 caused many-to-one associations in embeddable collection elements and
composite IDs to be eagerly fetched, even when explicitly mapped as lazy.

This bug does not affect many-to-one associations that are not in a composite ID or embeddable
collection element.

In 5.1.15, this bug was fixed. As a result, such associations will be fetched as specified
by their mappings.

Many-to-one associations mapped by using native HBM xml are lazy by default. In order to keep
the associations eager in 5.1.15 and later, mappings will need to explicitly specify that
they are non-lazy.

When mapped with annotations, many-to-one associations use `FetchType.EAGER` by default.
Starting in 5.1.15, if an association is mapped with `FetchType.LAZY`, the assocation will
be lazily fetched, as expected.

See details on the https://hibernate.atlassian.net/browse/HHH-12687[HHH-12687] Jira issue.