You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by bo...@apache.org on 2026/10/09 15:48:21 UTC
(grails-core) 04/05: docs(hibernate7): native domain binding is the default, classic binding is deprecated
This is an automated email from the ASF dual-hosted git repository.
borinquenkid pushed a commit to branch 9.0.x-h7-improvement-phase3
in repository https://gitbox.apache.org/repos/asf/grails-core.git
commit a58c8763109465071dd9b35051241dfab657b64f
Author: Walter Duque de Estrada <wb...@mac.com>
AuthorDate: Fri Oct 9 09:37:13 2026 -0500
docs(hibernate7): native domain binding is the default, classic binding is deprecated
The Native Domain Binding chapter describes native binding as the default
and hibernate.generatedDomainClasses: false as the deprecated fallback that
logs a warning at startup and will be removed; its steps for an existing
database start from the upgraded application and name dbm-gorm-diff, and
the schema table gains the column order of a generated createTable change
set. The configuration reference and the Hibernate 7 migration checklist
state the new default. The 9.0.x upgrade notes say native binding is the
default on upgrade, what to run before upgrading an existing database, how
to fall back temporarily, and link the chapter for the differences. The
module README tells contributors how to run the suite through the classic
binder and what classic-only-specs.txt is.
Co-Authored-By: Claude Fable 5.1 <no...@anthropic.com>
---
grails-data-hibernate7/README.md | 9 +++++
.../advancedGORMFeatures/nativeDomainBinding.adoc | 29 ++++++++------
.../configuration/configurationReference.adoc | 2 +-
.../asciidoc/gettingStarted/hibernateVersions.adoc | 6 +--
.../src/en/guide/upgrading/upgrading90x.adoc | 44 +++++++++++++---------
5 files changed, 58 insertions(+), 32 deletions(-)
diff --git a/grails-data-hibernate7/README.md b/grails-data-hibernate7/README.md
index dcfea0c232..9484b9f4e7 100644
--- a/grails-data-hibernate7/README.md
+++ b/grails-data-hibernate7/README.md
@@ -53,6 +53,15 @@ Registered via `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfi
A Grails CLI SPI hook (`org.grails.cli.compiler.CompilerAutoConfiguration`) that detects `@Entity` classes in Grails scripts and automatically adds the `grails-data-hibernate7-core` dependency and `grails.gorm.*` imports to the compilation context.
Registered via `META-INF/services/org.grails.cli.compiler.CompilerAutoConfiguration`.
+## Running the suite with the classic domain binder (contributors)
+
+Native domain binding is the default (`hibernate.generatedDomainClasses` defaults to `true`), so the core suite boots every datastore the
+TCK manager builds natively. `./gradlew -Pgrails.test.classicDomainBinding=true :grails-data-hibernate7-core:test` boots them through the
+deprecated classic binder instead (the Gradle property sets the JVM property `grails.hibernate.classicDomainBinding`, which the settings
+default and the TCK manager read; a spec that sets `hibernate.generatedDomainClasses` itself is not affected). The specs listed in
+`core/classic-only-specs.txt` assert facts of the classic boot model and run only in that mode; the default run excludes them. Both modes
+are wired in `gradle/hibernate7-test-config.gradle`.
+
## Differential specs and the frozen classic oracle (contributors)
Native domain binding (`hibernate.generatedDomainClasses`, `GrailsDomainGenerator`) is checked against what the classic domain binder
diff --git a/grails-data-hibernate7/docs/src/docs/asciidoc/advancedGORMFeatures/nativeDomainBinding.adoc b/grails-data-hibernate7/docs/src/docs/asciidoc/advancedGORMFeatures/nativeDomainBinding.adoc
index 578892e224..81f7a6b925 100644
--- a/grails-data-hibernate7/docs/src/docs/asciidoc/advancedGORMFeatures/nativeDomainBinding.adoc
+++ b/grails-data-hibernate7/docs/src/docs/asciidoc/advancedGORMFeatures/nativeDomainBinding.adoc
@@ -22,25 +22,28 @@ under the License.
GORM for Hibernate 7 can bind your domain classes to Hibernate in two ways.
-Classic binding::
-GORM reads your `static mapping` blocks and constraints and builds Hibernate's mapping model itself. This is the default.
-
Native binding::
-GORM describes each domain class with the JPA and Hibernate annotations that express the same mapping, and Hibernate's own annotation binder binds them. Your domain classes are not changed. Sessions, queries, proxies, dirty checking and the instances you work with are still your real domain classes.
+GORM describes each domain class with the JPA and Hibernate annotations that express the same mapping, and Hibernate's own annotation binder binds them. Your domain classes are not changed. Sessions, queries, proxies, dirty checking and the instances you work with are still your real domain classes. This is the default.
+
+Classic binding::
+GORM reads your `static mapping` blocks and constraints and builds Hibernate's mapping model itself. Classic binding is deprecated and will be removed in a later release.
-Native binding is where GORM for Hibernate 7 is heading: the mapping is bound by the same code that binds hand-annotated JPA entities, so it follows Hibernate releases without GORM keeping its own copy of Hibernate's mapping rules. It is opt-in today and is intended to become the default. Classic binding will then be retired.
+Native binding is where GORM for Hibernate 7 is heading: the mapping is bound by the same code that binds hand-annotated JPA entities, so it follows Hibernate releases without GORM keeping its own copy of Hibernate's mapping rules.
-This page lists everything that differs from classic binding, so you can decide when to switch.
+This page lists everything that differs from classic binding, so you know what changes for an application that was built with it.
+[[nativeDomainBinding-enabling]]
=== Enabling Native Binding
-Set `hibernate.generatedDomainClasses` to `true`. It is a boolean and defaults to `false`.
+Native binding is on by default: `hibernate.generatedDomainClasses` is a boolean and defaults to `true`. Nothing needs to be set.
+
+Setting it to `false` selects the deprecated classic binding. Use this only to keep an existing application running while you work through the differences on this page; the application logs a warning at startup that names the setting, and the option goes away when classic binding is removed.
[source,yaml]
.grails-app/conf/application.yml
----
hibernate:
- generatedDomainClasses: true
+ generatedDomainClasses: false # deprecated: selects the classic binding
----
The same key works wherever the configuration is read: `application.yml` in Spring Boot, or the `Map` or `PropertyResolver` passed to `HibernateDatastore` when GORM is used standalone. The setting applies to every data source of the application.
@@ -312,6 +315,10 @@ The schema of 765 groups of related domain classes was created with both binding
| No index named after a closure on the table of a collection whose `index` is a closure.
| See <<nativeDomainBinding-behavior,Differences in Behavior>>.
| A database created by classic binding has an index with a name that depends on the start it was created in. Drop it if you want to be rid of it.
+
+| The order of the columns in a `createTable` change set that `dbm-generate-gorm-changelog` or `dbm-gorm-diff` writes: the identifier, then the other columns in the order of the property names (the `version` column among them), then the foreign key columns.
+| Hibernate's annotation binder binds the properties of a class sorted by name, and the migration commands read the mapping model as it was bound. Classic binding listed the identifier, the version, then the properties in declaration order. The schema that `dbCreate` creates is not affected: Hibernate orders the columns of a table it creates itself, in the same way for both bindings, which is why the comparison above lists no other difference in column order.
+| None. Liquibase does not compare the order of columns, so a diff against an existing database reports nothing. A table created from a new change set has its columns in the new order.
|===
The comparison finds no difference in the unique keys, indexes and identifier columns that natural ids, `unique` groups and `index` options create: they have the same columns in the same order as with classic binding.
@@ -320,10 +327,10 @@ The comparison finds no difference in the unique keys, indexes and identifier co
Do not switch a production database over blindly. Whether `dbCreate: update` or a Liquibase changelog would change anything depends on the differences above.
-. Start the application with `hibernate.generatedDomainClasses: true` against a copy of your schema. Fix every refused mapping from the table above; classic binding cannot use these either.
+. Start the upgraded application, with its default native binding, against a copy of your schema. Fix every refused mapping from the table above; classic binding cannot use these either.
. Run <<ref-diff-scripts-dbm-gorm-diff,dbm-gorm-diff>> against the copy. An empty diff means the switch does not change the schema. Otherwise, compare each reported change with the table above, and apply the changes you want through a migration.
-. Run your test suite once with the setting on.
-. Set the property in the environment where you want it first, for example in `development` only.
+. Run your test suite once with native binding.
+. If you need more time, set `hibernate.generatedDomainClasses: false` in the environments that are not ready yet, for example in `production` only, and remove it as soon as the migration has run. Classic binding is deprecated and will be removed.
Prefer migrations over `dbCreate: update` for a production schema.
diff --git a/grails-data-hibernate7/docs/src/docs/asciidoc/configuration/configurationReference.adoc b/grails-data-hibernate7/docs/src/docs/asciidoc/configuration/configurationReference.adoc
index 2a0aa39d51..6fd360d59b 100644
--- a/grails-data-hibernate7/docs/src/docs/asciidoc/configuration/configurationReference.adoc
+++ b/grails-data-hibernate7/docs/src/docs/asciidoc/configuration/configurationReference.adoc
@@ -61,7 +61,7 @@ name,description,default value
`hibernate.configLocations`, Location of additional Hibernate XML configuration files
`hibernate.packagesToScan`, Specify packages to search for autodetection of your entity classes in the classpath
`hibernate.grails.proxy.lazy_to_string`, Whether `toString()` on an uninitialized proxy avoids initializing it (see Proxies and toString()), `false`
-`hibernate.generatedDomainClasses`, Whether Hibernate's own annotation binder binds the domain classes (see Native Domain Binding), `false`
+`hibernate.generatedDomainClasses`, Whether Hibernate's own annotation binder binds the domain classes (see Native Domain Binding); `false` selects the deprecated classic binding, `true`
|===
In addition, any additional settings that start with `hibernate.` are passed through to Hibernate, so if there is any specific feature of Hibernate you wish to configure that is possible.
diff --git a/grails-data-hibernate7/docs/src/docs/asciidoc/gettingStarted/hibernateVersions.adoc b/grails-data-hibernate7/docs/src/docs/asciidoc/gettingStarted/hibernateVersions.adoc
index 101f5eac78..1a6b4cc25d 100644
--- a/grails-data-hibernate7/docs/src/docs/asciidoc/gettingStarted/hibernateVersions.adoc
+++ b/grails-data-hibernate7/docs/src/docs/asciidoc/gettingStarted/hibernateVersions.adoc
@@ -113,9 +113,9 @@ If you are migrating an application from Hibernate 5 or the Grails Hibernate 5 p
| `insertable: false` and `updatable: false` are honored, enum columns receive the `comment`, `defaultValue`, `read` and `write` of their column mapping, the elements of basic-value collections of an owner with several unidirectional collections are stored, and the inverse side of a many-to-many reads the join table that its owner writes.
| Review domain classes that use `insertable: false` or `updatable: false`, because values that used to be written are no longer written. Compare the generated schema of enum properties with your database before using `dbCreate=update`. See <<nativeDomainBinding,Native Domain Binding>> for the related schema differences.
-| Native domain binding (opt-in)
-| `hibernate.generatedDomainClasses: true` makes Hibernate's own annotation binder bind the domain classes. It is off by default and is intended to become the default. A few mapping options are refused at startup and the generated schema differs from classic binding in documented cases.
-| Before enabling it, fix the mappings listed in <<nativeDomainBinding-refused,Mappings Native Binding Refuses>> and run `dbm-gorm-diff` against a copy of the existing database. See <<nativeDomainBinding-schema,Differences in the Schema>>.
+| Native domain binding (the default)
+| Hibernate's own annotation binder binds the domain classes; `hibernate.generatedDomainClasses` defaults to `true`. A few mapping options that classic binding could not use either are refused at startup, and the generated schema differs from classic binding in documented cases. `hibernate.generatedDomainClasses: false` selects the classic binding, which is deprecated, logs a warning at startup and will be removed.
+| Before upgrading an existing database, fix the mappings listed in <<nativeDomainBinding-refused,Mappings Native Binding Refuses>> and run `dbm-gorm-diff` against a copy of the database with the upgraded application. See <<nativeDomainBinding-schema,Differences in the Schema>> and <<nativeDomainBinding-enabling,Enabling Native Binding>> for the temporary fallback.
| Query locks and query cache
| Locked queries are not query-cacheable.
diff --git a/grails-doc/src/en/guide/upgrading/upgrading90x.adoc b/grails-doc/src/en/guide/upgrading/upgrading90x.adoc
index fcdd18e161..5c913f88e2 100644
--- a/grails-doc/src/en/guide/upgrading/upgrading90x.adoc
+++ b/grails-doc/src/en/guide/upgrading/upgrading90x.adoc
@@ -57,7 +57,7 @@ class Author {
The same applies to a many-to-many from a class to itself: `belongsTo` names the class itself.
A unidirectional many-to-many, a many-to-many that has `belongsTo` on either side, and one where either side is a `Map` need no change.
-The rule is the same whether or not you enable native domain binding, see below.
+The rule is the same with native domain binding, the default, and with the deprecated classic binding, see below.
See link:{hibernate7Guide}index.html#gormAssociation-manyToMany[Many-to-Many Associations] in the GORM for Hibernate 7 manual.
@@ -81,19 +81,9 @@ They are also fixed in the 8.0.x line, so an application that is already on a re
===== 1.3 Native Domain Binding
-GORM for Hibernate 7 can bind your domain classes with Hibernate's own annotation binder instead of building Hibernate's mapping itself.
-This is native domain binding.
-It is the direction GORM for Hibernate 7 is taking and is intended to become the default.
-In Grails {version} it is opt-in and the default stays classic binding.
-
-Enable it with the `hibernate.generatedDomainClasses` setting:
-
-[source,yaml]
-.grails-app/conf/application.yml
-----
-hibernate:
- generatedDomainClasses: true
-----
+GORM for Hibernate 7 binds your domain classes with Hibernate's own annotation binder instead of building Hibernate's mapping itself.
+This is native domain binding, and in Grails {version} it is the default: an upgraded application starts with it without any setting.
+The classic binding of earlier releases is deprecated and will be removed in a later release.
Your domain classes, your queries and the GORM API do not change.
The mapping can, though:
@@ -108,8 +98,28 @@ The mapping can, though:
Classic binding shares one table whose foreign key points at only one owner, so the collection of any other owner cannot be stored, and it does not start when the properties have the same name.
The first owner (by entity name, then property path) keeps the table and the key column it has today, the others get names that start with their table and the path of the embedded property.
* A custom collection type on a `hasMany` now takes effect, see <<native-binding-custom-collection-type,1.4>>.
+* A `createTable` change set written by `dbm-generate-gorm-changelog` or `dbm-gorm-diff` lists the columns in a different order: the identifier, then the columns in the order of the property names, then the foreign keys.
+ A diff against an existing database does not report this, because Liquibase does not compare column order.
+
+Before you upgrade an application with an existing database:
+
+. Start the upgraded application against a copy of the database and fix every refused mapping; the startup error says what to change.
+. Run `dbm-gorm-diff` against the copy with the upgraded application, which uses the new default.
+ An empty diff means the switch does not change your schema.
+ Otherwise, compare each reported change with the schema differences in the manual and apply the ones you want through a migration.
+. Run your test suite once.
+
+If you need more time, the `hibernate.generatedDomainClasses` setting selects the classic binding for the environments that are not ready yet:
+
+[source,yaml]
+.grails-app/conf/application.yml
+----
+hibernate:
+ generatedDomainClasses: false # deprecated: selects the classic binding
+----
-Before you switch an existing database, run `dbm-gorm-diff` against a copy of it with the setting on.
+The application then logs a warning at startup that names the setting.
+Remove the setting as soon as the migration has run, because classic binding will be removed.
The link:{hibernate7Guide}index.html#advancedGORMFeatures-nativeDomainBinding[Native Domain Binding] chapter of the GORM for Hibernate 7 manual lists every refused mapping, every schema difference and what each means for an existing database.
@@ -135,9 +145,9 @@ Native binding applies the type.
Hibernate creates, wraps and loads the collection with your class, so the code of your collection type runs where it never ran before.
The schema is the same.
-If your application maps a custom collection type, test it with `hibernate.generatedDomainClasses` set to `true` before you switch.
+If your application maps a custom collection type, test it with the upgraded application before you deploy.
A type that was never exercised can fail or behave differently once it is used.
-With classic binding, which stays the default in Grails {version}, nothing changes.
+With the deprecated classic binding (`hibernate.generatedDomainClasses: false`) nothing changes.
A custom collection type on a `hasMany` of basic values is not supported by either binding.