fix(orm): resolve implicit m2m join table schema for non-public PostgreSQL schemas

[ymc9]

Summary

• Fixes Title: Handling Implicit Many-to-Many Relationship Join Tables in ZenStack ZModel: Schema Mismatch and Workarounds #2603
• Implicit many-to-many join tables (e.g. _PostToTag) were always queried under the public schema in PostgreSQL multi-schema setups, causing a "relation does not exist" error
• The ORM now pre-computes each join table's schema at startup by looking at the alphabetically-first model in the relation — matching the convention Prisma uses when creating the join table

Changes

• packages/orm/src/client/executor/name-mapper.ts — build joinTableSchemaMap in the constructor; use it in getTableSchema when the model is not found in schema.models
• tests/regression/test/issue-2603.test.ts — regression tests covering: default schema, explicit @@schema, and models in different schemas

Test plan

• implicit m2m with defaultSchema set to non-public schema — creates/fetches posts with tags in mySchema
• implicit m2m with explicit @@schema on models — both models pinned to mySchema
• implicit m2m with models in different custom schemas — join table lands in schema1 (alphabetically first)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Fixed handling of PostgreSQL implicit many-to-many relationships when databases use custom schemas. Join tables now correctly determine their location based on related models, even when different models declare different custom schemas or use a non-default schema. Nested create operations and include queries now work properly in these scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

PostgreSQL implicit many-to-many join tables now have their schemas properly resolved during query execution. A join-table-to-schema mapping is precomputed in the QueryNameMapper constructor based on model/field relation metadata, and the getTableSchema method extended to resolve schemas for join tables that lack direct model entries, ensuring correct schema assignment regardless of custom schema configurations.

Changes

Cohort / File(s)	Summary
Schema Resolution Logic packages/orm/src/client/executor/name-mapper.ts	Precomputes join-table-to-schema mapping in QueryNameMapper constructor using model/field relation metadata. Extends getTableSchema to resolve schemas for implicit join tables and caches resolved schemas, defaulting to 'public' when unresolved.
Regression Test tests/regression/test/issue-2603.test.ts	Adds Vitest regression test verifying implicit many-to-many relations work correctly across custom schema configurations, testing create with nested tag creation and findFirst with tag inclusion in public, custom, and mixed schema scenarios.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Through schemas deep and tables wide,
The join paths now have nowhere to hide,
A mapper wise precomputes the way,
PostgreSQL queries dance and play! ✨
Lost relations found at last,
Custom schemas hold them fast! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main fix: resolving implicit many-to-many join table schema references for non-public PostgreSQL schemas, directly addressing the core issue.
Linked Issues check	✅ Passed	The PR fully addresses issue #2603 requirements: implements join-table-to-schema mapping precomputation, handles implicit m2m joins across different schema configurations, and includes comprehensive regression tests validating all specified scenarios.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to resolving implicit m2m join table schema resolution: modifications to name-mapper.ts for schema resolution logic and new regression tests for issue #2603, with no unrelated alterations detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-2603-implicit-m2m-join-table-schema

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude finished @ymc9's task —— View job

---

Code Review Complete ✅

Todo List

• Analyze the name-mapper.ts implementation changes
• Review the regression test coverage and quality
• Assess code quality and best practices
• Check for potential bugs or edge cases
• Evaluate performance considerations
• Review security implications
• Provide final feedback and recommendations

---

Summary

This is a well-implemented fix that addresses the PostgreSQL schema resolution bug for implicit M2M join tables. The solution is architecturally sound and follows established patterns.

✅ Strengths

• Correct approach: Pre-computing join table schemas matches Prisma's conventions
• Clean integration: Fits naturally into existing name-mapper architecture
• Comprehensive tests: All three main scenarios covered with good test data
• Performance improvement: O(1) lookups vs dynamic fallback logic
• Good documentation: Clear comments explaining the business logic

⚠️ Minor Improvements

name-mapper.ts:97

// Consider more defensive programming
const models = [modelName, m2m.otherModel].sort();
const owningModel = models[0];
if (!owningModel) continue; // or throw descriptive error

Optional validation enhancement:

// Validate otherModel exists before processing
if (!this.schema.models[m2m.otherModel]) {
    console.warn(`Referenced model ${m2m.otherModel} not found in schema`);
    continue;
}

🚀 Recommendation

APPROVE - This PR successfully fixes the reported issue with minimal risk. The implementation is clean, well-tested, and maintains backward compatibility. The minor suggestions above are optional improvements that don't block merging.

The fix correctly implements Prisma's join table placement convention and provides proper PostgreSQL multi-schema support for implicit M2M relationships.

---

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/orm/src/client/executor/name-mapper.ts (1)

567-585: ⚠️ Potential issue | 🟡 Minor

Unknown-table fallback to 'public' ignores defaultSchema.

For a non-join table that happens to be missing from schema.models (shouldn't normally happen, but it's the defensive branch), the new early return hardcodes 'public' rather than defaultSchema ?? 'public':

if (!this.schema.models[model]) {
    return this.joinTableSchemaMap.get(model) ?? 'public';
}

If the join table map lookup misses for any reason (e.g., a join table encountered before the map was fully built, or a relation metadata edge case), returning 'public' under a non-public defaultSchema would resurface the exact symptom this PR is fixing (42P01) but silently. Consider ?? (this.schema.provider.defaultSchema ?? 'public') to stay consistent with the normal-model branch below.

Proposed tweak

         if (!this.schema.models[model]) {
-            return this.joinTableSchemaMap.get(model) ?? 'public';
+            return this.joinTableSchemaMap.get(model) ?? this.schema.provider.defaultSchema ?? 'public';
         }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/orm/src/client/executor/name-mapper.ts` around lines 567 - 585, The
fallback in getTableSchema currently returns joinTableSchemaMap.get(model) ??
'public', which ignores a non-default provider defaultSchema; update the
unknown-model branch in getTableSchema so the final fallback uses the provider
defaultSchema (i.e. use joinTableSchemaMap.get(model) ??
(this.schema.provider.defaultSchema ?? 'public')) to match the logic used for
known models and avoid hardcoding 'public'; reference getTableSchema,
this.schema.models, joinTableSchemaMap and this.schema.provider.defaultSchema
when making the change.

🧹 Nitpick comments (2)

tests/regression/test/issue-2603.test.ts (1)

93-128: Minor: strengthen assertions for the cross-schema case.

This is the scenario most likely to regress (join table placed in alphabetically-first model's schema), yet it only creates a single tag and asserts the name list. Consider adding a findFirst({ include: { tags: true } }) round-trip plus asserting tag count — that exercises the SELECT-side schema resolution for the join table, which is a separate code path from the nested-create side.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/regression/test/issue-2603.test.ts` around lines 93 - 128, The test
implicit m2m with models in different custom schemas only asserts the created
tag name and should also exercise SELECT-side join-table resolution: after
calling db.post.create (db.post.create in this test), add a db.post.findFirst({
include: { tags: true } }) round-trip and assert that the returned post has
tags.length === 1 and the tag name matches (use expect(post.tags.length).toBe(1)
and expect(post.tags.map(t => t.name)).toEqual(['foo']) or equivalent), so both
nested-create and subsequent SELECT path for the join table are validated.

packages/orm/src/client/executor/name-mapper.ts (1)

86-102: Consider using realModel (originModel) when deriving the owning model for delegate-inherited m2m fields.

getManyToManyRelation uses realModel = fieldDef.originModel ?? model for sorting and naming the join table (see query-utils.ts lines 262–310). Here the owning-model selection uses modelName directly:

const owningModel = [modelName, m2m.otherModel].sort()[0]!;

If Post is a delegate child of BasePost, the join table will be named _BasePostTo... (sorted using BasePost), but schema resolution will look up Post. In most setups both resolve to the same schema so this is benign, but it's an inconsistency that could bite in configurations where delegate base and child carry different @@schema values. Consider deriving the owning model from the same realModel + otherModel pair used for the join table name.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/orm/src/client/executor/name-mapper.ts` around lines 86 - 102, The
owning-model selection uses the raw modelName instead of the field's origin
model, causing inconsistent schema lookup for delegate-inherited m2m fields;
update the loop that builds joinTableSchemaMap to compute realModel =
fieldDef.originModel ?? modelName (or similar) and then derive owningModel from
[realModel, m2m.otherModel].sort()[0] before calling
this.getTableSchema(owningModel) so the schema resolution matches the same
realModel used when naming the join table; reference getManyToManyRelation,
fieldDef.originModel, modelName, joinTableSchemaMap, and getTableSchema to
locate and change the logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@packages/orm/src/client/executor/name-mapper.ts`:
- Around line 567-585: The fallback in getTableSchema currently returns
joinTableSchemaMap.get(model) ?? 'public', which ignores a non-default provider
defaultSchema; update the unknown-model branch in getTableSchema so the final
fallback uses the provider defaultSchema (i.e. use joinTableSchemaMap.get(model)
?? (this.schema.provider.defaultSchema ?? 'public')) to match the logic used for
known models and avoid hardcoding 'public'; reference getTableSchema,
this.schema.models, joinTableSchemaMap and this.schema.provider.defaultSchema
when making the change.

---

Nitpick comments:
In `@packages/orm/src/client/executor/name-mapper.ts`:
- Around line 86-102: The owning-model selection uses the raw modelName instead
of the field's origin model, causing inconsistent schema lookup for
delegate-inherited m2m fields; update the loop that builds joinTableSchemaMap to
compute realModel = fieldDef.originModel ?? modelName (or similar) and then
derive owningModel from [realModel, m2m.otherModel].sort()[0] before calling
this.getTableSchema(owningModel) so the schema resolution matches the same
realModel used when naming the join table; reference getManyToManyRelation,
fieldDef.originModel, modelName, joinTableSchemaMap, and getTableSchema to
locate and change the logic.

In `@tests/regression/test/issue-2603.test.ts`:
- Around line 93-128: The test implicit m2m with models in different custom
schemas only asserts the created tag name and should also exercise SELECT-side
join-table resolution: after calling db.post.create (db.post.create in this
test), add a db.post.findFirst({ include: { tags: true } }) round-trip and
assert that the returned post has tags.length === 1 and the tag name matches
(use expect(post.tags.length).toBe(1) and expect(post.tags.map(t =>
t.name)).toEqual(['foo']) or equivalent), so both nested-create and subsequent
SELECT path for the join table are validated.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7430f94b-9158-4aa3-b7b2-ff5b263336ce

📥 Commits

Reviewing files that changed from the base of the PR and between 1cf4345 and ae78bbf.

📒 Files selected for processing (2)

• packages/orm/src/client/executor/name-mapper.ts
• tests/regression/test/issue-2603.test.ts