Skip to content

fix: fail fast when a SCHEMA multi-tenant entity references a non-tenant entity - #16850

Open
borinquenkid wants to merge 5 commits into
8.0.xfrom
fix/schema-mt-association-check-8.0.x
Open

borinquenkid wants to merge 5 commits into
8.0.xfrom
fix/schema-mt-association-check-8.0.x

Conversation

@borinquenkid

Copy link
Copy Markdown
Member

Fixes #14345

With grails.gorm.multiTenancy.mode: SCHEMA, each tenant schema gets its own SessionFactory, and only MultiTenant entities (plus entities that declare the ALL datasource) are mapped into it. An association from a MultiTenant entity to any other entity therefore failed at startup with a hard-to-diagnose "refers to an unmapped class" error.

This PR does not add support for such associations. It makes the failure clear: HibernateDatastore (Hibernate 5 and 7) now throws a ConfigurationException at startup in SCHEMA mode that names each offending Owner.property -> Target and says to make the target MultiTenant or use DISCRIMINATOR mode.

  • ConnectionSourcesSupport.findAssociationsToEntitiesMissingFromTenantSchemas finds the offending associations (embedded types and targets declaring ALL are skipped).
  • Tests: ConnectionSourcesSupportSpec, plus SchemaTenantAssociationSpec in both Hibernate cores.
  • Docs: new "Associations to Entities That Are Not Multi-Tenant" section in both schemaPerTenant.adoc files.

https://claude.ai/code/session_01Dmki4SQGwRSj8pRJ5KCWyX

…that are not multi-tenant

Each tenant schema gets a session factory that maps the MultiTenant entities
only, so a hasMany or to-one association from a MultiTenant entity to any
other entity failed at startup with 'An association ... refers to an unmapped
class'. Startup now fails with a ConfigurationException that names the
associations and the ways out, in both bindings. The schema-per-tenant guide
describes the restriction.

Fixes #14345

Claude-Session: https://claude.ai/code/session_01Dmki4SQGwRSj8pRJ5KCWyX
@borinquenkid
borinquenkid requested review from jamesfredley and a balanced review from Copilot November 4, 2026 04:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@borinquenkid borinquenkid added this to the grails:8.0.1 milestone Nov 4, 2026
@borinquenkid
borinquenkid requested a review from matrei November 12, 2026 14:13

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not approving. A non-tenant target that is mapped on every connection is rejected at startup.

if (!(property instanceof Association) || property instanceof Embedded || property instanceof EmbeddedCollection) {
continue;
}
PersistentEntity target = ((Association<?>) property).getAssociatedEntity();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A tenant owner has a many-to-one to a non-tenant entity that is mapped on every connection. Startup throws. That target is present. Do not reject it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could not reproduce this one. In 18bb5d5 I added SchemaTenantAssociationLayoutSpec (Hibernate 5 and 7) with the target layouts a mapping can declare: no datasource is refused; datasource 'ALL', datasources(['ALL']), a subclass of a root that uses ALL, the root of that hierarchy, and ALL given through grails.gorm.default.mapping all start. Which declaration of the target still throws for you? A mapping snippet is enough, and I will add it as a row.

… refuses and accepts

A tenant owner pointing at a target with no datasource declared is refused;
one pointing at a target that declares ALL (alone or as a list), a subclass
or the root of a hierarchy that uses every connection, or a target covered by
the default mapping starts. On Hibernate 5 and 7.

Claude-Session: https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL

@jamesfredley jamesfredley left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requested changes. A reference that should fail still fails. A target mapped to every named tenant schema is rejected because it does not use ALL.

continue;
}
PersistentEntity target = ((Association<?>) property).getAssociatedEntity();
if (target != null && !target.isMultiTenant() && !getConnectionSourceNames(target).contains(ConnectionSource.ALL)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The resolver returns only tenant1. Owner is multi-tenant and has Shared target. Shared is not multi-tenant and lists default and tenant1. Startup should succeed. This reports Owner.target -> Shared and throws, because ALL is absent. Check whether the target is actually mapped on the tenant connection.

…ses ALL

Answers the review of #16850: a non-tenant target that lists the default connection and the tenant schemas was refused for lacking ALL. The check now runs against the tenant schemas known at startup, and a target has to be mapped on every connection that maps the owner. The guide says so.

Claude-Session: https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL
@borinquenkid

Copy link
Copy Markdown
Member Author

Answers the second review. A non-tenant target is now checked against the tenant schemas known at startup, and against the default connection, because a MultiTenant entity is mapped there too: it is accepted when it uses ALL or lists the default connection and every tenant schema (your default + tenant1 example), and refused with the association named when one of them is missing.

SchemaTenantAssociationLayoutSpec (Hibernate 5 and 7) has each layout; the default + tenant1 row fails without the change (1 of 11 on each). datastore-core 330, datamapping-core 1808, Hibernate 5 1174, Hibernate 7 4350 tests, 0 failures; codeStyle clean. The guide paragraph is corrected.

Two limits, both written in the guide or the spec: a tenant schema added after startup is not checked, and a target that lists only the tenant schema is refused by Hibernate with a MappingException before this check runs, so the spec asserts only that it does not start.

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requested changes. A target mapped to every named tenant schema is accepted. A target mapped by annotation, with no datasource list, is still rejected even though it is mapped on every schema.

Set<String> names = new LinkedHashSet<>(tenantSchemaNames);
names.add(ConnectionSource.DEFAULT);
for (String name : names) {
if (usesConnectionSource(owner, name) && !usesConnectionSource(target, name)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The owner is multi-tenant. The target is mapped by annotation and has no datasource list. Startup used to succeed, because that target is mapped on every schema. This treats it as the default schema only and throws. Check the mapping that is actually used.

…hema

The startup check of schema multi-tenancy refused an association from a multi tenant entity to a target that lists no datasource,
whatever mapped the target. The Hibernate binders add every class annotated with jakarta.persistence.Entity to every session
factory and do not read its datasource list, so such a target is mapped on each tenant schema and the association has something
to refer to; startup used to succeed and the check refused it. The check now treats a JPA-annotated target as mapped everywhere,
and asks the datasource lists only of the others.

SchemaTenantAssociationLayoutSpec, on Hibernate 5 and Hibernate 7, gains the layout with the tenant schemas unknown and known.
A probe of the session factory of a tenant schema shows the JPA target mapped there on both, and a GORM-annotated target with no
datasource list not mapped.

Claude-Session: https://claude.ai/code/session_01Dmki4RzWwreEC2GkkyFnvL
@borinquenkid

Copy link
Copy Markdown
Member Author

Thank you, you are right, and I checked what the datastore does before changing the check. I added a probe that starts a datastore in SCHEMA mode, adds a tenant schema and lists the entities its session factory maps:

  • a target annotated with jakarta.persistence.Entity and listing no datasource is mapped in the tenant schema, on Hibernate 5 and on Hibernate 7. The binders add every JPA-annotated class to every session factory and do not read its datasource list.
  • a target annotated with grails.gorm.annotation.Entity and listing no datasource is not mapped there, so the refusal stays for it, as pinned by the existing "no datasource declared" row.

The check read only the datasource list, so it refused the first layout although the association has something to refer to. It now treats a JPA-annotated target as mapped on every schema, and asks the datasource lists only of the others.

SchemaTenantAssociationLayoutSpec has the JPA layout twice, with the tenant schemas unknown and known, on Hibernate 5 and on Hibernate 7. The two rows fail without the fix on Hibernate 5, and pass with it. Hibernate 5 (1176 tests), Hibernate 7 (4352) and grails-datastore-core (330) are green, and codeStyle is clean.

Branch policy: The mapping already failed at startup with an unclear unmapped-class error; this makes the same failure name the association, and accepts a target that is mapped on every connection of the owner, whether by datasource ALL or by a JPA annotation.

@jamesfredley jamesfredley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requested changes. A target mapped by annotation is accepted. A property stored as a value, not a relationship, is still rejected.

continue;
}
for (PersistentProperty<?> property : entity.getPersistentProperties()) {
if (!(property instanceof Association) || property instanceof Embedded || property instanceof EmbeddedCollection) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The owner maps items as a serializable value, not as a relationship. Startup used to succeed. This treats items as an association that is missing from the tenant schema and throws. Skip a property that is stored as a value.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

Multi-Tenancy - SCHEMA mode - One-To-Many relationship (tenant domain to public domain) error

3 participants