migration-guide for 6.2 release

hibernate-core/src/main/java/org/hibernate/cfg/Environment.java

@@ -11,6 +11,7 @@ import java.io.InputStream;
 import java.util.Properties;
 
 import org.hibernate.HibernateException;
+import org.hibernate.Internal;
 import org.hibernate.Version;
 import org.hibernate.bytecode.spi.BytecodeProvider;
 import org.hibernate.internal.CoreMessageLogger;
@@ -128,8 +129,14 @@ import static org.hibernate.internal.log.DeprecationLogger.DEPRECATION_LOGGER;
  * </table>
  *
  * @see org.hibernate.SessionFactory
+ *
+ * @apiNote This is really considered an internal contract, but leaving in place in this
+ * package as many applications use it historically.  However, consider migrating to use
+ * {@link AvailableSettings} instead.
+ *
  * @author Gavin King
  */
+@Internal
 public final class Environment implements AvailableSettings {
 	private static final CoreMessageLogger LOG = Logger.getMessageLogger( CoreMessageLogger.class, Environment.class.getName());
 

migration-guide.adoc

@@ -1,19 +1,26 @@
 = 6.2 Migration Guide
 :toc:
 :toclevels: 4
-:docsBase: https://docs.jboss.org/hibernate/orm/6.2
+:docsBase: https://docs.jboss.org/hibernate/orm
-:userGuideBase: {docsBase}/userguide/html_single/Hibernate_User_Guide.html
+:versionDocBase: {docsBase}/6.2
-:javadocsBase: {docsBase}/javadocs
+:userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html
+:javadocsBase: {versionDocBase}/javadocs
+:fn-logical-1-1: footnote:[A "true" one-to-one mapping is one in which both sides use the same primary-key value and the foreign-key is defined on the primary-key column to the other primary-key column.  A "logical" one-to-one is really a many-to-one with a UNIQUE contraint on the key-side of the foreign-key.  See link:{docsBase}/6.2/userguide/html_single/Hibernate_User_Guide.html#associations for more information]
 
 
-This guide discusses migration from Hibernate ORM version 6.2. For migration from
+This guide discusses migration to Hibernate ORM version 6.2. For migration from
 earlier versions, see any other pertinent migration guides as well.
 
-* link:https://github.com/hibernate/hibernate-orm/blob/6.1/migration-guide.adoc[6.1 Migration guide]
+https://docs.jboss.org/hibernate/orm/6.0/migration-guide/migration-guide.html
-* link:https://github.com/hibernate/hibernate-orm/blob/6.0/migration-guide.adoc[6.0 Migration guide]
 
+* link:{docsBase}/6.1/migration-guide/migration-guide.html[6.1 Migration guide]
+* link:{docsBase}/6.0/migration-guide/migration-guide.html[6.0 Migration guide]
+
+
+[[ddl-changes]]
 == Default DDL type changes
 
+[[uuid-mariadv]]
 === UUID mapping changes on MariaDB
 
 On MariaDB, the type code `SqlTypes.UUID` now by default refers to the DDL type `uuid`, whereas before it was using `binary(16)`.
@@ -23,6 +30,7 @@ The migration to `uuid` requires a migration expression like `cast(old as uuid)`
 
 To retain backwards compatibility, configure the setting `hibernate.type.preferred_uuid_jdbc_type` to `BINARY`.
 
+[[uuid-sqlserver]]
 === UUID mapping changes on SQL Server
 
 On SQL Server, the type code `SqlTypes.UUID` now by default refers to the DDL type `uniqueidentifier`, whereas before it was using `binary(16)`.
@@ -32,6 +40,7 @@ The migration to `uuid` requires a migration expression like `cast(old as uuid)`
 
 To retain backwards compatibility, configure the setting `hibernate.type.preferred_uuid_jdbc_type` to `BINARY`.
 
+[[json-oracle]]
 === JSON mapping changes on Oracle
 
 On Oracle 12.1+, the type code `SqlTypes.JSON` now by default refers to the DDL type `blob` and on 21+ to `json`, whereas before it was using `clob`.
@@ -43,14 +52,42 @@ To get the old behavior, annotate the column with `@Column(definition = "clob")`
 
 This change was done because `blob` and `json` are way more efficient and because we don't expect wide usage of `SqlTypes.JSON` yet.
 
-=== Column type inference for `number(n,0)` in native SQL queries on Oracle
+[[implicit-datatype-enum]]
+=== Implicit SQL datatype for enums
 
-Previously, since Hibernate 6.0, columns of type `number` with scale 0 on Oracle were interpreted as `boolean`, `tinyint`, `smallint`, `int`, or `bigint`,
+Hibernate 6.1 changed the implicit SQL datatype for mapping enums from `TINYINT` to `SMALLINT` to account for
+Java supporting up to 32K enum entries which would overflow a `TINYINT`.  However, almost no one is developing
+enums with that many entries.  Starting in 6.2, the choice of implicit SQL datatype for storing enums is sensitive
+to the number of entries defined on the enum class.  Enums with more than 128 entries are stored as `SMALLINT` implicitly,
+otherwise `TINYINT` is used.
+
+
+[[logical-1-1-unique]]
+== UNIQUE constraint for optional one-to-one mappings
+
+Previous versions of Hibernate did not create a UNIQUE constraint on the database for
+logical{fn-logical-1-1} one-to-one associations marked as optional.  That is not correct
+from a modeling perspective as the foreign-key should be constrained as unique.  Starting in
+6.2, those UNIQUE constraints are now created.
+
+If this causes problems for an application, creation of the UNIQUE constraint can be skipped
+using `@jakarta.persistence.ForeignKey(NO_CONSTRAINT)`.
+
+Often the association can also be remapped using `@ManyToOne` + `@UniqueConstraint` instead.
+
+[[tz-offset]]
+== Timezone and offset storage
+
+
+== Column type inference for `number(n,0)` in native SQL queries on Oracle
+
+Since Hibernate 6.0, columns of type `number` with scale 0 on Oracle were interpreted as `boolean`, `tinyint`, `smallint`, `int`, or `bigint`,
 depending on the precision.
 
 Now, columns of type `number` with scale 0 are interpreted as `int` or `bigint` depending on the precision.
 
-=== Removal of support for legacy database versions
+[[database-versions]]
+== Removal of support for legacy database versions
 
 This version introduces the concept of minimum supported database version for most of the database dialects that Hibernate supports. This implies that the legacy code for versions that are no longer supported by their vendors, has been removed from the hibernate-core module. It is, however, still available in the hibernate-community-dialects module.
 
@@ -99,7 +136,7 @@ The minimum supported dialect versions are as follows:
 |2.6.1
 |===
 
-=== Change enhancement defaults and deprecation
+== Change enhancement defaults and deprecation
 
 The `enableLazyInitialization` and `enableDirtyTracking` enhancement tooling options in the ANT task, Maven Plugin and Gradle Plugin,
 as well as the respective `hibernate.enhancer.enableLazyInitialization` and `hibernate.enhancer.enableDirtyTracking` configuration settings,
@@ -109,7 +146,43 @@ See link:https://hibernate.atlassian.net/browse/HHH-15641[HHH-15641] for details
 The global property `hibernate.bytecode.use_reflection_optimizer` switched the default value to `true`
 and the setting is now deprecated for removal without replacement. See link:https://hibernate.atlassian.net/browse/HHH-15631[HHH-15631] for details.
 
-=== Changes in Integration contracts (SPIs)
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// API / internal
+[[api-internal]]
+== API / SPI / Internal distinction
+
+Dating back to Hibernate 5.x, we have been cleaning up packages to make the distinction between contracts
+which are considered an API, SPI and internal.  We've done some more work on that in 6.2 as well.
+
+[[api-internal-cfg]]
+=== org.hibernate.cfg package
+
+The `org.hibernate.cfg` package has been especially egregious in mixing APIs and internals historically.  The only
+true API contracts in this package include `org.hibernate.cfg.AvailableSettings` and `org.hibernate.cfg.Configuration`
+which have been left in place.
+
+Additionally, while it is considered an internal detail, `org.hibernate.cfg.Environment` has also been left in place
+as many applications have historically used it rather than `org.hibernate.cfg.AvailableSettings`.
+
+A number of contracts are considered deprecated and have been left in place.
+
+The rest have been moved under the `org.hibernate.boot` package where they more properly belong.
+
+
+[[api-internal-loader]]
+=== org.hibernate.loader package
+
+Most of the `org.hibernate.loader` package is really an SPI centered around `org.hibernate.loader.ast`
+which supports loading entities and collections by various types of keys - primary-key, unique-key,
+foreign-key and natural-key.  `org.hibernate.loader.ast` has already been previously well-defined
+in terms of SPI / internal split.
+
+
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// SPI
+
+[[spi]]
+== Changes in integration contracts (SPIs)
 
 SPI is a category of interfaces that we strive to maintain with more stability than internal APIs, but which might change from minor to minor
 upgrades as the project needs a bit of flexibility.
@@ -119,7 +192,8 @@ with other libraries which integrate with Hibernate ORM.
 
 During the development of Hibernate ORM 6.2 the following SPIs have seen some modifications:
 
-==== EntityPersister#lock
+[[spi-lock]]
+=== EntityPersister#lock
 
 Changed from `EntityPersister#lock(Object, Object, Object, LockMode, SharedSessionContractImplementor)` to `EntityPersister#lock(Object, Object, Object, LockMode, EventSource)`.
 This should be trivial to fix as `EventSource` and `SharedSessionContractImplementor` are both contracts of the `SessionImpl`; to help transition we recommend using
@@ -128,21 +202,26 @@ the methods `isEventSource` and `asEventSource`, available on the `SharedSession
 N.B. method `asEventSource` will throw an exception for non-compatible type; but because of previous restrictions all invocations to `lock` actually had to be compatible:
 this is now made cleared with the signature change.
 
-==== EntityPersister#multiLoad
+[[spi-multiLoad]]
+=== EntityPersister#multiLoad
 
 The same change was applieed to `multiLoad(Object[] ids, SharedSessionContractImplementor session, MultiIdLoadOptions loadOptions)`,
 now migrated to `multiLoad(Object[] ids, EventSource session, MultiIdLoadOptions loadOptions)`
 
 The same conversion can be safely applied.
 
-==== Executable#afterDeserialize
+[[spi-afterDeserialize]]
+=== Executable#afterDeserialize
 
 As in the previous two cases, the parameter now accepts `EventSource` instead of `SharedSessionContractImplementor`.
 
 The same conversion can be safely applied.
 
-=== Changes to JdbcType
+[[spi-JdbcType]]
+=== JdbcType#getJdbcRecommendedJavaTypeMapping()
 
 The return type of `JdbcType#getJdbcRecommendedJavaTypeMapping()` was changed from `BasicJavaType` to `JavaType`.
 Even though this is a source compatible change, it breaks binary backwards compatibility.
-We decided that it is fine to do this though, as this is a new minor version.
+We decided that it is fine to do this though, as this is a new minor version.
+
+