fix(postgrest): address a hinted embed by its table name outside the select list

[spydon]

Summary

Follow-up to #1960, from a review of that PR.

A relation with a foreign key hint and no alias, such as a hand-written PostgrestToOneRelation('users!messages_username_fkey', ...), was addressed by its hinted name everywhere outside the select list. PostgREST matches those paths against the alias or the table name only. Checked against the local stack:

Request	Result
messages.limit=1	applied, 1 row
messages!username.limit=1	silently ignored, every row
order=users(username).desc	applied
order=users!username(username).desc	PGRST100 parse error

Outside the select list, the embed is now addressed by its alias, or by the table name without the hint. This fixes embedded() scopes, and also the to-one order keys and embeddedFilterName, which had the same bug before #1960. Typegen always pairs a hint with an alias, so generated tables were not affected.

Other changes

• The embedded() dartdoc now says exactly what a repeated call does: a later limit replaces only the limit, and a later range replaces both the offset and the limit.
• The untyped order() merges its key through appendOrderKey instead of duplicating the merge logic.
• In MIGRATION.md, the foreign key paragraph is back next to the relation text it explains, and the snippet is wrapped to 80 characters.

Testing

• New unit tests cover a hinted embed with no alias in a scope, in an order key and in a filter name.
• The full postgrest suite passes against the local stack (623 tests). melos analyze and dcm analyze are clean.

Summary by CodeRabbit

• Bug Fixes

  • Embedded ordering and filters now correctly use the referenced table name when a foreign-key hint is present without an alias, while preserving the hint in the select expression.

• Documentation

  • Clarified how to address embedded relations when multiple foreign keys point to the same table.
  • Updated guidance on how repeated embedded sort keys, limits, and ranges are applied.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Repository: supabase/supabase-flutter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6d87c62a-6eea-4ff3-bb60-1fb40eb0f78c

📥 Commits

Reviewing files that changed from the base of the PR and between 0800e8f and adcf87f.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: supabase/supabase-flutter/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: f752c4af-fb3a-4798-8a99-7403f921b0ef

📥 Commits

Reviewing files that changed from the base of the PR and between 973de4f and 0800e8f.

📒 Files selected for processing: 6

• MIGRATION.md
• packages/postgrest/lib/src/postgrest_embedded_relation.dart
• packages/postgrest/lib/src/postgrest_transform_builder.dart
• packages/postgrest/lib/src/postgrest_typed_transform_builder.dart
• packages/postgrest/test/postgrest_embedded_relation_test.dart
• packages/postgrest/test/typed_query_test.dart

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

📝 Walkthrough

Unaliased foreign-key-hinted relations now use the alias or table name for references outside the select list. Order-key formatting delegates query-parameter merging to appendOrderKey. Tests and documentation cover the relation naming and embedded query behavior.

Changes: Embedded relation references

Layer / File(s)	Summary
Resolve embedded relation references packages/postgrest/lib/src/postgrest_embedded_relation.dart, packages/postgrest/lib/src/postgrest_transform_builder.dart, packages/postgrest/lib/src/postgrest_typed_transform_builder.dart, packages/postgrest/test/postgrest_embedded_relation_test.dart, packages/postgrest/test/typed_query_test.dart, MIGRATION.md	_reference returns the alias or table name, not the full hinted relation name. Order-key merging uses appendOrderKey. Tests verify that select expressions retain foreign-key hints while ordering, filters, and limits use the table name. Documentation describes generated hints and aliases and the behavior of repeated embedded calls.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: androidpoet

Merge Risk: ⚪ Minimal · up to 0800e

Embedded query parameters use the alias or table name while the select expression retains its relationship hint and join modifier, matching PostgREST’s documented syntax. No material merge-blocking risk remains.

Pre-merge checks: 5

Passed checks: 5 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: addressing hinted embeds by their table name outside the select list.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches: 💡 1

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}