Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
sweatybridge merged 3 commits into from
Feb 7, 2026
Merged

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

sweatybridge merged 3 commits into from
Feb 7, 2026
+107 −1

Conversation

@7ttp
Copy link
Contributor

@7ttp 7ttp commented Nov 25, 2025 •
edited
Loading

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 owner November 25, 2025 20:46
@7ttp 7ttp changed the base branch from main to develop November 25, 2025 20:51
@7ttp 7ttp marked this pull request as draft November 25, 2025 21:01
@sweatybridge
Copy link
Contributor

sweatybridge commented Nov 26, 2025

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

CREATE TABLE test (path extensions.ltree NOT 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
Copy link
Contributor Author

7ttp commented Nov 26, 2025 •
edited
Loading

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

CREATE TABLE test (path extensions.ltree NOT 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
Copy link
Contributor

sweatybridge commented Nov 26, 2025

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
Copy link
Contributor Author

7ttp commented Nov 26, 2025

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 7ttp force-pushed the fix/ltree-extension-search-path branch from b68f5bb to 1b972d2 Compare November 26, 2025 10:40
@coveralls
Copy link

coveralls commented Nov 26, 2025 •
edited
Loading

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 Reduction New Missed Lines %
internal/gen/keys/keys.go 5 12.9%
Totals Coverage Status
Change from base Build 21777876298: -0.02%
Covered Lines: 7123
Relevant Lines: 12863
💛 - Coveralls

@7ttp 7ttp force-pushed the fix/ltree-extension-search-path branch from 1b972d2 to 711463f Compare November 26, 2025 11:29
@7ttp 7ttp changed the title fix: ensure extensions schema is accessible during migration execution feat: improve error messages for undefined extension types Nov 26, 2025
@7ttp 7ttp changed the title feat: improve error messages for undefined extension types feat: add schema qualification hints for extension type errors Nov 26, 2025
@7ttp 7ttp marked this pull request as ready for review November 26, 2025 13:14
@7ttp
Copy link
Contributor Author

7ttp commented Nov 27, 2025

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

sweatybridge
sweatybridge reviewed Nov 27, 2025
View reviewed changes
Copy link
Contributor

@sweatybridge sweatybridge left a comment

Choose a reason for hiding this comment

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

Just a few nitpicks

@7ttp
Copy link
Contributor Author

7ttp commented Nov 27, 2025 •
edited
Loading

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

@7ttp 7ttp requested a review from sweatybridge November 27, 2025 15:49
sweatybridge
sweatybridge requested changes Dec 2, 2025
View reviewed changes
@7ttp 7ttp force-pushed the fix/ltree-extension-search-path branch from 8def4f9 to 3395b48 Compare December 3, 2025 20:57
@7ttp 7ttp requested a review from sweatybridge December 3, 2025 21:34
@7ttp
Copy link
Contributor Author

7ttp commented Feb 6, 2026

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

@sweatybridge
Copy link
Contributor

sweatybridge commented Feb 7, 2026

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

7ttp added 3 commits February 7, 2026 16:31
@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 7ttp force-pushed the fix/ltree-extension-search-path branch from b2873f8 to c01e0da Compare February 7, 2026 11:01
@7ttp
Copy link
Contributor Author

7ttp commented Feb 7, 2026

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

Added unit tests for extractTypeName function

@sweatybridge sweatybridge changed the title feat: add schema qualification hints for extension type errors fix: add schema qualification hints for extension type errors Feb 7, 2026
@sweatybridge sweatybridge merged commit f7b79ef into supabase:develop Feb 7, 2026
14 of 16 checks passed
@7ttp 7ttp deleted the fix/ltree-extension-search-path branch February 7, 2026 11:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sweatybridge sweatybridge sweatybridge 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