feat: improve error messages for undefined extension types

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.

Author: 7ttp

pkg/migration/file.go

@@ -96,6 +96,20 @@ func (m *MigrationFile) ExecBatch(ctx context.Context, conn *pgx.Conn) error {
 			if len(pgErr.Detail) > 0 {
 				msg = append(msg, pgErr.Detail)
 			}
+			// Provide helpful hint for extension type errors (SQLSTATE 42704: undefined_object)
+			if pgErr.Code == "42704" && strings.Contains(pgErr.Message, "type") && strings.Contains(pgErr.Message, "does not exist") {
+				// Extract type name from error message (e.g., 'type "ltree" does not exist')
+				typeName := extractTypeName(pgErr.Message)
+				msg = append(msg, "")
+				msg = append(msg, "Hint: This type may be defined in a schema that's not in your search_path.")
+				msg = append(msg, "      Use schema-qualified type references to avoid this error:")
+				if typeName != "" {
+					msg = append(msg, fmt.Sprintf("        CREATE TABLE example (col extensions.%s);", typeName))
+				} else {
+					msg = append(msg, "        CREATE TABLE example (col extensions.<type_name>);")
+				}
+				msg = append(msg, "      Learn more: supabase migration new --help")
+			}
 		}
 		msg = append(msg, fmt.Sprintf("At statement: %d", i), stat)
 		return errors.Errorf("%w\n%s", err, strings.Join(msg, "\n"))
@@ -120,6 +134,18 @@ func markError(stat string, pos int) string {
 	return strings.Join(lines, "\n")
 }
 
+// extractTypeName extracts the type name from PostgreSQL error messages like:
+// 'type "ltree" does not exist' -> "ltree"
+func extractTypeName(errMsg string) string {
+	// Match pattern: type "typename" does not exist
+	re := regexp.MustCompile(`type "([^"]+)" does not exist`)
+	matches := re.FindStringSubmatch(errMsg)
+	if len(matches) > 1 {
+		return matches[1]
+	}
+	return ""
+}
+
 func (m *MigrationFile) insertVersionSQL(conn *pgx.Conn, batch *pgconn.Batch) error {
 	value := pgtype.TextArray{}
 	if err := value.Set(m.Statements); err != nil {

pkg/migration/file_test.go

@@ -77,4 +77,47 @@ func TestMigrationFile(t *testing.T) {
 		assert.ErrorContains(t, err, "ERROR: schema \"public\" already exists (SQLSTATE 42P06)")
 		assert.ErrorContains(t, err, "At statement: 0\ncreate schema public")
 	})
+
+	t.Run("provides helpful hint for extension type errors", func(t *testing.T) {
+		migration := MigrationFile{
+			Statements: []string{"CREATE TABLE test (path ltree NOT NULL)"},
+			Version:    "0",
+		}
+		// Setup mock postgres
+		conn := pgtest.NewConn()
+		defer conn.Close(t)
+		conn.Query(migration.Statements[0]).
+			ReplyError("42704", `type "ltree" does not exist`).
+			Query(INSERT_MIGRATION_VERSION, "0", "", migration.Statements).
+			Reply("INSERT 0 1")
+		// Run test
+		err := migration.ExecBatch(context.Background(), conn.MockClient(t))
+		// Check error
+		assert.ErrorContains(t, err, `type "ltree" does not exist`)
+		assert.ErrorContains(t, err, "Hint: This type may be defined in a schema")
+		assert.ErrorContains(t, err, "extensions.ltree")
+		assert.ErrorContains(t, err, "supabase migration new --help")
+		assert.ErrorContains(t, err, "At statement: 0")
+	})
+
+	t.Run("provides generic hint when type name cannot be extracted", func(t *testing.T) {
+		migration := MigrationFile{
+			Statements: []string{"CREATE TABLE test (id custom_type)"},
+			Version:    "0",
+		}
+		// Setup mock postgres
+		conn := pgtest.NewConn()
+		defer conn.Close(t)
+		conn.Query(migration.Statements[0]).
+			ReplyError("42704", `type does not exist`).
+			Query(INSERT_MIGRATION_VERSION, "0", "", migration.Statements).
+			Reply("INSERT 0 1")
+		// Run test
+		err := migration.ExecBatch(context.Background(), conn.MockClient(t))
+		// Check error
+		assert.ErrorContains(t, err, "type does not exist")
+		assert.ErrorContains(t, err, "Hint: This type may be defined in a schema")
+		assert.ErrorContains(t, err, "extensions.<type_name>")
+		assert.ErrorContains(t, err, "supabase migration new --help")
+	})
 }