8.0 Migration Guide

One specific requirement change that is important to call out is the move to from Jakarta Persistence version 3.2 to 4.0 which has a number of impacts, many of which are discussed below.

See this issue for more details.

Register package metadata using MetadataSources.addPackageDescriptor(String) or addPackageDescriptor(Package), and module metadata using addModuleDescriptor(String) or addModuleDescriptor(Module). The former addPackage and addModule methods remain as deprecated forwarding aliases.

Explicit package registration now requires a resolvable package-info.class. Bootstrap fails if the descriptor is missing, including for an existing package without package-info and when using the deprecated addPackage aliases. Remove registrations that do not identify a descriptor, or supply the intended descriptor. Implicit package annotation lookup from a class continues to tolerate absence.

A class input may no longer name package-info or module-info. For example, replace <class>com.acme.package-info</class> with <package-descriptor>com.acme</package-descriptor> in persistence.xml. This check also applies to older XML documents upgraded by Hibernate’s reader. Use JPA’s managed package/module descriptor APIs for programmatic configuration and its separate explicit/complete descriptor lists for container integrations. Registering a descriptor contributes its annotations without enrolling classes in its package or module.

Scanner results contain separate class, package, module, and mapping-resource inventories. The Jandex scanner uses selected archives as the candidate inventory, including when a prebuilt index is supplied. The supplied index may contribute annotation definitions, but cannot enroll resources outside those archives. jpaScan() excludes root discovery when exclude-unlisted-classes is true or omitted; listed JARs and the root standard mapping resource are still considered.

SessionFactory.getFilterDefinition(String) and Filter.getFilterDefinition() now return the API interface org.hibernate.engine.FilterDefinition. Their deprecations have been removed. The interface exposes the filter name, parameter names, default condition, automatic enablement, and load-by-key flag. The existing SPI class implements this interface, so the returned objects and the behavior for unknown filter names are unchanged.

The changed return types are a binary compatibility break: callers compiled against the old API declarations must be recompiled. Source code assigning the result to org.hibernate.engine.spi.FilterDefinition must use the API interface or migrate to SPI access if it needs JDBC mappings, parameter resolvers, or argument processing. See Filter definition API/SPI split.

The deprecated Session.replicate() methods and the associated ReplicationMode enum have been removed. There is no direct replacement. For some import or overwrite workflows, consider StatelessSession#upsert(Object).

Jakarta Persistence now defines a contract for "stateless" processing, named EntityAgent, similar to Hibernate’s StatelessSession. Hibernate’s StatelessSession now implements EntityAgent. 2 methods on EntityAgent clash with methods already defined on StatelessSession -

In both cases, StatelessSession has been changed to match the EntityAgent signatures.

One of the biggest changes in Jakarta Persistence 4.0 is the better modeling of "queries" into selections (TypedQuery) and mutations (its new Statement contract), aligning closely with Hibernate’s already existing SelectionQuery and MutationQuery contracts. At the same time, it deprecated all "operation methods" from its "raw" Query contract.

Hibernate’s Query contracts implement the Jakarta Persistence ones, so changes were needed here.

Another impact is that @NamedQuery and @NamedNativeQuery (as well as Hibernate’s variants) may no longer be used to define mutation queries -

The entire org.hibernate.transform package, which was deprecated since 6.0, has been deleted. This includes Transformers, AliasToBeanResultTransformer, AliasToBeanConstructorResultTransformer, AliasToEntityMapResultTransformer, and ToListResultTransformer.

Use org.hibernate.query.TupleTransformer (a @FunctionalInterface) as a direct replacement. Since it is a functional interface, lambdas can be used inline:

For bean-based result transformation (formerly Transformers.beanTransformer()), use HQL/JPQL dynamic instantiation (select new MyDto(…​)) or a @jakarta.persistence.ConstructorResult mapping instead. A TupleTransformer lambda also works well for simple DTO projections:

Historically, both Hibernate and Jakarta Persistence have defined timeouts as integer values. Confusingly, Hibernate generally used second precision while Jakarta Persistence used millisecond precision. Starting in 3.2, Jakarta Persistence added a new Timeout class which helps alleviate this potential confusion. Originally this new Timeout type was not exposed on any API directly, so there was no impact from an API perspective. However, this has changed a bit in 4.0 where Timeout is now exposed on certain APIs. This causes a signature conflict with a few of Hibernate API methods; as part of fixing those conflicts, it was decided to change all exposures of timeout in Hibernate APIs to use Timeout as this helps clarify these confusions.

As part of its support for "entity graphs", Hibernate’s org.hibernate.graph.AttributeNode contract extends the Jakarta Persistence jakarta.persistence.AttributeNode. Starting in version 4.0, Jakarta Persistence has "fixed" the use of raw types for the AttributeNode#getSubgraphs and AttributeNode#getKeySubgraphs methods. Hibernate has therefore needed to do the same in its org.hibernate.graph.AttributeNode.

Jakarta Persistence has changed/fixed the type signature of methods in the Criteria API which return Join and Fetch based on the String name of attributes. This can lead to compilation issues if an application uses these methods in certain ways.

The API for ProcedureCall and ProcedureOutputs has been redesigned for a number of reasons, mostly -

The four enums which are implementors of org.hibernate.FindMultipleOption have been moved as inner enums of org.hibernate.FindMultipleOption itself :

These enums were previously incubating, except for org.hibernate.BatchSize which is now marked as deprecated.

The @GenericGenerator annotation was deprecated in Hibernate 6.5. Instead of removing it completely, we have modernized it and reversed its deprecation. Code still using @GenericGenerator must adapt to its reworked definition.

The hibernate.mapping.default_list_semantics setting and MappingSettings.DEFAULT_LIST_SEMANTICS constant are deprecated for removal in ORM 9.0. Use @DefaultListSemantics on a package or module instead.

For example, replace hibernate.mapping.default_list_semantics=LIST with the following declaration in each applicable package-info.java, or with the equivalent annotation on module-info.java:

Use BAG instead of LIST to retain bag semantics in an annotated scope. Package defaults override module defaults and do not extend to subpackages. Inherited attributes use the package and module of their declaring type; embedded attributes use those of the embeddable. When migrating a persistence-unit-wide setting, cover all applicable declaring packages or modules before removing the setting.

During the transition, the setting remains a fallback where neither annotation applies. Explicit use logs a deprecation warning even when an annotation overrides its effect. With no annotation or configured default, Hibernate continues to use BAG.

This replacement preserves the existing classification rules: explicit mappings take precedence, and lists with retrieval ordering or unowned to-many associations do not acquire an implicit order column. See the User Guide for the complete decision tree.

The venerable @OptimisticLock annotation was deprecated in favor of the new JPA-standard @ExcludedFromVersioning annotation.

Previous versions of Hibernate did not respect the <delimited-identifiers> element of orm.xml. This is now fixed.

With the addition of static queries to Jakarta Persistence comes a requirement for the Jakarta Persistence provider to discover Jakarta Data repository interfaces. When Hibernate is started via a PersistenceConfiguration, discovery is impossible, and so Jakarta Data repository interfaces must be explicitly registered with the configuration:

Previously, generated Jakarta Data Repository implementation classes were named with a trailing underscore. These classes are now named with a leading underscore to avoid collision with Jakarta Persistence static query methods. Thus, to directly instantiate a Jakarta Data Repository implementation, client code must now use:

This change does not affect code which obtains a repository by injection.

The annotation processor now propagates security annotations from the jakarta.annotation.security package (@DeclareRoles, @DenyAll, @PermitAll, @RolesAllowed, @RunAs) from repository interfaces to generated implementations. Previously, only @InterceptorBinding annotations were propagated.

Hibernate now integrates Hibernate Accessor for property value access. PropertyAccess implementations must implement the new getPropertyValueAccessor() method, returning a PropertyValueAccessor for the mapped attribute. There is no default implementation of this method; custom implementations must be updated and recompiled.

Use the appropriate PropertyValueAccessor factory for the access pattern, such as standard() for a reader/writer pair or map() for map-backed properties. The existing getGetter() and getSetter() methods remain part of the contract, but implementing those methods alone is no longer sufficient. Integrations must preserve their property’s read, write, and insert-time access semantics through the new accessor. PropertyValueAccessor is currently incubating.

Dialect extension contracts have been reorganized and explicitly classified using @SPI. Custom dialects must update imports and overrides to the current contracts, including the focused org.hibernate.dialect.lock.spi, org.hibernate.dialect.pagination.spi, and org.hibernate.dialect.mutation.spi packages where applicable. Use supported strategy contracts and factories instead of implementations in internal packages.

Extend Dialect or another type explicitly classified with SPI.Role.IMPLEMENT. A built-in dialect being available for selection does not by itself make it a supported subclass base. The USE, IMPLEMENT, and SUPPLY roles are independent, and compatibility expectations for non-incubating SPIs apply within one X.Y release family.

See the Dialect Provider Guide for supported extension points, migration examples, and provider validation tooling.

Custom implementations of CascadeStyle and CascadingAction are no longer "supported". They were never well-supported anyway. These contracts, now in org.hibernate.cascade.spi, are internal strategies rather than extension points. The CascadeStyles.registerCascadeStyle() registration method has been removed, and the cascade coordinator rejects custom actions.

Integrations must remove custom cascade registrations and use Hibernate’s built-in cascade styles. There is no replacement extension contract for custom cascade styles or actions; application-specific propagation of persistence operations must be implemented explicitly.

Enhancer.enhanceClient(String, byte[]) performs client field-access rewriting separately from managed-class enhancement. Its default implementation reports unsupported client enhancement, so existing enhancer implementations continue to work when it is unused. HibernatePersistenceProvider.getClientClassTransformer(PersistenceUnitInfo, Map) exposes an independent Jakarta transformer for containers. Targets must already have compatible managed enhancement from tooling, or the container must arrange it before defining them. When both transformations apply to a class, managed enhancement precedes client enhancement. A client may reference another class scheduled for later managed enhancement. Runtime client enhancement can be used with runtime managed enhancement disabled when tooling has already enhanced the targets. Requesting the client transformer does not register either transformer.

Gradle, Maven, and Ant accept enableClientEnhancement, defaulting to false. enableExtendedEnhancement remains a deprecated alias. When both are set, the new name wins, including explicit false. Client classes no longer receive a managed-enhancement marker simply because client enhancement was requested. Targets must be scheduled for managed enhancement or already carry compatible enhancement; known skipped or incompatible targets fail during enhancement instead of producing unavailable accessor calls. XML mapping recognition is unchanged, and reflection and method-handle accesses are outside the client transformation.

EnhancementContext, DefaultEnhancementContext, and EnhancementContextWrapper have been replaced by independent EnhancementModel, EnhancementOptions, and EnhancementEnvironment contracts. DefaultEnhancementModel supplies the existing annotation-based interpretation. Discovery and metadata belong to an EnhancementSession, not to the model or options.

BytecodeProvider implementations must replace getEnhancer(context) with createEnhancementSession(model, environment). There is no compatibility adapter. Direct EnhancerImpl construction is replaced by session creation as well:

Environments resolve bytecode without defining application classes and may use a custom byte source instead of a loader. The Byte Buddy provider also accepts a borrowed EnhancerClassLocator when creating a session. Sessions do not close borrowed environments, locators, or class loaders.

Call invalidateMetadata() between passes which replace class resources. This clears bytecode and getter caches while retaining discovered persistence classifications. Close or invalidate only when no session operations are active. Closing a session makes all of its enhancers unusable.

The paired JPA transformer factories share discovery and metadata when called on the same HibernatePersistenceProvider and PersistenceUnitInfo instances, for the same defining loader and bytecode-provider instance. Each transformer retains its own enhancer and generation options. The PersistenceUnitInfo.addTransformer bootstrap path remains independent.

org.hibernate.engine.spi.FilterDefinition remains SPI and now implements the API interface org.hibernate.engine.FilterDefinition. Its constructors, JDBC parameter mappings, managed parameter resolvers, and argument processing remain unchanged. The public API getters no longer return the SPI class.

Integrations requiring the SPI definition should use:

SessionFactoryImplementor is in org.hibernate.engine.spi and retains its SPI return type. Internal FilterImpl access also retains its covariant SPI return; FilterImpl is not a supported provider access path. For an enabled Filter, use its name to look up the SPI definition through SessionFactoryImplementor.

The central SQL AST and translator SPIs are no longer incubating, including the translator factories and typed requests, JdbcParameterFactory, and the JdbcOperations builders. Their supported SPI roles now carry the normal compatibility expectations within an X.Y release family. No signatures or provider implementation requirements change as part of this stabilization.

QueryTransformer, SqlAstTranslator.renderNamedSetReturningFunction(), and SetReturningFunctionType remain incubating. Separate execution, mapping-model mutation, and result-processing contracts retain their existing lifecycle status.

Many changes were needed across various SPIs to accommodate the new Graph-based ActionQueue, focused around the new org.hibernate.action.queue.spi package which primarily defines -

Main SPI touch points include -

The dependency on Classmate was removed, which had a minor impact on certain SPIs. In particular, ClassmateContext was completely removed.

Raw Map types were eliminated from the signatures of methods of the class org.hibernate.jpa.boot.spi.Bootstrap.

Hibernate uses a number of implementations of its NamedQueryMemento contract to model "named queries". Starting in version 3.2, Jakarta Persistence added the TypedQueryReference contract intended to serve the much the same goal. Hibernate’s NamedQueryMemento implementations were changed to extend from TypedQueryReference.

In version 4.0, Jakarta Persistence has added some additional methods to TypedQueryReference which now conflict with some of Hibernate’s existing methods requiring a rename. Notably, the addition of TypedQueryReference#getParameterTypes caused conflict’s with Hibernate’s NamedSqmQueryMemento#getParameterTypes. To address this conflict, we’ve renamed the NamedSqmQueryMemento method to #getAnticipatedParameterTypes.

Jakarta Persistence clarifies that scanning is the responsibility of the container, rather than the provider. To that effect, the scanning SPI, and related ArchiveDescriptor SPI, have been rewritten. During "EE bootstrap", Hibernate no longer performs scanning. Instead, the jakarta.persistence.spi.PersistenceUnitInfo has been augmented to make it clear that the container passes in any classes discovered during scanning.

Hibernate does still provide this SPI for use by containers - Wild Fly for example takes advantage of this.

Hibernate also uses this scanning SPI when applications use HibernatePersistenceConfiguration bootstrapping and supply the root and/or non-root URLs.

The incubating ActionQueue.clearFromFlushNeededCheck(int) method has been replaced by an opaque checkpoint and restore contract:

An ActionQueueCheckpoint belongs to the queue instance which created it and does not expose the queue’s internal list or graph representation. Queue implementations must preserve all work registered before the checkpoint. Work registered afterward is retained when it represents durable persistence-context state, including entity inserts, entity deletes, orphan removals, and orphan collection removals. Flush-derived entity updates and ordinary collection work may be discarded only while their source state remains intact and can reproduce equivalent work during a later required flush.

Collection mutation registration now uses the queue-neutral addCollectionMutation(CollectionMutationInput) method. The collection-specific addAction(CollectionRecreateAction), addAction(CollectionRemoveAction), addAction(CollectionUpdateAction), and addAction(QueuedOperationCollectionAction) overloads have been removed from the incubating ActionQueue SPI. Queue implementations may lower the semantic input to these legacy action forms internally, but they are no longer the common registration vocabulary.

Collection mutation interpretation, including semantics-specific delta production, is now associated with CollectionSemantics through the new default getCollectionMutationInterpreter() method. Custom semantics remain source compatible and use the conservative compatibility interpreter unless they override this association. PersistentCollection likewise has new default methods for exposing queued commands, a mutation generation, and the post-snapshot initialization step.

Custom collection wrappers which apply queued commands during afterInitialize() should instead retain them until afterInitializationSnapshot(). Hibernate captures the database-loaded state between these calls and then applies and clears queued commands, ensuring that an initialized collection has no queued commands while its snapshot still represents the persisted comparison baseline. Wrappers derived from AbstractPersistentCollection inherit this sequencing automatically.

The SessionLazyDelegator class has been made abstract, and its constructor that accepted a Supplier<Session> removed, in order to align it with how the new StatelessSessionLazyDelegator` is implemented. Consumers of this class must extend it and implement the abstract delegate() method, thus providing the required Session to it.

Interceptor, previously considered an API simply because it was not yet classified, is classified as an SPI with the IMPLEMENT and SUPPLY roles. Implementing its callbacks and supplying an instance to Hibernate remain supported. Hibernate continues to invoke them during session operations.

The interceptor registration methods on SessionBuilder, StatelessSessionBuilder, their shared-session variants, CommonBuilder, CommonSharedBuilder, SessionFactoryBuilder, and Configuration are now SPI supply points instead of API.

These classification changes do not change Java signatures or runtime behavior. Existing implementations and registration calls require no source changes. The affected contracts now carry the SPI compatibility promise within an X.Y release family, instead of the API promise across a major version.

The SessionFactoryOptions.getInterceptor() and getStatelessInterceptorImplementorSupplier() methods have been removed, along with their declarations on AbstractDelegatingSessionFactoryOptions. Both methods forced immediate resolution of the configured Interceptor, which bypassed CDI-managed bean lifecycles and could no longer reflect a session factory’s interceptor configuration now that interceptors may be resolved as CDI beans.

Use SessionFactoryOptions.getConfiguredInterceptor() instead, which reports how the interceptor was configured (instance, global, session-scoped, or supplied) without resolving any bean. To obtain the actual factory-level interceptor, use SessionFactoryImplementor.getInterceptorStrategy().getFactoryInterceptorBean(), which returns a ManagedBean<? extends Interceptor> resolved lazily on first access to getBeanInstance().

EntityInitializer now has a default getFilteredAssociationKey(RowProcessingState) method. It exposes the stored association key when a restriction hides the target. The default returns null, so existing implementations remain source compatible. Custom entity initializers which represent restricted targets as null must supply this information during hydration to participate in the stored-reference preservation described below. EmbeddableInitializer.collectFilteredAssociations() contributes hidden references directly to the owning entity’s state using the supplied shared mapping metadata. It must return the supplied state unchanged when there is no additional evidence. Custom embeddable initializers must implement this hook when they contain restricted associations. Custom entity persisters must supply the shared metadata via EntityPersister.getFilteredAssociationMapping(). Hibernate’s standard initializers and entity persisters manage this automatically.

TableUpdateBuilder implementations must implement setColumnInclusion() and setRowKnownToExist(). The first limits assignments, including generated assignments, to the permitted columns. The second requires an update of an existing row instead of an optional-row insert or upsert when stored values have been omitted. Standard builders implement both operations. Builders extending AbstractTableUpdateBuilder inherit column inclusion and can consult isRowKnownToExist() when choosing the mutation form.

Internal subclasses overriding UpdateCoordinatorStandard.performUpdate() or analyzeUpdateValues() must forward the additional FilteredAssociationMutation argument. performUpdate() also receives a boolean indicating eligibility for the update variant cache. Passing the same mutation view through the operation avoids reconstructing it or looking up the persistence-context entry twice.

AbstractCollectionPersister is an internal implementation class. Its protected applyWhereFragments() method which accepts a TableGroup now also accepts a boolean useQualifier parameter immediately before SqlAstCreationState. Custom collection persisters overriding this method must update their signature and forward this argument when calling the superclass implementation.

The fixes for HHH-13537 and HHH-21017 correct how embeddables inherit their access type.

Embeddable elements of an @ElementCollection and embeddable map keys now inherit the access type of the class declaring the collection attribute, instead of the access type of the owning entity’s identifier. An attribute-level @Access override on the identifier no longer changes the access type inherited by these embeddables. This also applies when the collection is declared by a mapped superclass or a containing embeddable, and the inherited access type propagates to nested embeddables.

For example, if an entity uses field access but overrides its identifier to use property access, its embeddable collection elements now use field access by default. Previously, Hibernate incorrectly used property access, potentially causing bootstrap failures when the embeddable had no accessor methods.

Additionally, an attribute-level @Access override on an @Embedded, @EmbeddedId, or collection attribute now controls only access to that attribute. The embedded state inherits the containing class’s access type independently of the override. This applies to singular embeddables, collection elements, and embeddable map keys in both element collections and relationship maps.

For example, a field-accessed entity may use @Access(AccessType.PROPERTY) on the getter of an embedded attribute or element collection. Hibernate uses that getter to access the attribute, but uses field access for the embeddable’s state by default. Previously, the attribute override also caused the embeddable to use property access.

Applications that relied on the previous behavior should declare the intended access type explicitly on the embeddable using @Access(AccessType.PROPERTY) or @Access(AccessType.FIELD). An explicit access type on the embeddable continues to take precedence. If the same embeddable is used in multiple contexts that require different access types, review those usages before applying a class-level override.

This change aligns with the expected Jakarta Persistence behavior.

The following bootstrap messages now use the dedicated org.hibernate.orm.info logging category:

Both messages retain their existing message IDs and INFO level. Update any logging configuration or filters targeting these messages to use org.hibernate.orm.info. This category allows applications and containers to suppress bootstrap information independently of other core and connection-pooling messages.

Persisting an entity currently scheduled for deletion unschedules that deletion per the Jakarta Persistence specification. Hibernate now logs “Unscheduling entity deletion {details}” at DEBUG level under the org.hibernate.orm.event.unschedule-deletion category, isolating it to make it easier to enable logging for that single message.

Persistence behavior is unchanged.

When hibernate.xml_mapping_enabled=false, native bootstrap now skips access to mapping XML resources and JAXB binding. Previously, MetadataSources and Configuration still read and bound mapping XML, then excluded the bindings from metamodel building. Missing or malformed mapping XML therefore no longer causes bootstrap to fail when XML mapping processing is disabled.

Set this option before registering XML mappings, for example before calling addResource() or addFile(). Native registration uses the setting available at the time of the call. Disabling XML later does not undo binding that has already occurred, and mappings skipped while disabled are not replayed if XML is enabled later.

XML mapping resource, file, and jar references in hibernate.cfg.xml are also skipped when XML mappings are disabled, for both native and JPA bootstrap. The configuration document itself is still read, and its class and package mapping references still apply.

Native bootstrap now recognizes legacy javax.persistence. connection settings when normalizing settings for the standard service registry. Previously, this normalization supplied Hibernate connection settings from jakarta.persistence. aliases only; JPA bootstrap already recognized the legacy aliases.

The newly recognized aliases are:

An existing Hibernate connection setting takes precedence over its Jakarta alias, which takes precedence over its legacy javax.persistence.* alias. For the datasource setting, all Jakarta aliases are considered before legacy aliases; within each namespace, the non-JTA datasource takes precedence over the JTA datasource. Existing JPA bootstrap source precedence is unchanged.

Review native bootstrap configuration for stale legacy connection settings, which may now take effect when no corresponding Hibernate or Jakarta setting is present. Prefer the jakarta.persistence.* names when migrating legacy configuration.

The following fixes change behavior applications may observe after upgrading:

The default value of hibernate.type.java_time_use_direct_jdbc is now true. Previously, Hibernate converted java.time values to legacy java.sql representations before passing them to JDBC. Hibernate now uses java.time values directly where the configured dialect reports support for the Java type. For unsupported types, Hibernate falls back to the legacy JDBC representation and logs the driver/database limitation.

Applications should verify temporal value handling with their JDBC driver when upgrading, particularly where they rely on the previous conversion behavior. Set hibernate.type.java_time_use_direct_jdbc=false to retain the legacy behavior.

The legacy lock cascade style and the CascadeStyles.LOCK and CascadingActions.LOCK constants have been removed. Legacy hbm.xml mappings that specify cascade="lock", either alone or in a comma-separated list, now fail with an unsupported cascade style error.

Remove lock from these cascade declarations, omitting the declaration if no other cascade styles remain. Applications that need to lock associated entities should explicitly request the required lock on each entity instead of relying on lock cascading or use JPA "extended locking".

Hibernate now warns on boot when it detects persistent fields declared final in entity or embeddable classes that will need to be set through reflection. Reflective mutation of final fields is deprecated starting with JDK 26 and will be denied in a future JDK version.

To resolve these warnings:

The behavior of this check is controlled by the configuration property hibernate.mapping.final_persistent_fields, which accepts the values warn (the default), error (fail on boot), and ignore (suppress the check).

See the User Guide for details.

Hibernate now applies a target entity’s @SQLRestriction, and enabled filters declared with @FilterDef(applyToLoadByKey = true), consistently when fetching @ManyToOne and @OneToOne associations. This includes eager and lazy fetching, entity queries, fetch joins, find(), and entity graphs. Previously, a SQL restriction could hide a join-fetched target while leaving a lazily fetched target visible. An applicable filter could instead cause EntityFilterException during eager fetching or an EntityNotFoundException when initializing a lazy reference.

A target excluded by an applicable restriction is now represented as null. Applications must handle this null value instead of relying on those exceptions. This is also possible for an association declared optional = false or mapped to a non-nullable foreign key. The Java value describes the visible association, while the database may still contain a non-null reference. An explicit inner fetch join still excludes an owner whose target does not satisfy the restriction. Use a left fetch join to retain that owner with a null association.

The default value of applyToLoadByKey remains false. A filter declared on the target entity does not begin affecting loading by key merely because it is enabled for entity queries. @SQLRestriction remains unconditional and cannot be disabled. The change does not extend to @Any fetching, which may still throw EntityFilterException.

An @SQLUpdate statement retains its fixed parameter layout when an in-memory generated value, such as @UpdateTimestamp, requires dynamic update processing internally. Hibernate now binds every updateable attribute required by the custom statement, including unchanged attributes. This corrects missing or misplaced parameter bindings in the graph mutation queue and matches the legacy mutation queue. It applies independently of association filtering. Combining @DynamicUpdate and @SQLUpdate on the same entity remains unsupported.

When rendering a collection-element @SQLRestriction, Hibernate now qualifies an unambiguous mapped column using the table which declares it. This fixes restrictions on collections of JOINED subclasses which refer to a column stored in a superclass table, as described in HHH-12016. The same qualification applies to mapped columns stored in a @SecondaryTable, for both one-to-many and many-to-many collections. The qualification handles quoted column names and case differences in unquoted names. Unmapped or ambiguous column names retain the existing default qualification. This does not introduce an explicit alias declaration facility for @SQLRestriction.

When moving a collection between owners or roles requires both removal of its old state and creation of its new state, Hibernate now invokes the collection-remove interceptor hook before the legacy collection-recreate hook. The corresponding Hibernate collection events and semantic mutation completion are likewise remove-first. Integrations must not retain the previous assumption that the recreate interceptor hook runs before the remove hook.

Collection post-events, cache handling, successful statistics, and queued-operation finalization are now tied to semantic collection-mutation completion instead of to the last row operation produced during decomposition. This ensures that grouped, reordered, and batched row work completes the correct collection lifecycle and that failed physical work suppresses successful completion handling.

A collection mutation which produces no SQL now completes directly after its semantic work is sealed; Hibernate no longer creates a SQL-shaped no-op solely to carry its post-event. Consequently, applications must not rely on a global order between pre/post collection events for unrelated collections. Each mutation’s pre-event still precedes its post-event, and a post-event still follows all physical work belonging to that mutation.

Jakarta Persistence owner update callbacks are coordinated once per owner and flush. When entity and non-inverse collection work both contribute to an applicable owner update, one @PreUpdate callback is invoked and one @PostUpdate callback is delayed until all contributing entity and collection post-events have been delivered. Collection create or remove work associated with owner insert/delete lifecycle does not by itself establish update-callback applicability.

When no transaction is active (autocommit), Hibernate now correctly releases the connection after statement execution if the configured ConnectionReleaseMode is set to AFTER_TRANSACTION. Previously, with DELAYED_ACQUISITION_AND_RELEASE_AFTER_TRANSACTION connection handling mode, JDBC resources and the physical connection were held until an explicit call to afterTransaction() or closing the session, even though in autocommit mode each statement is effectively its own transaction.

This change ensures that JDBC connections are promptly returned to the pool after each statement when there is no active transaction, preventing potential resource leaks.

As a consequence, accessing LOB locators (i.e. java.sql.Blob or java.sql.Clob typed attributes) outside of an active transaction will no longer work and result in an exception on most dialects. Previously this appeared to work only because the connection happened to remain open; however, there were no transactional isolation guarantees — the data read from the LOB could have already been modified by another transaction.

Note that this only affects entity attributes mapped as java.sql.Blob or java.sql.Clob, since these types rely on a JDBC locator that requires a live connection. Attributes mapped as byte[] or String are always eagerly materialized when the result set is read, and are not affected by this change. Similarly, some dialects that always use materialized LOB access are also unaffected.

Applications that use Blob or Clob typed attributes must access them within an active transaction:

A null element of an inverse @OneToMany list mapped with @OrderColumn again leaves a gap in the order column, so that the element is read back as null and the elements after it keep their list positions.

Since 6.2 the order column was instead written compacted, and a list persisted as [a, null, b] was stored with the index values 0,1 rather than 0,2 and loaded back as [a, b], silently shifting the elements after the null. Applications that came to rely on that compaction — for example by treating the reloaded list size as the number of non-null elements — will now see the null elements preserved across a round-trip, as they were through 5.x and 6.1.

Element collections are unaffected: a null element of an @ElementCollection list has never been persisted, and such lists still load back without it.

Jakarta Persistence 4.0 specifies that constraints from Jakarta Validation annotations, such as @NotNull, @Size, @Digits and others, should influence the generated DDL schema. For example, a property annotated @NotNull will result in a non-nullable column.

Previously, this behavior required explicitly setting the validation mode to DDL (a Hibernate-specific extension to the JPA ValidationMode enum).

As a result:

As described in What’s New and SPI Changes, 8.0 changes how Hibernate coordinates work needed for flushing. This new coordinator can often lead to different SQL or SQL being performed in different order. The legacy strategy remains temporarily available by configuration using

A HQL query like:

now returns a detached collection without flattening.

In previous versions of Hibernate, such queries were accepted, and due to an undocumented and unsupported behavior, resulted in an implicit join and flattening of the collection. To recover this previous undocumented behavior, the singular form of the functions may be used:

The behavior of Hibernate’s handling for creating a ProcedureCall / StoredProcedureQuery with multiple result set mappings has been changed to fix a long-standing bug and comply with the Jakarta Persistence specification. Hibernate now interprets the multiple mappings as one per result available from the procedure. E.g.

A final field of an entity is now treated as if it were annotated @Immutable, that is, it is excluded from dirty checking and from SQL UPDATE statements. In order to eliminate the possibility of "silent" changes in behavior, attempts to modify the value of a final fields using the merge() method are rejected. If a field of an entity can actually be updated via merge(), the field must be declared non-final.

Jakarta Persistence now defines a series of overloaded EntityHandler.get() methods as corollaries to EntityHandler.find(). These methods are defined to throw an EntityNotFoundException rather than return null. This operates quite differently from the older Hibernate Session.get() methods which

Applications which use(d) Session.get() should be aware of this change in behavior.

As discussed in Scanning above, Hibernate no longer performs scanning during "EE bootstrap". It is expected by Jakarta Persistence that the container perform the scanning prior to bootstrapping Hibernate.

Calls to EntityGraph.removeAttributeNode() and EntityGraph.removeAttributeNodes() now behave in specification compliant way - when the graph is used as a "load graph", removing an attribute "suppresses inclusion of an attribute mapped for eager fetching".

Jakarta Persistence has clarified that listener-style callback classes (@EntityListeners) may define multiple methods for a given event type -

Using <E> as a generic type for the signatures, it says -

Be aware that creating a Cat, with the above model, will result in calls to both postInsert(Animal) and postInsert(Cat); and that creating a Dog, both postInsert(Animal) and postInsert(Dog).

On databases with built-in support for row-level security, Hibernate now uses row-level security to enforce the visibility rules implied by discriminator-based multi-tenancy. This requires specific DDL which the schema management tooling is responsible for generating.

To recover the previous behavior, where discriminator-based multi-tenancy rules were not enforced by the database, set the configuration property hibernate.multi_tenant.rls_enabled=false.

Hibernate now restricts generated mutation SQL by tenant and checks tenant ownership before changing secondary tables or collections. Stateless updates and deletes reject detached entities with a missing or mismatched tenant identifier before executing SQL. The root tenant is exempt from these restrictions.

Root tenant read operations now bypass the second-level cache. Mutations performed by the root tenant invalidate cache entries belonging to the actual owning tenant.

It has always been illegal to call the Hibernate session from an Interceptor or JPA entity lifecycle callback, but Hibernate has never previously enforced this, opening the door to undefined behavior in programs which did not respect this restriction.

Hibernate now throws IllegalStateException if the session is accessed in an unsafe way from a callback.

JPA 4 specifies that EntityExistsException should be thrown on any sort of unique key violation that occurs while inserting an entity, which means that Hibernate now throws this exception type in some cases where ConstraintViolationException was previously thrown.

After the introduction of EntityAgent, the Hibernate StatelessSession now throws the exception types mandated by the JPA specification. Previously, it threw native exception types.

StatelessSession.update() and EntityAgent.update() now leave the version invariant when only attributes annotated @ExcludedFromVersioning have been modified.

As required by JPA 4.0, Parameter.getParameterType() now throws IllegalStateException instead of returning null when the Java type is unknown. This can occur for native SQL parameters before binding, or HQL parameters whose type cannot be inferred. Binding a value with an explicit Java type establishes the parameter type, even when the value is null.

With JPA bootstrap, a query result type mismatch now produces IllegalArgumentException instead of QueryTypeMismatchException.

CUBRIDDialect now requires CUBRID 10.2 or later, the oldest version still supported by the vendor, and declares several capability flags explicitly for 10.2. Two of these are visible at runtime.

getNullOrdering() is now SMALLEST, which matches CUBRID’s native ordering (NULL first when ascending and last when descending). Queries that relied on the previous inherited default may order NULL values differently.

Pessimistic locking now produces a FOR UPDATE clause. The dialect previously returned an empty lock string, so PESSIMISTIC_READ and PESSIMISTIC_WRITE had no effect.

The default value of FindMultipleOption.SessionCheckMode has been changed from DISABLED to ENABLED.

This means that Session#findMultiple() and Session#getMultiple() now check the persistence context by default before querying the database. Identifiers for entities already managed in the current session will not be sent to the database, and entities marked for removal will be replaced with null in the result (see RemovalsMode).

To restore the previous behavior, pass FindMultipleOption.SessionCheckMode.DISABLED as a find option:

Or, for the legacy byMultipleIds() API:

The MySQLDialect was using the now() function to implement fetching of the current timestamp, which returns no fractional seconds. Since the implementations for other databases all at least returned values with millisecond precision, the implementation was changed to include the maximum precision 6, by using now(6).

The effect of the change is that newly updated/inserted entities that use @CurrentTimestamp will now assign a value with the configured precision of the column, instead of always truncating the fractional seconds.

To revert back to the old behavior, change the column type of the annotated attribute to datetime(0),

EntityManager.getLockMode() now returns NONE for a managed entity outside a transaction instead of throwing TransactionRequiredException. With JPA bootstrap, lock(entity, LockModeType.NONE) now requires an active transaction. Stateless refresh() with a lock mode other than NONE also requires a transaction with JPA bootstrap.

A query requesting a pessimistic lock now checks the version of an already managed versioned entity even when its current lock mode is NONE. If another transaction has changed its version, the query throws OptimisticLockException instead of acquiring the lock on the stale instance. This includes entities loaded outside a transaction or retained in the persistence context after an earlier transaction. This behavior is consistent with EntityManager.lock(). Queries which request no lock are unaffected.

Locking queries now also perform the optimistic checks and forced version increments requested for entities already managed by the session. This applies to streamed results and follow-on locking as well as ordinary query results.

Hibernate now more consistently chooses between PessimisticLockException and LockTimeoutException based on whether the database locking failure aborts the transaction or only the statement.

For a managed entity locked with mode OPTIMISTIC or READ, Hibernate verifies the version before a transaction commits. Previously, on databases with snapshot isolation, this verification could read a stale version and miss a concurrent update.

Hibernate now acquires a pessimistic lock when necessary. Therefore, optimistic version checks may wait for other transactions or encounter lock timeouts or deadlocks.

When @NativeGenerator was introduced in Hibernate ORM 7.0, it defaulted to an allocation size of 1 for, in case the @SequenceGenerator or @TableGenerator annotations had their allocation size set to their default of 50. Other values were respected, so this behavior was slightly unintuitive, yet the reasoning behind the choice was not documented. To make the behavior less surprising, it was now changed to respect the allocation size of 50.

This requires that, if sequences are used, the sequence is altered to change the allocation size from 1 to 50. Alternatively, users can configure the allocation size to match the legacy value 1 by defining @NativeGenerator(sequenceForm = @SequenceGenerator(allocationSize = 1), tableForm = @TableGenerator(allocationSize = 1).

When an enum is mapped via @EnumeratedValue, a column value which matches none of the declared enum values now results in an IllegalArgumentException while the row is read, consistent with the EnumType.STRING mapping (which relies on Enum.valueOf()). Previously such a value was silently read as null, which typically surfaced much later as a NullPointerException or as a wrong attribute value. Applications which relied on the lenient behavior, e.g. while an enum value is being removed, must clean up the affected rows before the enum value is dropped.

Configuring both hibernate.session_factory.interceptor and hibernate.session_factory.session_scoped_interceptor now throws ConflictingInterceptorSettingsException when building the SessionFactory. Previously, one setting silently took precedence over the other with no indication that both had been configured.

Applications that set both must choose one: hibernate.session_factory.interceptor for a shared instance or CDI-managed global interceptor, or hibernate.session_factory.session_scoped_interceptor for a per-session interceptor obtained from a Supplier or a CDI-managed class.

The namespace for mapping.xsd is now https://www.hibernate.org/xsd/orm/mapping, using HTTPS instead of HTTP. Hibernate will handle this on the fly at runtime, though you should also consider changing your mapping documents using this XSD either manually or using the hibernate-migration-recipes OpenRewrite recipes.

Previous versions of the mapping.xsd defined table and column comments (for schema export) using XSD attributes. This was a decision made at the time to facilitate users migrating from hbm.xml mapping format. In the intervening period, Jakarta Persistence has also added comments to its table and column XSD types, but using dedicated element.

We now align with the Jakarta Persistence approach of using elements. This will require changes any mapping.xml documents which define table or column comments. E.g.,

would need to be changed to

The orphan-removal attribute has been removed from the <many-to-many> element in the XML mapping XSD.

Although previous versions of the schema allowed specifying orphan-removal="true" on a <many-to-many> mapping, this attribute was never processed during boot. Orphan removal behavior was silently ignored for many-to-many associations. The attribute has been removed from the XSD to reflect the actual supported behavior.

Any mapping.xml documents using this attribute:

should remove the orphan-removal attribute, as it had no effect.

TThe proxy and polymorphism XML mapping attributes have been removed from the entity mapping XSD.

This change follows the removal of the corresponding @Proxy and @Polymorphism annotations in Hibernate ORM 7.0.0.Beta1.

Both elements have been removed from the mapping-8.0.xsd schema along with the polymorphism-type simple type definition.

Any mapping.xml documents using these elements:

should remove them, as they are no longer supported.

The SpannerPostgreSQLDialect, which was previously part of the hibernate-community-dialects artifact under the package name org.hibernate.community.dialect, has been migrated to the hibernate-core artifact and package name org.hibernate.dialect.

Users currently using the community dialect must update their dialect configuration to use org.hibernate.dialect.SpannerPostgreSQLDialect (or rely on Hibernate’s automatic dialect resolution).

In previous versions the Interceptor.onLoad() callback had not been implemented for Stateless Sessions. This has now been corrected.

Generated unique constraints for Set collection tables with nullable element columns now use NULLS NOT DISTINCT where supported, including PostgreSQL 15 and later. This prevents duplicate elements whose corresponding columns contain nulls. Before applying the new constraint to an existing table, remove any such duplicates.

Define a @Changelog entity that maps to the existing REVINFO table (or use the built-in DefaultChangelog):

No DDL changes are needed. The default REV/REVTYPE column names and encoding match between Envers and core. The REVINFO table rows continue the same sequence.

Hibernate ORM JARs no longer include OSGi metadata in their manifests, including Bundle-*, Import-Package, Export-Package, and Require-Capability headers. Applications deploying Hibernate ORM in an OSGi environment must supply the required bundle metadata themselves. The Automatic-Module-Name manifest attribute is retained for use on the Java module path.

Previous releases published relocation POMs under the org.hibernate group id, directing consumers to the current org.hibernate.orm coordinates. Starting with this version — these relocation POMs are no longer published.

If your build still references Hibernate ORM modules using the old org.hibernate group id (e.g. org.hibernate:hibernate-core), you must update your dependency coordinates to use org.hibernate.orm (e.g. org.hibernate.orm:hibernate-core).

The hibernate-micrometer module no longer pulls io.micrometer:micrometer-core as a transitive runtime dependency. Applications using this module must now explicitly add io.micrometer:micrometer-core to their classpath.