7.0 series - Hibernate ORM

Hibernate ORM 7.0 is still in development:

some features may be incomplete;
newly introduced features may change in a backward-incompatible way before the stable release.

We encourage you to give it a try and to let us know of any bugs or problems you encounter.

Compatibility

Java	17, 21 or 23
Jakarta Persistence	3.2
Jakarta EE	11

Not compatible with your requirements? Have a look at the other series.

See also the Compatibility policy and Maintenance policy.

Documentation

Documentation for Hibernate ORM 7.0 can be accessed through the links below:

Getting started guide HTML

Migration guide HTML

Reference HTML API (Javadoc)

You can find more documentation for all series on the documentation page.

How to get it

Current series status: development

Maven artifacts of Hibernate ORM are published to Maven Central. Most build tools fetch artifacts from Maven Central by default, but if that's not the case for you, see this page to configure your build tool.

You can find the Maven coordinates of all artifacts through the link below:

Maven artifacts

Below are the Maven coordinates of the main artifacts.

Core implementation

Spatial support

Vector support

Envers audit support

Agroal connection pooling

HikariCP connection pooling

c3p0 connection pooling

JCache second-level caching

Integration for Micrometer

Integration for Java Flight Recorder

Community-maintained SQL dialects

Hibernate Processor compile-time tooling

Direct download

Individual Maven artifacts may be downloaded directly from the Maven repository:

Maven Central subdirectory

See here for how to download all dependencies of your Maven project to a local directory on your filesystem.

See here for how to download an explicitly listed set of artifacts to a local directory on your filesystem.

More information about specific releases (announcements, download links) can be found here.

What's new

A detailed list of new features, improvements and fixes in this series can be found on our issue tracker.

Apache License

Starting with 7.0, Hibernate ORM will be licensed under the Apache License 2.0.

Details can be seen at https://hibernate.atlassian.net/browse/HHH-19145.

As part of this effort, the Hibernate team reached out to the authors of "non-trivial" contributions to request permission to relicense their work under the Apache License. The response was overwhelming positive, although we never heard back from some contributors and another explicitly disagreed. This required a few actions on our part:

Dropping hibernate-ucp - see https://hibernate.atlassian.net/browse/HHH-19162
Dropping TeradataDialect - see https://hibernate.atlassian.net/browse/HHH-19057

Java 17

Java 17 is the new baseline Java version.

Jakarta Persistence 3.2

7.0 migrates to Jakarta Persistence 3.2, which is fairly disruptive. See this blog post for a good discussion of the changes.

TCK Results with Java 17
TCK Results with Java 21

Hibernate Models

For many years Hibernate has used the Hibernate Commons Annotations (HCANN) library for handling various low-level tasks related to understanding the structure of an application domain model, reading annotations and weaving in XML mapping documents. The Hibernate Models project was developed to be a better alternative to HCANN. 7.0 uses Hibernate Models in place of HCANN.

@SoftDelete with TIMESTAMP

Soft-delete now supports the strategy of tracking the timestamp at which the soft-delete occurred, in addition to the previous truth-based strategies. See the User Guide for details.

@EmbeddedColumnNaming

A long-requested feature for both Hibernate and Jakarta Persistence has been the ability to define a prefix for the names of columns associated with an embedded value.

7.0 adds support for this using the new @EmbeddedColumnNaming annotation. The annotation accepts a format pattern, so is more flexible than just a prefix.

@Embeddable
class Address {
    String street;
    String city;
        ...
}

@Entity
class Person {
    ...
    @Embedded
    @EmbeddedColumnNaming("home_%")
    Address homeAddress;

    @Embedded
    @EmbeddedColumnNaming("work_%")
    Address workAddress;
}

See the User Guide for details.

@NamedEntityGraph

A new annotation (@org.hibernate.annotations.NamedEntityGraph) has been added to allow specifying a named entity-graph using Hibernate’s ability to parse a string representation of the graph.

@Entity
@NamedEntityGraph( graph="title, isbn, author(name, phoneNumber)" )
class Book {
        // ...
}

See org.hibernate.graph.GraphParser for details on the syntax and the User Guide for additional details.

findMultiple()

The new operation Session.findMultiple() provides a convenient way to fetch a batch of entities by id. Combined with the BatchSize option, allows breaking up the JDBC calls into "batches".

Direct access to first-level cache

The new operation Session.getManagedEntities() allows the application to iterate over all entities in the first-level cache, or over all entities of a given type.

Converted Enums and Check Constraints

Hibernate previously added support for generating check constraints for enums mapped using @Enumerated as part of schema generation. 7.0 adds the same capability for enums mapped using an AttributeConverter, by asking the converter to convert all the enum constants on start up.

JSON and XML functions

Support for most of the JSON and XML functions that the SQL standard specifies was added to HQL/Criteria. The implementations retain the SQL standard semantics and will throw an error if emulation on a database is impossible.

New functions include:

construction functions like json_array(), json_object(), xmlelement() and xmlforest()
query functions like json_value(), json_query() and xmlquery()
aggregation functions like json_agg(), json_object_agg() and xmlagg()
manipulation functions like json_set(), json_mergepatch()
many others

Set-returning Functions

A set-returning function is a new type of function that can return rows and is exclusive to the from clause. The concept is known in many different database SQL dialects and is sometimes referred to as table valued function or table function.

Custom set-returning functions can be registered via a FunctionContributor. Out-of-the-box, some common set-returning functions are already supported or emulated

unnest() - allows to turn an array into rows
generate_series() - can be used to create a series of values as rows
json_table() - turns a JSON document into rows
xmltable() - turns an XML document into rows

@AnyDiscriminatorImplicitValues

The new @AnyDiscriminatorImplicitValues offers 2 related improvements for the mapping of discriminator values for @Any and ManyToAny associations.

First, it allows control over how Hibernate determines the discriminator value to store in the database for implicit discriminator mappings. Historically, Hibernate would always use the full name of the associated entity.

Second, it allows mixing of explicit and implicit value strategies.

See the User Guide for details.

StatelessSession and Batch Operations

StatelessSession now supports explicit batch operations via insertMultiple(), updateMultiple(), or deleteMultiple().

StatelessSession and Second Level Cache

Previously, stateless sessions never interacted with the second-level cache. This reflected their original intended role in bulk processing. With the advent of Jakarta Data and Hibernate Data Repositories, the responsibilities of StatelessSession have now expanded, and this behavior is no longer appropriate. Thus, a stateless session now makes use of the second-level cache by default.

See the Migration Guide for additional details.

StatelessSession and JDBC Batching

Automatic JDBC batching has the side effect of delaying the execution of the batched operation, and this undermines the synchronous nature of operations performed through a stateless session. In Hibernate 7, the configuration property hibernate.jdbc.batch_size now has no effect on a stateless session. Automatic batching may be enabled by explicitly calling setJdbcBatchSize(). However, the preferred approach is to explicitly batch operations via insertMultiple(), updateMultiple(), or deleteMultiple().

Improvements to Transaction

The Transaction interface leaks the SPI type TransactionStatus via getStatus(), and the JTA-defined type Synchronization via registerSynchronization(), which breaks layering in a fairly harmless way. New operations were added to the Transaction interface, allowing code to inspect the status of the transaction or register callbacks without the use of layer-breaking operations.

Data population

Setting jakarta.persistence.schema-generation.database.action=populate or calling SchemaManager.populate() populates an existing schema with initial data in /import.sql or other SQL scripts specified via jakarta.persistence.sql-load-script-source.

XML mappings

Hibernate’s legacy hbm.xml mapping schema has been deprecated for quite some time, replaced by a new mapping.xml schema, which is now stabilized and should be prefered. Support for hbm.xml mappings will be removed in 8.0.

We offer a transformation of hbm.xml files into mapping.xml files, which is available both at build-time (Gradle plugin) and at run-time (using hibernate.transform_hbm_xml.enabled=true).

Development versions (SNAPSHOTS)

The latest development versions of Maven artifacts for Hibernate ORM are published to the OSSRH snapshots repository.

OSSRH snapshots subdirectory

You should only need those (unstable) versions for testing recently merged patches, and should never use them in production.

To consume these artifacts, you may need to configure your build tool to fetch artifacts from https://oss.sonatype.org/content/repositories/snapshots and to enable snapshots:

Maven Gradle