hibernate-orm/migration-guide.adoc

= 5.4 Migration Guide
:toc:

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

== Background


== Known changes

=== Overriding Delayed Identity Insert Behavior

In Hibernate 5.3, we added support for `DelayedPostInsertIdentifier` behavior to be influenced based on the
`FlushMode` or `FlushModeType` values, in short enhancing Extended PersistenceContext support.  Unfortunately,
there were a few side effects that were recently reported with this change.

In Hibernate 5.4, we wanted to preserve as much of the 5.3 behavior as possible and only restore very specific
`DelayedPostInsertIdentifier` behavior for selected use cases.

We understand mappings can be complex and there very well could be a corner case we didn't consider.  In order
to make 5.4 as flexible with these changes as possible, we added a configuration option that you can use as a
_temporary_ solution to completely disable the 5.3 behavior, reverting it back to 5.2 and prior.

`hibernate.id.disable_delayed_identity_inserts=true`

If you find you need to use this configuration setting, be sure to report the mapping to us in a JIRA issue so
that we can review it and determine if the mapping corner case should be included in our algorithm since the
configuration setting is meant to bridge behavior support for this across a few releases.

=== Hibernate Spatial depends on JTS 1.6

Hibernate Spatial depends on the https://github.com/locationtech/jts[Java Topology Suite (JTS)]. In 5.4 this
 dependency has been upgraded to version 1.6. This implies a change in package naming:
 all `com.vividsolutions.jts.\*` packages have been renamed to `org.locationtech.jts.*`.

See https://github.com/locationtech/jts/blob/master/MIGRATION.md[the JTS Migration guide] for more information.

=== SQL Server JDBC Driver version upgrade to at least 6.1.2

Due to fixing https://hibernate.atlassian.net/browse/HHH-12973[HHH-12973], you need to upgrade the JDBC Driver version to at least 6.1.2. Due to https://github.com/Microsoft/mssql-jdbc/issues/91[this bug], the older versions of the SQL Server JDBC Driver cannot introspect the `INFORMATION_SCHEMA.SEQUENCES` without closing the database connection.
HHH-12820 Initialize the 5.4 migration guide 2018-07-18 05:40:12 -04:00			`= 5.4 Migration Guide`
HHH-10043 - Migration Guide 2015-08-20 15:29:48 -04:00			`:toc:`

HHH-12820 Initialize the 5.4 migration guide 2018-07-18 05:40:12 -04:00			`This guide discusses migration from Hibernate ORM version 5.3 to version 5.4. For migration from`
HHH-10043 - Migration Guide 2015-08-20 15:29:48 -04:00			`earlier versions, see any other pertinent migration guides as well.`

HHH-10664 - Prep 6.0 feature branch - merge hibernate-entitymanager into hibernate-core (test fixup) 2016-05-03 13:21:11 -04:00			`== Background`


prepare for 5.3.0.Beta1 2018-01-17 23:02:35 -05:00			`== Known changes`

HHH-13101 - Document `hibernate.id.disable_delayed_identity_inserts` config setting. 2018-11-14 11:14:30 -05:00			`=== Overriding Delayed Identity Insert Behavior`

			In Hibernate 5.3, we added support for `DelayedPostInsertIdentifier` behavior to be influenced based on the
			`FlushMode` or `FlushModeType` values, in short enhancing Extended PersistenceContext support. Unfortunately,
			`there were a few side effects that were recently reported with this change.`

			`In Hibernate 5.4, we wanted to preserve as much of the 5.3 behavior as possible and only restore very specific`
			`DelayedPostInsertIdentifier` behavior for selected use cases.

			`We understand mappings can be complex and there very well could be a corner case we didn't consider. In order`
			`to make 5.4 as flexible with these changes as possible, we added a configuration option that you can use as a`
			`_temporary_ solution to completely disable the 5.3 behavior, reverting it back to 5.2 and prior.`

			`hibernate.id.disable_delayed_identity_inserts=true`

			`If you find you need to use this configuration setting, be sure to report the mapping to us in a JIRA issue so`
			`that we can review it and determine if the mapping corner case should be included in our algorithm since the`
			`configuration setting is meant to bridge behavior support for this across a few releases.`

HHH-12144 - Add note to migration guide 2018-10-11 15:21:22 -04:00			`=== Hibernate Spatial depends on JTS 1.6`

			`Hibernate Spatial depends on the https://github.com/locationtech/jts[Java Topology Suite (JTS)]. In 5.4 this`
			`dependency has been upgraded to version 1.6. This implies a change in package naming:`
			all `com.vividsolutions.jts.\` packages have been renamed to `org.locationtech.jts.`.

			`See https://github.com/locationtech/jts/blob/master/MIGRATION.md[the JTS Migration guide] for more information.`

HHH-12973 - Inconsistent identity generation when using the default @SequenceGenerator with a database sequence having the increment size of 1 - add SQL Server JDBC Driver version upgrade note to migration guides 2018-10-12 05:55:25 -04:00			`=== SQL Server JDBC Driver version upgrade to at least 6.1.2`

			Due to fixing https://hibernate.atlassian.net/browse/HHH-12973[HHH-12973], you need to upgrade the JDBC Driver version to at least 6.1.2. Due to https://github.com/Microsoft/mssql-jdbc/issues/91[this bug], the older versions of the SQL Server JDBC Driver cannot introspect the `INFORMATION_SCHEMA.SEQUENCES` without closing the database connection.