Skip to content

fix: add schema qualification hints for extension type errors - #4513

Merged
sweatybridge merged 3 commits into
supabase:developfrom
7ttp:fix/ltree-extension-search-path
Feb 7, 2026
Merged

fix: add schema qualification hints for extension type errors#4513
sweatybridge merged 3 commits into
supabase:developfrom
7ttp:fix/ltree-extension-search-path

Conversation

@7ttp

@7ttp7ttp commented Nov 25, 2025•
edited
Loading

Copy link
Copy Markdown
Member

Summary

Improve CLI migration errors for undefined PostgreSQL extension types by adding a context aware hint for unqualified type references.

Problem

Migrations can fail with:

ERROR: type "ltree" does not exist (SQLSTATE 42704)

This error does not indicate whether the type is missing due to schema visibility,
extension installation, or configuration differences.

Solution

Inspect pgconn.PgError during migration execution and conditionally provide a schema-qualification hint only when the referenced type is not already schema-qualified.

Related

@7ttp
7ttp requested a review from a team as a code ownerNovember 25, 2025 20:46
@7ttp
7ttp changed the base branch from main to developNovember 25, 2025 20:51
@7ttp
7ttp marked this pull request as draft November 25, 2025 21:01
@sweatybridge

sweatybridge commented Nov 26, 2025

Copy link
Copy Markdown
Contributor

Thanks for checking. Our current recommendation is to always use schema qualified references in your migration file. For eg.

CREATETABLEtest (pathextensions.ltreeNOT NULL);

This avoids ambiguity in default search path resolution which can be configured per session, per role, or per cluster.

The default search path for Supabase postgres role is currently set to $user, public, extensions. We can't guarantee that it won't be changed in the future. Therefore, I think it's not ideal to make such assumptions in the CLI migration tool.

@7ttp

7ttp commented Nov 26, 2025•
edited
Loading

Copy link
Copy Markdown
MemberAuthor

Thanks for checking. Our current recommendation is to always use schema qualified references in your migration file. For eg.

CREATETABLEtest (pathextensions.ltreeNOT NULL);

This avoids ambiguity in default search path resolution which can be configured per session, per role, or per cluster.

The default search path for Supabase postgres role is currently set to $user, public, extensions. We can't guarantee that it won't be changed in the future. Therefore, I think it's not ideal to make such assumptions in the CLI migration tool.

@sweatybridge Thanks for the elaboration! I get that relying on a fixed search_path isn’t future-proof.
That said, the current type "ltree" does not exist errors are pretty opaque especially since local and remote migrations behave differently.
instead I can:
update docs to recommend schema qualified types
improve the error message when an extension type isn’t found
optionally add a CLI hint suggesting extensions.ltree
Let me know if that approach is fine and frameable for a pr, I can revise this patch accordingly.

@sweatybridge

sweatybridge commented Nov 26, 2025

Copy link
Copy Markdown
Contributor

improve the error message when an extension type isn’t found
optionally add a CLI hint suggesting extensions.ltree

Do you plan to do this by inspecting the error object returned from pgx? If so, that sounds good to me.

Thanks for your help.

@7ttp

7ttp commented Nov 26, 2025

Copy link
Copy Markdown
MemberAuthor

improve the error message when an extension type isn’t found
optionally add a CLI hint suggesting extensions.ltree

Do you plan to do this by inspecting the error object returned from pgx? If so, that sounds good to me.

Thanks for your help.

Yep, I’ll inspect the pgx error and add the clearer message + schema qualification hint. On it

@7ttp
7ttpforce-pushed the fix/ltree-extension-search-path branch from b68f5bb to 1b972d2CompareNovember 26, 2025 10:40
@coveralls

coveralls commented Nov 26, 2025•
edited
Loading

Copy link
Copy Markdown

Pull Request Test Coverage Report for Build 21779030687

Details

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • 5 unchanged lines in 1 file lost coverage.
  • Overall coverage decreased (-0.02%) to 55.376%
Files with Coverage ReductionNew Missed Lines%
internal/gen/keys/keys.go512.9%
TotalsCoverage Status
Change from base Build 21777876298:-0.02%
Covered Lines:7123
Relevant Lines:12863
💛 - Coveralls

@7ttp
7ttpforce-pushed the fix/ltree-extension-search-path branch from 1b972d2 to 711463fCompareNovember 26, 2025 11:29
@7ttp7ttp changed the title fix: ensure extensions schema is accessible during migration executionfeat: improve error messages for undefined extension typesNov 26, 2025
@7ttp7ttp changed the title feat: improve error messages for undefined extension typesfeat: add schema qualification hints for extension type errorsNov 26, 2025
@7ttp
7ttp marked this pull request as ready for review November 26, 2025 13:14
@7ttp

7ttp commented Nov 27, 2025

Copy link
Copy Markdown
MemberAuthor

@sweatybridge whenever you have a moment, a quick review would be appreciated. 💚

sweatybridge
sweatybridge reviewed Nov 27, 2025
View reviewed changes

@sweatybridgesweatybridge 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.

Just a few nitpicks

Comment threadpkg/migration/file.go Outdated
Comment threadpkg/migration/file.go Outdated
@7ttp

7ttp commented Nov 27, 2025•
edited
Loading

Copy link
Copy Markdown
MemberAuthor

@sweatybridge All requested changes have been applied. Ready for rereview.

sweatybridge
sweatybridge requested changes Dec 2, 2025
View reviewed changes
Comment threadpkg/migration/file.go
@7ttp
7ttpforce-pushed the fix/ltree-extension-search-path branch from 8def4f9 to 3395b48CompareDecember 3, 2025 20:57
@7ttp

7ttp commented Feb 6, 2026

Copy link
Copy Markdown
MemberAuthor

@sweatybridge heyy!
(sorry for the ping on an old PR)
Can u please have another look at this aswell?? 😁💚

@sweatybridge

sweatybridge commented Feb 7, 2026

Copy link
Copy Markdown
Contributor

Can we add some unit tests for the new code please?

@7ttp
feat: improve error messages for undefined extension types
4b51978
Inspect pgx errors for SQLSTATE 42704 (undefined_object) and provide
helpful hints when extension types are not found. The error message now:
- Detects 'type does not exist' errors
- Extracts the type name from the error message
- Suggests using schema-qualified references (e.g., extensions.ltree)
- Provides a concrete example in the error output
This addresses the issue where migrations work locally but fail remotely
with opaque 'type does not exist' errors, making it clear to users that
they should use schema-qualified type references instead of relying on
search_path settings.
@7ttp
feat: add IsSchemaQualified method to skip hint for schema-qualified …
1229547
…types
@7ttp
test: add unit tests for extractTypeName function
c01e0da
@7ttp
7ttpforce-pushed the fix/ltree-extension-search-path branch from b2873f8 to c01e0daCompareFebruary 7, 2026 11:01
@7ttp

7ttp commented Feb 7, 2026

Copy link
Copy Markdown
MemberAuthor

Can we add some unit tests for the new code please?

Added unit tests for extractTypeName function

@sweatybridgesweatybridge changed the title feat: add schema qualification hints for extension type errorsfix: add schema qualification hints for extension type errorsFeb 7, 2026
@sweatybridge
sweatybridge merged commit f7b79ef into supabase:developFeb 7, 2026
14 of 16 checks passed
@7ttp
7ttp deleted the fix/ltree-extension-search-path branch February 7, 2026 11:12
@supabase-cli-releasersupabase-cli-releaserBot mentioned this pull request Feb 10, 2026
Merged
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sweatybridgesweatybridgesweatybridge approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Ltree extension should be in extension or public schema?

3 participants

@7ttp@sweatybridge@coveralls