= 5.0 Migration Guide :toc: This guide discusses migration from Hibernate ORM version 4.3 to version 5.0. For migration from earlier versions, see any other pertinent migration guides as well. Several updates have been added to this document for changes that took affect after 5.0.0.Final was released. See <> for details migrating to later 5.0 releases. == Re-purposing of Configuration Configuration, historically, allowed users to iteratively add settings and mappings in any order and to query the state of settings and mapping information in the middle of that process. Which meant that building the mapping information could not effectively rely on any settings being available. This lead to many limitations and problems. Quite a few methods have been removed from Configuration. Be sure to see the User Guide chapter on bootstrapping for details. For applications that integrate with Hibernate via one or more APIs, this change might effect your integrations as well. == Short-naming In an effort to insulate applications from refactoring efforts, Hibernate has begun to recognize "short name" values for certain configuration settings. These are discussed in detail in the User Guide in the pertinent sections. Where available, we highly recommend using the short name for a setting value. == Transactions The transaction SPI underwent a major redesign as part of 5.0 as well. From a user perspective this generally only comes into view in terms of configuration. Previously applications would work with the different backend transaction stratagies directly via the `org.hibernate.Transaction` API. In 5.0 a level of indirection has been added here. The API implementation of `org.hibernate.Transaction` is always the same now. On the backend, the `org.hibernate.Transaction` impl talks to a `org.hibernate.resource.transaction.TransactionCoordinator` which represents the "transactional context" for a given Session according to the backend transaction strategy. Users generally do not need to care about the distinction. The change is noted here because it might affect your bootstrap configuration. Whereas previously applications would specify `hibernate.transaction.factory_class` and refer to a `org.hibernate.engine.transaction.spi.TransactionFactory` FQN, with 5.0 the new contract is `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` and is specified using the `hibernate.transaction.coordinator_class` setting. See `org.hibernate.cfg.AvailableSettings.TRANSACTION_COORDINATOR_STRATEGY` JavaDocs for additional details. The following short-names are recognized: `jdbc`::(the default) says to use JDBC-based transactions (`org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorImpl`) `jta`::says to use JTA-based transactions (`org.hibernate.resource.transaction.backend.jta.internal.JtaTransactionCoordinatorImpl`) See the User Guide for additional details. == Type handling * Migrated `org.hibernate.metamodel.spi.TypeContributor` and `org.hibernate.metamodel.spi.TypeContributions` to `org.hibernate.boot.model.TypeContributor` and `org.hibernate.boot.model.TypeContributions` * Built-in `org.hibernate.type.descriptor.sql.SqlTypeDescriptor` implementations no longer auto-register themselves with `org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistry`. Applications using custom SqlTypeDescriptor implementations extending the built-in ones and relying on that behavior should be updated to call `SqlTypeDescriptorRegistry#addDescriptor` themselves. * The JDBC type for "big_integer" (org.hibernate.type.BigIntegerType) properties has changed from java.sql.Types,NUMERIC to java.sql.Types.BIGINT. This change was reverted in 5.0.1.Final. See <> for details. * For ids defined as UUID with generation, for some databases it is required to explicitly set the `@Column( length=16 )` in order to generate BINARY(16) so that comparisons properly work. * For EnumType mappings defined in hbm.xml where the user wants name-mapping (`javax.persistence.EnumType#STRING`) the configuration must explicitly state that using either the `useNamed` (true) setting or by specifying the `type` setting set to the value 12 (VARCHAR JDBC type code). == Naming strategies Historically Hibernate provided just a singular contract for applying a "naming strategy". Starting in 5.0 this has been split into 2 distinct contracts: * `ImplicitNamingStrategy` - is used whenever a table or column is not explicitly named to determine the name to use. * `PhysicalNamingStrategy` - is used to convert a "logical name" (either implicit or explicit) name of a table or column into a physical name (e.g. following corporate naming guidelines) == Changed setting defaults * Default value for `hibernate.id.new_generator_mappings` setting changed to true for 5.0. See `org.hibernate.cfg.AvailableSettings#USE_NEW_ID_GENERATOR_MAPPINGS` javadocs. * The default ImplicitNamingStrategy (`hibernate.implicit_naming_strategy`) has changed to the JPA-compliant one. See `org.hibernate.cfg.AvailableSettings.IMPLICIT_NAMING_STRATEGY` javadocs for details. If you experience problems migrating dues to implicit table or column names you may want to specify the legacy strategy (`legacy-hbm` \ `org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyHbmImpl`). * `hibernate.jdbc.batch_versioned_data` default value is now true; Oracle dialects set this property to false, except for Oracle12cDialect == Misc * `cfg.xml` files are again fully parsed and integrated (events, security, etc) * properties loaded from `cfg.xml` through EntityManagerFactory did not previously prefix names with "hibernate." this is now made consistent. * `Configuration` is no longer `Serializable` * `org.hibernate.dialect.Dialect.getQuerySequencesString` expected to retrieve catalog, schema, and increment values as well * removed AuditConfiguration in preference for new `org.hibernate.envers.boot.internal.EnversService` * changed AuditStrategy method parameters from (removed) AuditConfiguration to (new) EnversService * Moving `org.hibernate.hql.spi.MultiTableBulkIdStrategy` and friends to new `org.hibernate.hql.spi.id` package and sub-packages * Complete redesign of "property access" contracts * Valid `hibernate.cache.default_cache_concurrency_strategy` setting values are now defined via `org.hibernate.cache.spi.access.AccessType#getExternalName` rather than the `org.hibernate.cache.spi.access.AccessType` enum names; this is more consistent with other Hibernate settings == Deprecations * Removed the deprecated `org.hibernate.cfg.AnnotationConfiguration` * Removed deprecated `org.hibernate.id.TableGenerator` id-generator * Removed deprecated `org.hibernate.id.TableHiLoGenerator` (hilo) id-generator * Deprecated `org.hibernate.id.SequenceGenerator` and its subclasses * Added a new dedicated "deprecation logger" to consolidate logging for deprecated uses. == Changed/Moved contracts * `org.hibernate.integrator.spi.Integrator` contract changed to account for bootstrap redesign * Extracted `org.hibernate.engine.jdbc.env.spi.JdbcEnvironment` from `JdbcServices`; created `org.hibernate.engine.jdbc.env` package and moved a few contracts there. * Introduction of `org.hibernate.boot.model.relational.ExportableProducer` which will effect any `org.hibernate.id.PersistentIdentifierGenerator` implementations * Changed to signature of `org.hibernate.id.Configurable` to accept `ServiceRegistry` rather than just `Dialect` [[migration-updates]] === Migration from 5.0.0.Final to 5.0.1.Final As of 5.0.1.Final, the JDBC type for "big_integer" (`org.hibernate.type.BigIntegerType`) properties has been changed back from `java.sql.Types.BIGINT` to `java.sql.Types.NUMERIC`. This is consistent with earlier versions (pre-5.0.0.Final). See https://hibernate.atlassian.net/browse/HHH-10053[HHH-10053] for details. === Migration from 5.0.1.Final to 5.0.2.Final As of 5.0.2.Final, usage of JPQL KEY() for an `Map` key that is an entity results in the addition of an inner join with the entity table. Earlier versions only referenced the entity ID and did not add an inner join. See https://hibernate.atlassian.net/browse/HHH-10537[HHH-10537] for details. === Migration from 5.0.2.Final to 5.0.3.Final As of 5.0.3.Final, when using an `AttributeConverter` for an enum, queries must refer to the enum value (e.g., MyEnum.TYPE1). Queries that refer to a literal that is the "converted" value (e.g., returned by AttributeConverter#convertToDatabaseColumn) will cause a failure. See https://hibernate.atlassian.net/browse/HHH-10282[HHH-10282] for details. === Migration from 5.0.3.Final to 5.0.8.Final As of 5.0.8.Final, 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 has 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.0.8.Final 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`).