HHH-13101 - Document `hibernate.id.disable_delayed_identity_inserts` config setting.

documentation/src/main/asciidoc/userguide/appendices/Configurations.adoc

@@ -268,6 +268,13 @@ Users migrating from earlier versions using the legacy `hibernate_sequence` name
 This setting allows you to provide an instance or the class implementing the `org.hibernate.jpa.spi.IdentifierGeneratorStrategyProvider` interface,
 so you can provide a set of https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/id/IdentifierGenerator.html[`IdentifierGenerator`] strategies allowing to override the Hibernate Core default ones.
 
+`*hibernate.id.disable_delayed_identity_inserts*` (e.g. `true` or `false` (default value))::
+If true, inserts that use generated-identifiers (identity/sequences) will never be delayed and will always be inserted immediately.
+This should be used if you run into any errors with `DelayedPostInsertIdentifier` and should be considered a _temporary_ fix.
+Please report your mapping that causes the problem to us so we can examine the default algorithm to see if your use case should be included.
++
+The default value is `false` which means Hibernate will use an algorithm to determine if the insert can be delayed or if the insert should be performed immediately.
+
 ==== Quoting options
 
 `*hibernate.globally_quoted_identifiers*` (e.g. `true` or `false` (default value))::

documentation/src/main/asciidoc/userguide/chapters/domain/identifiers.adoc

@@ -231,6 +231,25 @@ If applications set this to false the resolutions discussed here will be very di
 The rest of the discussion here assumes this setting is enabled (true).
 ====
 
+[IMPORTANT]
+====
+In Hibernate 5.3, Hibernate attempts to delay the insert of entities if the flush-mode does not equal `AUTO`.
+This was slightly problematic for entities that used `IDENTITY` or `SEQUENCE` generated identifiers that were
+also involved in some form of association with another entity in the same transaction.
++
+In Hibernate 5.4, Hibernate attempts to remedy the problem using an algorithm to decide if the insert should
+be delayed or if it requires immediate insertion.  We wanted to restore the behavior prior to 5.3 only for
+very specific use cases where it made sense.
++
+Entity mappings can sometimes be complex and it is possible a corner case was overlooked.  Hibernate offers a
+way to completely disable the 5.3 behavior in the event problems occur with `DelayedPostInsertIdentifier`.  To
+enable the legacy behavior, set `hibernate.id.disable_delayed_identity_inserts=true`.
++
+This configuration option is meant to act as a _temporary_ fix and bridge the gap between the changes in this
+behavior across Hibernate 5.x releases.  If this configuration setting is necessary for a mapping, please open
+a JIRA and report the mapping so that the algorithm can be reviewed.
+====
+
 `AUTO` (the default):: Indicates that the persistence provider (Hibernate) should choose an appropriate generation strategy. See <<identifiers-generators-auto>>.
 `IDENTITY`:: Indicates that database IDENTITY columns will be used for primary key value generation. See <<identifiers-generators-identity>>.
 `SEQUENCE`:: Indicates that database sequence should be used for obtaining primary key values. See <<identifiers-generators-sequence>>.

migration-guide.adoc

@@ -9,6 +9,25 @@ earlier versions, see any other pertinent migration guides as well.
 
 == 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