From 08c0fc247bbcfb441f03482ba0498a78ac6b79c3 Mon Sep 17 00:00:00 2001 From: Utkarash Kumar Singh Date: Tue, 19 May 2026 15:42:44 +0100 Subject: [PATCH] feat(studio): warn about pg_graphql introspection change on upgrade (#46096) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit introspection ## 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 ## 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 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) --------- Co-authored-by: Joshen Lim --- .../guides/database/extensions/pg_graphql.mdx | 8 ++- .../content/guides/platform/upgrading.mdx | 34 +++++++++++++ .../Infrastructure/InfrastructureInfo.tsx | 18 ++++--- .../Infrastructure/UpgradeWarnings.tsx | 51 ++++++++++++++++++- .../project-upgrade-eligibility-query.ts | 1 + packages/api-types/types/api.d.ts | 4 ++ supa-mdx-lint/Rule003Spelling.toml | 1 + 7 files changed, 109 insertions(+), 8 deletions(-) diff --git a/apps/docs/content/guides/database/extensions/pg_graphql.mdx b/apps/docs/content/guides/database/extensions/pg_graphql.mdx index e724379d995..389dc09ddd6 100644 --- a/apps/docs/content/guides/database/extensions/pg_graphql.mdx +++ b/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 diff --git a/apps/docs/content/guides/platform/upgrading.mdx b/apps/docs/content/guides/platform/upgrading.mdx index d589dd42477..58a2c79a6e1 100644 --- a/apps/docs/content/guides/platform/upgrading.mdx +++ b/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. diff --git a/apps/studio/components/interfaces/Settings/Infrastructure/InfrastructureInfo.tsx b/apps/studio/components/interfaces/Settings/Infrastructure/InfrastructureInfo.tsx index 7468e0c470b..0df92efc963 100644 --- a/apps/studio/components/interfaces/Settings/Infrastructure/InfrastructureInfo.tsx +++ b/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 ( <> @@ -227,9 +229,13 @@ export const InfrastructureInfo = () => { ) ) : null} - {showDatabaseUpgrades && data && !data.eligible && hasValidationErrors ? ( - - ) : null} + {showDatabaseUpgrades && data && !data.eligible && ( + + )} + + {showDatabaseUpgrades && data && ( + + )} )} diff --git a/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx b/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx index f46f83cfe87..ba02bf5116f 100644 --- a/apps/studio/components/interfaces/Settings/Infrastructure/UpgradeWarnings.tsx +++ b/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 (
@@ -142,3 +147,47 @@ export const ValidationErrorsWarning = ({ ) } + +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) => ( + + + + )) +} diff --git a/apps/studio/data/config/project-upgrade-eligibility-query.ts b/apps/studio/data/config/project-upgrade-eligibility-query.ts index 8e62c0441f2..2f922756647 100644 --- a/apps/studio/data/config/project-upgrade-eligibility-query.ts +++ b/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. diff --git a/packages/api-types/types/api.d.ts b/packages/api-types/types/api.d.ts index 0ef1b6b20a7..07d186d944d 100644 --- a/packages/api-types/types/api.d.ts +++ b/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 diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml index 6d6937c8b11..c57e093dde1 100644 --- a/supa-mdx-lint/Rule003Spelling.toml +++ b/supa-mdx-lint/Rule003Spelling.toml @@ -225,6 +225,7 @@ allow_list = [ "Grafana", "Grafana OnCall", "GraphQL", + "GraphiQL", "Groonga", "HackerOne", "[Hh][Aa][Pp]roxy",