75 lines
3.8 KiB
Plaintext
75 lines
3.8 KiB
Plaintext
= 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_long_raw`, 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`.
|
|
|
|
== Changes to Java compatibility
|
|
|
|
Versions 5.1.0.Final through 5.1.3.Final ensure Java 6 compatibility.
|
|
|
|
Versions through 5.1.16.Final ensure Java 7 compatibility.
|
|
|
|
As of 5.1.17.Final, Java 8 is required.
|
|
|
|
See details on the https://hibernate.atlassian.net/browse/HHH-13126[HHH-13126] Jira issue.
|
|
|
|
== 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.
|