feat: add schema qualification hints for extension type errors

[7ttp]

Problem

When using extensions like ltree in the extensions schema, migrations can fail with cryptic errors:

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

This error is confusing because:

• It doesn't explain why the type isn't found
• Users don't know that schema-qualified references are needed
• Local and remote databases may have different search_path settings

Solution

Improve the CLI error message by inspecting the pgconn.PgError object and providing a helpful hint when extension types are not found.

When SQLSTATE 42704 (undefined_object) is returned for a missing type, the CLI now displays:

Hint: This type may be defined in a schema that's not in your search_path. Use schema-qualified type references to avoid this error: CREATE TABLE example (col extensions.ltree); Learn more: supabase migration new --help

Changes

• Modified pkg/migration/file.go to detect extension type errors via pgx error inspection
• Added extractTypeName() helper to parse type name from error message
• Provides dynamic hint with the actual type name (e.g., extensions.ltree)

Testing

• Inspects pgconn.PgError.Code for SQLSTATE 42704
• Checks error message contains "type" and "does not exist"
• Extracts type name using regex for accurate hint

Related

Addresses feedback from https://github.com/supabase/cli/issues/4572

[7ttp]

@sweatybridge can you confirm if adding extensions to the search_path after each RESET ALL is the right approach to keep types like ltree accessible during migrations? Just want to make sure this aligns with expected behavior before taking the PR out of draft. If you have any suggestions, I’m happy to adjust.

[sweatybridge]

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]

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]

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]

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

[coveralls]

Pull Request Test Coverage Report for Build 19908597392

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.03%) to 56.159%

---

Files with Coverage Reduction	New Missed Lines	%
internal/gen/keys/keys.go	5	12.9%
<!--	Total:	5

Totals
Change from base Build 19887353385:	-0.03%
Covered Lines:	6816
Relevant Lines:	12137

---

💛 - Coveralls

[7ttp]

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

[7ttp]

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