feat(studio): warn about pg_graphql introspection change on upgrade (#46096)

<img width="1512" height="818" alt="introspection"
src="https://github.com/user-attachments/assets/5c0e4c6a-c0e9-496d-8768-4a55a2433268"
/>
## Summary

Adds an in-product admonition on the Infrastructure Settings page when a
project has pg_graphql < 1.6.0 installed, warning users that GraphQL
introspection will be disabled by default after upgrading. Links to
upgrade notes docs with the opt-in SQL.

The admonition is purely informational — it renders alongside the
upgrade button, does not block the upgrade.

## Context

pg_graphql 1.6.0 disables GraphQL introspection by default. The change
is upgrade-triggered (not backported), so users on 1.5.x will only
encounter it when their AMI bundles 1.6.0+. To prevent surprise breakage
of tools that rely on `__schema`/`__type` (GraphiQL, codegen, Relay
compiler, etc.), Studio surfaces this admonition before they upgrade.

Design discussion in
[PSQL-1199](https://linear.app/supabase/issue/PSQL-1199/prepare-dashboard-notification-for-pg-graphql-breaking-change).

## Companion PR

This depends on the schema change in
[supabase/platform#32954](https://github.com/supabase/platform/pull/32954)
which adds the new `warnings` field to
`ProjectUpgradeEligibilityResponse`.

## Admonition copy

- **Title:** \"GraphQL introspection will be disabled by default after
upgrade\"
- **Body:** \"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.\"
- **CTA:** \"Read upgrade notes\" → links to the new docs section


## Related

- Linear:
[PSQL-1199](https://linear.app/supabase/issue/PSQL-1199/prepare-dashboard-notification-for-pg-graphql-breaking-change)
- Parent rollout:
[PSQL-1163](https://linear.app/supabase/issue/PSQL-1163/breaking-change-pg-graphql-introspection-rollout)
- Companion platform PR: https://github.com/supabase/platform/pull/32954


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added “Upgrading to pg_graphql 1.6.0” and updated pg_graphql docs:
introspection is disabled by default, how to re-enable per schema,
verification steps, and affected tools.

* **New Features**
* Upgrade settings UI now shows validation warnings about introspection
with links to upgrade notes.

* **Chores**
* Added "GraphiQL" to MDX spelling allow list and added upgrade-warning
types to API surface.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46096?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Joshen Lim <joshenlimek@gmail.com>

apps/docs/content/guides/database/extensions/pg_graphql.mdx

@@ -100,7 +100,13 @@ returning the JSON
 }
 ```
 
-Note that `pg_graphql` fully supports schema introspection so you can connect any GraphQL IDE or schema inspection tool to see the full set of fields and arguments available in the API.
+Note that `pg_graphql` supports schema introspection, so you can connect any GraphQL IDE or schema inspection tool to see the full set of fields and arguments available in the API. Starting from `pg_graphql` 1.6.0, introspection is **disabled by default** and must be enabled per schema:
+
+```sql
+comment on schema public is e'@graphql({"introspection": true})';
+```
+
+See the [upgrade notes](/guides/platform/upgrading#upgrading-to-pg_graphql-160) for details.
 
 ## API
 

apps/docs/content/guides/platform/upgrading.mdx

@@ -172,3 +172,37 @@ Projects planning to upgrade from Postgres 15 to Postgres 17 need to first disab
 `pgjwt` was enabled by default on every Supabase project up until Postgres 17. If you weren’t explicitly using `pgjwt` in your project, it’s most likely safe to disable.
 
 Existing projects on lower versions of Postgres are not impacted, and the extensions will continue to be supported on projects using Postgres 15, until the end of life of Postgres 15 on the Supabase platform.
+
+### Upgrading to pg_graphql 1.6.0
+
+Starting with pg_graphql 1.6.0, GraphQL introspection is disabled by default. After the upgrade, queries to `__schema` and `__type` will return an error unless introspection is explicitly enabled. See the [pg_graphql configuration docs](https://supabase.github.io/pg_graphql/configuration/#introspection) for full details.
+
+This affects tools that rely on introspection:
+
+- Studio's GraphQL inspector (GraphiQL)
+- External GraphiQL or GraphQL Playground
+- Code generators (e.g. `graphql-codegen`)
+- Relay compiler
+- Any tool that calls `__schema` or `__type` directly
+
+Regular data queries (e.g. `accountCollection`, `insertIntoAccountCollection`) are not affected.
+
+To re-enable introspection on a schema, run the following SQL in the SQL editor:
+
+```sql
+comment on schema public is e'@graphql({"introspection": true})';
+```
+
+If your schema already has a comment with other directives (e.g. `inflect_names`), combine the keys — setting a new comment overwrites the old one:
+
+```sql
+comment on schema public is e'@graphql({"inflect_names": true, "introspection": true})';
+```
+
+To verify introspection is enabled:
+
+```sql
+select graphql.resolve('{ __schema { queryType { name } } }');
+```
+
+Existing projects on pg_graphql 1.5.x are not impacted unless they choose to upgrade.

apps/studio/components/interfaces/Settings/Infrastructure/InfrastructureInfo.tsx

@@ -16,7 +16,11 @@ import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
 import { GenericSkeletonLoader } from 'ui-patterns/ShimmeringLoader'
 
 import { ProjectUpgradeAlert } from '../General/Infrastructure/ProjectUpgradeAlert'
-import { ReadReplicasWarning, ValidationErrorsWarning } from './UpgradeWarnings'
+import {
+  ReadReplicasWarning,
+  ValidationErrorsWarning,
+  ValidationWarningsAdmonition,
+} from './UpgradeWarnings'
 import { NoticeBar } from '@/components/interfaces/DiskManagement/ui/NoticeBar'
 import {
   ScaffoldContainer,
@@ -83,8 +87,6 @@ export const InfrastructureInfo = () => {
   const isInactive = project?.status === 'INACTIVE'
   const hasReadReplicas = (databases ?? []).length > 1
 
-  const hasValidationErrors = (data?.validation_errors ?? []).length > 0
-
   return (
     <>
       <ScaffoldDivider />
@@ -227,9 +229,13 @@ export const InfrastructureInfo = () => {
                       )
                     ) : null}
 
-                    {showDatabaseUpgrades && data && !data.eligible && hasValidationErrors ? (
-                      <ValidationErrorsWarning validationErrors={data.validation_errors ?? []} />
-                    ) : null}
+                    {showDatabaseUpgrades && data && !data.eligible && (
+                      <ValidationErrorsWarning validationErrors={data.validation_errors} />
+                    )}
+
+                    {showDatabaseUpgrades && data && (
+                      <ValidationWarningsAdmonition warnings={data.warnings} />
+                    )}
                   </>
                 )}
               </>

apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx

@@ -4,7 +4,10 @@ import { Button } from 'ui'
 import { Admonition } from 'ui-patterns/admonition'
 
 import { InlineLink } from '@/components/ui/InlineLink'
-import { ProjectUpgradeEligibilityValidationError } from '@/data/config/project-upgrade-eligibility-query'
+import {
+  ProjectUpgradeEligibilityValidationError,
+  ProjectUpgradeEligibilityWarning,
+} from '@/data/config/project-upgrade-eligibility-query'
 import { DOCS_URL } from '@/lib/constants'
 
 export const ReadReplicasWarning = ({ latestPgVersion }: { latestPgVersion: string }) => {
@@ -126,6 +129,8 @@ export const ValidationErrorsWarning = ({
 }: {
   validationErrors: ProjectUpgradeEligibilityValidationError[]
 }) => {
+  if (validationErrors.length === 0) return null
+
   return (
     <Admonition type="note" showIcon={false} title="A newer version of Postgres is available">
       <div className="flex flex-col gap-3">
@@ -142,3 +147,47 @@ export const ValidationErrorsWarning = ({
     </Admonition>
   )
 }
+
+const getWarningTitle = (warning: ProjectUpgradeEligibilityWarning): string => {
+  switch (warning.type) {
+    case 'pg_graphql_introspection_change':
+      return 'GraphQL introspection will be disabled by default after upgrade'
+  }
+}
+
+const getWarningDescription = (warning: ProjectUpgradeEligibilityWarning): string => {
+  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.'
+  }
+}
+
+const getWarningLink = (warning: ProjectUpgradeEligibilityWarning): string => {
+  switch (warning.type) {
+    case 'pg_graphql_introspection_change':
+      return `${DOCS_URL}/guides/platform/upgrading#upgrading-to-pg_graphql-160`
+  }
+}
+
+export const ValidationWarningsAdmonition = ({
+  warnings,
+}: {
+  warnings: ProjectUpgradeEligibilityWarning[]
+}) => {
+  if (warnings.length === 0) return null
+
+  return warnings.map((warning, idx) => (
+    <Admonition
+      key={`${warning.type}-${idx}`}
+      type="default"
+      title={getWarningTitle(warning)}
+      description={getWarningDescription(warning)}
+    >
+      <Button asChild type="default" className="mt-2">
+        <Link href={getWarningLink(warning)} target="_blank" rel="noreferrer">
+          Read upgrade notes
+        </Link>
+      </Button>
+    </Admonition>
+  ))
+}

apps/studio/data/config/project-upgrade-eligibility-query.ts

@@ -14,6 +14,7 @@ export type ProjectUpgradeEligibilityResponse =
   components['schemas']['ProjectUpgradeEligibilityResponse']
 export type ProjectUpgradeEligibilityValidationError =
   ProjectUpgradeEligibilityResponse['validation_errors'][number]
+export type ProjectUpgradeEligibilityWarning = ProjectUpgradeEligibilityResponse['warnings'][number]
 
 /**
  * Fetches upgrade eligibility information for a project.

packages/api-types/types/api.d.ts

@@ -3749,6 +3749,10 @@ export interface components {
             type: 'active_replication_slot'
           }
       )[]
+      warnings: {
+        /** @enum {string} */
+        type: 'pg_graphql_introspection_change'
+      }[]
     }
     ProjectUpgradeInitiateResponse: {
       tracking_id: string

supa-mdx-lint/Rule003Spelling.toml

@@ -225,6 +225,7 @@ allow_list = [
     "Grafana",
     "Grafana OnCall",
     "GraphQL",
+    "GraphiQL",
     "Groonga",
     "HackerOne",
     "[Hh][Aa][Pp]roxy",