Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(upgrade): surface ltree reindex + operator estimator upgrade warnings (#47003)

Utkarash Kumar Singha5b820d51bd3
diff --git a/apps/docs/content/guides/platform/upgrading.mdx b/apps/docs/content/guides/platform/upgrading.mdx
index 25d87e3ebc7..047d2a3751d 100644
--- a/apps/docs/content/guides/platform/upgrading.mdx
+++ b/apps/docs/content/guides/platform/upgrading.mdx
@@ -189,3 +189,59 @@ select graphql.resolve('{ __schema { queryType { name } } }');
```
Existing projects on pg_graphql 1.5.x are not impacted unless they choose to upgrade.
+
+### Ltree indexes require reindexing after upgrade
+
+After upgrading, indexes on `ltree` columns that were built under the previous version can return incomplete results — for example, label searches silently miss rows that are present — until the index is rebuilt. This affects databases using a multibyte encoding (such as UTF-8) or a non-`libc` collation provider (ICU or builtin).
+
+This is silent: no error is raised. Affected queries return fewer rows than expected until the indexes are reindexed.
+
+To find affected indexes, run the following in the SQL editor:
+
+```sql
+select schemaname, tablename, indexname
+from pg_indexes
+where
+ indexname in (
+ select c.relname
+ from
+ pg_index as i
+ join pg_class as c on i.indexrelid = c.oid
+ join pg_attribute as a on a.attrelid = i.indrelid and a.attnum = ANY(i.indkey)
+ join pg_type as t on a.atttypid = t.oid
+ where t.typname in ('ltree', '_ltree')
+ );
+```
+
+To remediate, reindex each affected index. `REINDEX INDEX CONCURRENTLY` runs online with no downtime:
+
+```sql
+REINDEX INDEX CONCURRENTLY <index_name>;
+```
+
+### Custom operator selectivity estimators
+
+Attaching a non-built-in (extension- or user-provided) selectivity estimator function to an operator now requires superuser. Existing operators continue to work — the check only fires when an operator is (re)created, most commonly during `pg_dump` / `pg_restore`, a logical restore, or a branch.
+
+Because Supabase database roles are not superusers, recreating such an operator on your behalf (for example during a restore or branch) can fail with:
+
+```
+ERROR: must be superuser to specify a non-built-in restriction estimator function
+```
+
+Most projects are not affected. To check whether your database has any user-defined operators that reference a non-built-in estimator:
+
+```sql
+SELECT n.nspname AS schema, o.oprname AS operator
+FROM pg_operator o
+JOIN pg_namespace n ON o.oprnamespace = n.oid
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+ AND ((o.oprrest <> 0 AND o.oprrest::oid >= 10000)
+ OR (o.oprjoin <> 0 AND o.oprjoin::oid >= 10000))
+ AND NOT EXISTS (
+ SELECT 1 FROM pg_depend d
+ WHERE d.classid = 'pg_operator'::regclass AND d.objid = o.oid AND d.deptype = 'e'
+ );
+```
+
+If this returns no rows, your project is unaffected.
diff --git a/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx b/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx
index 669a0d23d84..db1ca7378d6 100644
--- a/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx
+++ b/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx
@@ -160,6 +160,10 @@ const getWarningTitle = (warning: ProjectUpgradeEligibilityWarning): string => {
switch (warning.type) {
case 'pg_graphql_introspection_change':
return 'GraphQL introspection will be disabled by default after upgrade'
+ case 'ltree_reindex_required':
+ return 'ltree indexes must be reindexed after this upgrade'
+ case 'operator_estimator_gate':
+ return 'Custom operators may need attention after this upgrade'
}
}
@@ -167,6 +171,10 @@ const getWarningDescription = (warning: ProjectUpgradeEligibilityWarning): strin
switch (warning.type) {
case 'pg_graphql_introspection_change':
return 'After upgrading, queries to `__schema` and `__type` will return an error unless introspection is explicitly re-enabled on the schema. Regular data queries are not affected.'
+ case 'ltree_reindex_required':
+ return 'After upgrading, ltree indexes on this database can return incomplete results until they are rebuilt. Run `REINDEX INDEX CONCURRENTLY` on the affected indexes — this runs online with no downtime.'
+ case 'operator_estimator_gate':
+ return 'After upgrading, recreating an operator that references a non-built-in selectivity estimator (for example during a restore or branch) requires superuser and may fail. Most projects are not affected.'
}
}
@@ -174,6 +182,10 @@ const getWarningLink = (warning: ProjectUpgradeEligibilityWarning): string => {
switch (warning.type) {
case 'pg_graphql_introspection_change':
return `${DOCS_URL}/guides/platform/upgrading#upgrading-to-pg_graphql-160`
+ case 'ltree_reindex_required':
+ return `${DOCS_URL}/guides/platform/upgrading#ltree-indexes-require-reindexing-after-upgrade`
+ case 'operator_estimator_gate':
+ return `${DOCS_URL}/guides/platform/upgrading#custom-operator-selectivity-estimators`
}
}
diff --git a/packages/api-types/types/api.d.ts b/packages/api-types/types/api.d.ts
index c6be0ea7421..6283a1679fe 100644
--- a/packages/api-types/types/api.d.ts
+++ b/packages/api-types/types/api.d.ts
@@ -3826,10 +3826,20 @@ export interface components {
type: 'project_hibernating'
}
)[]
- warnings: {
- /** @enum {string} */
- type: 'pg_graphql_introspection_change'
- }[]
+ warnings: (
+ | {
+ /** @enum {string} */
+ type: 'pg_graphql_introspection_change'
+ }
+ | {
+ /** @enum {string} */
+ type: 'ltree_reindex_required'
+ }
+ | {
+ /** @enum {string} */
+ type: 'operator_estimator_gate'
+ }
+ )[]
}
ProjectUpgradeInitiateResponse: {
tracking_id: string
diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml
index de50cd51728..a870771011f 100644
--- a/supa-mdx-lint/Rule003Spelling.toml
+++ b/supa-mdx-lint/Rule003Spelling.toml
@@ -94,6 +94,7 @@ allow_list = [
"[Ll]odash",
"LogEvent",
"[Ll]oopback",
+ "[Ll]tree",
"[Mm]atryoshka",
"[Mm][Cc][Pp]",
"[Mm]essageBird",
@@ -104,6 +105,7 @@ allow_list = [
"[Mm]iscapitalization",
"[Mm]isreport",
"[Mm]onorepos?",
+ "[Mm]ultibyte",
"[Mm]ultimodal",
"[Mm]ultipart",
"[Mm]ultithreading",