HHH-20017

README.adoc

@@ -18,7 +18,7 @@ See link:MAINTAINERS.md#ci[MAINTAINERS.md] for information about CI.
 
 == Building from sources
 
-The build requires at least JDK 21, and produces Java 17 bytecode.
+The build requires at least JDK 25, and produces Java 17 bytecode.
 
 Hibernate uses https://gradle.org[Gradle] as its build tool. See the _Gradle Primer_ section below if you are new to
 Gradle.

changelog.txt

@@ -1,6 +1,28 @@
 Hibernate 7 Changelog
 =======================
 
+Changes in 7.2.0.CR4 (December 10, 2025)
+------------------------------------------------------------------------------------------------------------------------
+
+https://hibernate.atlassian.net/projects/HHH/versions/36476
+
+
+** Bug
+    * HHH-19980 In JTA after-completion callbacks may get ignored
+    * HHH-19979 processor should handle @NamedEntityGraph with defaulted name
+    * HHH-19975 Calling entityManager.find(clazz, id) with null id throws NullPointerException
+    * HHH-19972 OptionalTableUpdateOperation can fail on PostgreSQL < 15 and CockroachDB
+    * HHH-19963 Wrong references in entity fields with circular associations
+    * HHH-19958 `<generated>` tag in orm.xml is not implemented
+    * HHH-19955 Thread-safety issue in EntityEntryContext resulting in NullPointerException for Session.contains() calls.
+    * HHH-19843 Bean Validation may fail on operations with stateless session
+    * HHH-18871 Nested NativeQuery mappings causing 'Could not locate TableGroup' exception after migration
+    * HHH-18217 StatelessSession.upsert() for entity with all-null non-id fields, or no non-id field
+
+** Improvement
+    * HHH-19943 Comparison of generic nested EmbeddedId's fails for JPQL and Criteria API
+    * HHH-19215 Extends Dialect#addQueryHints to support straight_join syntax
+
 Changes in 7.2.0.CR3 (November 25, 2025)
 ------------------------------------------------------------------------------------------------------------------------
 

ci/release/Jenkinsfile

@@ -222,15 +222,9 @@ pipeline {
 								withEnv([
 										"DISABLE_REMOTE_GRADLE_CACHE=true"
 								]) {
-                                    def notesFiles = findFiles(glob: 'release_notes.md')
-                                    if ( notesFiles.length < 1 ) {
-                                        throw new IllegalStateException( "Could not locate `release_notes.md`" )
-                                    }
-                                    if ( notesFiles.length > 1 ) {
-                                        throw new IllegalStateException( "Located more than 1 `release_notes.md`" )
-                                    }
+                                    def ghReleaseNote = sh(script: 'realpath -e release_notes.md 2>/dev/null', returnStdout: true).trim()
 
-									sh ".release/scripts/publish.sh -j --notes=${notesFiles[0].path} ${env.SCRIPT_OPTIONS} ${env.PROJECT} ${env.RELEASE_VERSION} ${env.DEVELOPMENT_VERSION} ${env.GIT_BRANCH} "
+                                    sh ".release/scripts/publish.sh -j ${ghReleaseNote != '' ? '--notes=' + ghReleaseNote : ''} ${env.SCRIPT_OPTIONS} ${env.PROJECT} ${env.RELEASE_VERSION} ${env.DEVELOPMENT_VERSION} ${env.GIT_BRANCH} "
 								}
 							}
 						}

docker_db.sh

@@ -218,53 +218,59 @@ mariadb_setup() {
     echo "MySQL databases were successfully setup"
 }
 
+POSTGRESQL_PLATFORM_OPTION=""
+if [[ "$IS_OSX" == "true" ]]; then
+  # PostGIS images only support amd64, so we force emulation on macOS
+  POSTGRESQL_PLATFORM_OPTION="--platform linux/amd64"
+fi
+
 postgresql() {
   postgresql_18
 }
 
 postgresql_13() {
     $CONTAINER_CLI rm -f postgres || true
-    $CONTAINER_CLI run --name postgres -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_13:-docker.io/postgis/postgis:13-3.1} \
+    $CONTAINER_CLI run --name postgres ${POSTGRESQL_PLATFORM_OPTION} -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_13:-docker.io/postgis/postgis:13-3.1} \
        -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c shared_buffers=256MB -c maintenance_work_mem=256MB -c max_wal_size=1GB -c checkpoint_timeout=1d
     $CONTAINER_CLI exec postgres bash -c '/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && apt install -y postgresql-13-pgvector'
     postgresql_setup
 }
 
 postgresql_14() {
     $CONTAINER_CLI rm -f postgres || true
-    $CONTAINER_CLI run --name postgres -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_14:-docker.io/postgis/postgis:14-3.3} \
+    $CONTAINER_CLI run --name postgres ${POSTGRESQL_PLATFORM_OPTION} -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_14:-docker.io/postgis/postgis:14-3.3} \
        -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c shared_buffers=256MB -c maintenance_work_mem=256MB -c max_wal_size=1GB -c checkpoint_timeout=1d
     $CONTAINER_CLI exec postgres bash -c '/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && apt install -y postgresql-14-pgvector'
     postgresql_setup
 }
 
 postgresql_15() {
     $CONTAINER_CLI rm -f postgres || true
-    $CONTAINER_CLI run --name postgres -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_15:-docker.io/postgis/postgis:15-3.3} \
+    $CONTAINER_CLI run --name postgres ${POSTGRESQL_PLATFORM_OPTION} -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_15:-docker.io/postgis/postgis:15-3.3} \
       -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c shared_buffers=256MB -c maintenance_work_mem=256MB -c max_wal_size=1GB -c checkpoint_timeout=1d
     $CONTAINER_CLI exec postgres bash -c '/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && apt install -y postgresql-15-pgvector'
     postgresql_setup
 }
 
 postgresql_16() {
     $CONTAINER_CLI rm -f postgres || true
-    $CONTAINER_CLI run --name postgres -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_16:-docker.io/postgis/postgis:16-3.4} \
+    $CONTAINER_CLI run --name postgres ${POSTGRESQL_PLATFORM_OPTION} -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_16:-docker.io/postgis/postgis:16-3.4} \
       -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c shared_buffers=256MB -c maintenance_work_mem=256MB -c max_wal_size=1GB -c checkpoint_timeout=1d
     $CONTAINER_CLI exec postgres bash -c '/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && apt install -y postgresql-16-pgvector'
     postgresql_setup
 }
 
 postgresql_17() {
     $CONTAINER_CLI rm -f postgres || true
-    $CONTAINER_CLI run --name postgres -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_17:-docker.io/postgis/postgis:17-3.5} \
+    $CONTAINER_CLI run --name postgres ${POSTGRESQL_PLATFORM_OPTION} -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql/data -d ${DB_IMAGE_POSTGRESQL_17:-docker.io/postgis/postgis:17-3.5} \
       -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c shared_buffers=256MB -c maintenance_work_mem=256MB -c max_wal_size=1GB -c checkpoint_timeout=1d
     $CONTAINER_CLI exec postgres bash -c '/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && apt install -y postgresql-17-pgvector'
     postgresql_setup
 }
 
 postgresql_18() {
     $CONTAINER_CLI rm -f postgres || true
-    $CONTAINER_CLI run --name postgres -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql -d ${DB_IMAGE_POSTGRESQL_17:-docker.io/postgis/postgis:18-3.6} \
+    $CONTAINER_CLI run --name postgres ${POSTGRESQL_PLATFORM_OPTION} -e POSTGRES_USER=hibernate_orm_test -e POSTGRES_PASSWORD=hibernate_orm_test -e POSTGRES_DB=hibernate_orm_test -p5432:5432 --tmpfs /var/lib/postgresql -d ${DB_IMAGE_POSTGRESQL_18:-docker.io/postgis/postgis:18-3.6} \
       -c fsync=off -c synchronous_commit=off -c full_page_writes=off -c shared_buffers=256MB -c maintenance_work_mem=256MB -c max_wal_size=1GB -c checkpoint_timeout=1d
     $CONTAINER_CLI exec postgres bash -c '/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y && apt install -y postgresql-18-pgvector'
     postgresql_setup
@@ -1282,7 +1288,68 @@ EOF
 }
 
 tidb() {
-  tidb_5_4
+  tidb_8_5
+}
+
+tidb_8_5() {
+    $CONTAINER_CLI rm -f tidb || true
+    $CONTAINER_CLI run --name tidb -p4000:4000 -d ${DB_IMAGE_TIDB_8_5:-docker.io/pingcap/tidb:v8.5.4}
+
+    # Wait for TiDB to start
+    OUTPUT=
+    n=0
+    until [ "$n" -gt 15 ]; do
+        OUTPUT=$($CONTAINER_CLI logs tidb 2>&1)
+        if [[ $OUTPUT == *"server is running"* ]]; then
+            break;
+        fi
+        n=$((n+1))
+        echo "Waiting for TiDB to start..."
+        sleep 5
+    done
+
+    if [ "$n" -gt 15 ]; then
+        echo "TiDB failed to start after 75 seconds"
+        exit 1
+    else
+        echo "TiDB successfully started"
+    fi
+
+    # Wait for TiDB to accept connections
+    n=0
+    until [ "$n" -gt 10 ]; do
+        if $CONTAINER_CLI run --rm --network container:tidb docker.io/mysql:8.0 \
+            mysqladmin -h 127.0.0.1 -P 4000 -uroot ping >/dev/null 2>&1; then
+            break;
+        fi
+        n=$((n+1))
+        echo "Waiting for TiDB to be ready..."
+        sleep 3
+    done
+
+    if [ "$n" -gt 10 ]; then
+        echo "TiDB failed to become ready after 30 seconds"
+        exit 1
+    else
+        echo "TiDB is ready"
+    fi
+
+    # Create databases
+    databases=()
+    for n in $(seq 1 $DB_COUNT)
+    do
+      databases+=("hibernate_orm_test_${n}")
+    done
+    create_cmd=
+    create_cmd+="CREATE DATABASE IF NOT EXISTS hibernate_orm_test;"
+    create_cmd+="CREATE USER IF NOT EXISTS 'hibernate_orm_test'@'%' IDENTIFIED BY 'hibernate_orm_test';"
+    create_cmd+="GRANT ALL ON hibernate_orm_test.* TO 'hibernate_orm_test'@'%';"
+    for i in "${!databases[@]}";do
+      create_cmd+="CREATE DATABASE IF NOT EXISTS ${databases[i]}; GRANT ALL ON ${databases[i]}.* TO 'hibernate_orm_test'@'%';"
+    done
+    $CONTAINER_CLI run --rm --network container:tidb docker.io/mysql:8.0 \
+        mysql -h 127.0.0.1 -P 4000 -uroot -e "${create_cmd}" 2>/dev/null
+    echo "TiDB databases were successfully setup"
 }
 
 tidb_5_4() {
@@ -1370,6 +1437,38 @@ informix_12_10() {
     fi
 }
 
+spanner() {
+  spanner_emulator
+}
+
+spanner_emulator() {
+
+  $CONTAINER_CLI rm -f spanner || true
+  # Run emulator (gRPC on 9010, REST on 9020)
+  $CONTAINER_CLI run --name spanner -d \
+    -p 9010:9010 \
+    -p 9020:9020 \
+    ${SPANNER_EMULATOR:-gcr.io/cloud-spanner-emulator/emulator:1.5.45}
+
+  # Wait for emulator to be ready (check logs for known messages)
+  n=0
+  until [ "$n" -ge 20 ]; do
+    OUTPUT="$($CONTAINER_CLI logs spanner 2>&1 || true)"
+    if [[ "$OUTPUT" == *"gRPC server listening"* ]] || [[ "$OUTPUT" == *"Cloud Spanner emulator running"* ]]; then
+      echo "Cloud Spanner emulator started."
+      break
+    fi
+    echo "Waiting for Cloud Spanner emulator to start..."
+    n=$((n+1))
+    sleep 3
+  done
+
+  if [ "$n" -ge 20 ]; then
+    echo "Cloud Spanner emulator failed to start after 1 minute"
+    exit 1
+  fi
+}
+
 if [ -z ${1} ]; then
     echo "No db name provided"
     echo "Provide one of:"
@@ -1413,10 +1512,13 @@ if [ -z ${1} ]; then
     echo -e "\tpostgresql_13"
     echo -e "\tsybase"
     echo -e "\ttidb"
+    echo -e "\ttidb_8_5"
     echo -e "\ttidb_5_4"
     echo -e "\informix"
     echo -e "\informix_14_10"
     echo -e "\informix_12_10"
+    echo -e "\tspanner"
+    echo -e "\tspanner_emulator"
 else
     ${1}
 fi

documentation/src/main/asciidoc/introduction/Advanced.adoc

@@ -886,6 +886,17 @@ On the other hand, the following annotations specify how a collection should be
 
 Under the covers, Hibernate uses a `TreeSet` or `TreeMap` to maintain the collection in sorted order.
 
+[CAUTION]
+====
+The unowned (`mappedBy`) side of a bidirectional association is not responsible for specifying column mappings.
+So it's wrong in principle to use `@OrderColumn` or `@MapKeyColumn` on the unowned side of an association mapping.
+But for unowned collections, we may use `@OrderBy` or `@MapKey` instead.
+That is:
+
+- You can use `@OrderColumn` or `@MapKeyColumn` with an `@ElementCollection`, owned `@ManyToMany`, or owned `@OneToMany`.
+- But use `@OrderBy` or `@MapKey` when it's an _unowned_ `@ManyToMany` or `@OneToMany`.
+====
+
 [[any]]
 === Any mappings
 

documentation/src/main/asciidoc/introduction/Configuration.adoc

@@ -116,8 +116,8 @@ and `org.ehcache:ehcache`
 and `com.github.ben-manes.caffeine:jcache`
 | Distributed second-level cache support via {infinispan}[Infinispan] | `org.infinispan:infinispan-hibernate-cache-v60`
 // | SCRAM authentication support for PostgreSQL | `com.ongres.scram:client:2.1`
-| A JSON serialization library for working with JSON datatypes, for example, {jackson}[Jackson] or {yasson}[Yasson] |
-`com.fasterxml.jackson.core:jackson-databind` +
+| A JSON serialization library for working with JSON datatypes, for example, {jackson}[Jackson 2], {jackson3}[Jackson 3] or {yasson}[Yasson] |
+`com.fasterxml.jackson.core:jackson-databind`, `tools.jackson.core:jackson-databind` +
 or `org.eclipse:yasson`
 | <<spatial,Hibernate Spatial>> | `org.hibernate.orm:hibernate-spatial`
 | <<envers,Envers>>, for auditing historical data | `org.hibernate.orm:hibernate-envers`

documentation/src/main/asciidoc/introduction/Entities.adoc

@@ -526,6 +526,21 @@ Hibernate automatically generates a `UNIQUE` constraint on the columns mapped by
 Consider using the natural id attributes to implement <<equals-and-hash>>.
 ====
 
+In cases where the natural id is defined by multiple attributes, Hibernate also offers the link:{doc-javadoc-url}org/hibernate/annotations/NaturalIdClass.html[`@NaturalIdClass`] annotation which acts similarly to the Jakarta Persistence `@IdClass` annotation for <<load-by-natural-id,find operations>> -
+
+[source,java]
+----
+record BookKey(String isbn, int printing) {}
+
+@Entity
+@NaturalIdClass(BookKey.class)
+class Book {
+    ...
+}
+----
+
+See the link:{doc-user-guide-url}#naturalid[User Guide] for more details about natural ids.
+
 The payoff for doing this extra work, as we will see <<natural-id-cache,much later>>, is that we can take advantage of optimized natural id lookups that make use of the second-level cache.
 
 Note that even when you've identified a natural key, we still recommend the use of a generated surrogate key in foreign keys, since this makes your data model _much_ easier to change.
@@ -586,6 +601,7 @@ Hibernate slightly extends this list with the following types:
 | Additional date/time types | `java.time` | `Duration`, `ZoneId`, `ZoneOffset`, and even `ZonedDateTime`
 | JDBC LOB types | `java.sql` | `Blob`, `Clob`, `NClob`
 | Java class object | `java.lang` | `Class`
+| Internet addresses | `java.net` | `InetAddress`
 | Miscellaneous types | `java.util` | `Currency`, `Locale`, `URL`, `TimeZone`
 |====
 

documentation/src/main/asciidoc/introduction/Interacting.adoc

@@ -276,6 +276,7 @@ Modifications are automatically detected when the session is <<flush,flushed>>.
 
 On the other hand, except for `getReference()`, the following operations all result in immediate access to the database:
 
+[[methods-for-reading]]
 .Methods for reading and locking data
 [%breakable,cols="30,~"]
 |===
@@ -368,9 +369,30 @@ The following code results in a single SQL `select` statement:
 List<Book> books = session.findMultiple(Book.class, bookIds);
 ----
 
+[[load-by-natural-id]]
+As discussed <<natural-id-attributes,earlier>>, Hibernate offers the ability to map a natural id and perform load operations using that natural id.
+This is accomplished using the `KeyType#NATURAL` `FindOption` -
+
+[source,java]
+----
+var bookKey = new BookKey(...);
+var book = session.find(Book.class, bookKey, NATURAL);
+var books = session.findMultiple(Book.class, List.of(bookKey), NATURAL);
+----
+
+When loading by natural id, the type of value accepted depends on the type of natural id.
+For single-attribute natural ids, whether defined by a basic or embedded type, the attribute type should be used.
+For multi-attribute natural ids, Hibernate will accept a number of forms:
+
+* If a link:{doc-javadoc-url}org/hibernate/annotations/NaturalIdClass.html[`@NaturalIdClass`] is defined, an instance of the natural id class may be used.
+* An array of the individual attribute values, ordered alphabetically by name, may be used.
+* A `Map` of the individual attribute values, keyed by the attribute name, may be used.
+
 Each of the operations we've seen so far affects a single entity instance passed as an argument.
 But there's a way to set things up so that an operation will propagate to associated entities.
 
+See the link:{doc-user-guide-url}#find-by-natural-id[User Guide] for more details about loading by natural ids.
+
 [[cascade]]
 === Cascading persistence operations
 
@@ -595,7 +617,8 @@ Therefore, Hibernate has some APIs that streamline certain more complicated look
 
 [NOTE]
 ====
-Since the introduction of `FindOption` in JPA 3.2, `byId()` is now much less useful.
+Since the introduction of `FindOption` in JPA 3.2, `byId()` is now much less useful and deprecated.
+Instead, use `find()` and `findMultiple()` as discussed <<methods-for-reading,earlier>>.
 ====
 
 Batch loading is very useful when we need to retrieve multiple instances of the same entity class by id:
@@ -627,6 +650,8 @@ We also have some operations for working with lookups by <<natural-identifiers,
 | `byMultipleNaturalId()` | Lets us load a _batch_ of natural ids at the same time
 |===
 
+Again, see the link:{doc-user-guide-url}#find-by-natural-id[User Guide] for more details about loading by natural ids.
+
 Here's how we can retrieve an entity by its composite natural id:
 
 [source,java]

documentation/src/main/asciidoc/introduction/Mapping.adoc

@@ -809,13 +809,20 @@ class Person {
 ----
 
 We also need to add Jackson or an implementation of JSONB—for example, Yasson—to our runtime classpath.
-To use Jackson we could add this line to our Gradle build:
+To use Jackson 2 we could add this line to our Gradle build:
 
 [source,groovy]
 ----
 runtimeOnly 'com.fasterxml.jackson.core:jackson-databind:{jacksonVersion}'
 ----
 
+To use Jackson 3 we could add this line to our Gradle build:
+
+[source,groovy]
+----
+runtimeOnly 'tools.jackson.core:jackson-databind:{jackson3Version}'
+----
+
 Now the `name` column of the `Author` table will have the type `jsonb`, and Hibernate will automatically use Jackson to serialize a `Name` to and from JSON format.
 
 [[miscellaneous-mappings]]