## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update.
## What is the current behavior?
Linear:
[CLI-1618](https://linear.app/supabase/issue/CLI-1618/update-cli-workflow-docs-for-pg-delta-default-diffing)
Four docs pages lag the shipped CLI behavior now that `pg-delta` is the
default diff engine for projects created by a recent `supabase init`:
- **CLI workflows** claims `db diff` compares `supabase/schemas/`
against migrations. Under `pg-delta`, declarative files are never the
`db diff` baseline (and `[db.migrations].schema_paths` no longer changes
it) — the declarative flow goes through `supabase db schema declarative
sync`. The cleanup guidance describes `migra`-era output.
- **Declarative database schemas** teaches the old `db diff -f` +
`schema_paths` flow throughout, and its known-caveats list is the
`migra` issue list.
- **Managing environments** still presents `--use-migra` as an
"experimental flag" for a "more concise" diff — inverted now.
- **Backup and restore (migrating within Supabase)** and the CLI
workflows guide both steer users to `db diff`/`db pull` with `--schema
auth,storage`. Under `pg-delta`, `--schema` layers an extra exclude
policy on top of the Supabase profile: it can only narrow a diff, never
re-include managed schemas, and managed-schema selections can even fail
closed (e.g. `--schema auth` when a trigger function lives in `public`).
Unfiltered diffs are the supported path.
## What is the new behavior?
All claims verified against the CLI source at current `develop` —
including supabase/cli#6300, which upgraded the engine to
`@supabase/pg-delta` 1.0.0-alpha.46 — against the pinned pg-delta
package source (profile rules, format defaults, coverage doc), and
against a live dogfood run of the documented workflows on `develop`
`38f31b4` (two OSS corpus projects, warm shadow cache).
- **`cli-workflows.mdx`**: adds a "Which diff engine you're on" note
(`pg-delta` for new `supabase init` projects, `migra` for existing ones
until they opt in by adding `[experimental.pgdelta] enabled = true`;
per-run fallbacks `--use-migra` on `db diff` / `--diff-engine migra` on
`db pull`); corrects `db pull` and `db diff` mechanics (shadow built
from migrations vs. live database; the baseline history record is
offered, not unconditional); switches the declarative flow to `supabase
db schema declarative sync`; reworks the cleanup section around pg-delta
output (uppercase keywords at max width 180, `format_options`, per-unit
migration files with numeric segment suffixes, the `-- pg-delta:
transaction=false` directive on genuinely non-transactional files,
engine-neutral grant/revoke review guidance, coverage warnings +
`--strict-coverage`); documents what pg-delta captures in managed
schemas (user triggers, RLS policies on `auth` tables and on
`storage.objects`/`storage.buckets`/`realtime.messages`) versus what it
doesn't; adds key-command rows for the declarative commands and
troubleshooting entries (`db pull` non-zero exit when in sync, the
`schema_paths` warning, `PGDELTA_DEBUG=1` bundles under
`supabase/.temp/pgdelta/v2/debug/`).
- **`declarative-database-schemas.mdx`**: swaps `db diff -f` for `db
schema declarative sync -f` throughout; replaces
lexicographic/`schema_paths` ordering guidance with automatic dependency
ordering and the `generate` export layout (`_cluster/`, reserved
`_custom/`); bootstraps from production via `db schema declarative
generate --linked` (explicit target + `--overwrite` in scripts) and
refreshes via `db pull --declarative`; rewrites known caveats for
pg-delta (DML including storage buckets, untracked object kinds + the
`_custom/` escape hatch, managed schemas, extension-managed objects, and
the two gates when adopting an existing schema tree:
`[experimental.webhooks]` for `pg_net` migrations and declaring the
tree's extensions) keeping the `migra` workflow and issue list under a
legacy section for projects that haven't enabled it.
- **`managing-environments.mdx`**: frames the verbose grant sample as
legacy-engine output, notes that generated migrations can include grant
statements on any engine, describes `--use-migra` as a single-run
fallback, and adds a `db diff --strict-coverage` CI step.
- **`backup-restore.mdx`**: replaces `db diff --linked --schema
auth,storage` with a plain `db diff --linked` on `pg-delta` (keeping the
`--schema auth,storage` form for the legacy engine) and explains what
the engine includes (user triggers on managed tables, user RLS policies
on `auth`, `storage.objects`/`storage.buckets`/`realtime.messages`) and
what must be recreated manually.
- **New `diff-engines.mdx` page** (from #49889): the single home for how
the engine is selected, a behavior matrix for `pg-delta` versus `migra`,
the per-command fallback flags, a procedure for switching an existing
project (the first `db pull` after enabling may write a catch-up
migration), and how to go back with `enabled = false`. Registered in
navigation. A shared `diff_engine_check` partial replaces the inline
engine parentheticals across seven pages, and a
`managed_schemas_diff_capture` partial carries the managed-schema
capture rules.
- **CLI reference (`cli_v1_commands.yaml`, `cli_v1_config.yaml`)**: `db
pull`, `db schema declarative sync`/`generate` flags and descriptions,
`experimental.pgdelta.*` and `db.migrations.schema_paths` config keys,
and the `db diff` description updated to describe both engines. Note
that `cli_v1_commands.yaml` is generated from the CLI repo;
[supabase/cli#6557](https://github.com/supabase/cli/pull/6557) carries
the matching `db pull` example and overlay text so the next publish
keeps it.
- **`examples/prompts/declarative-database-schema.md`**: rewritten for
the `db schema declarative sync` flow, with the `[experimental.pgdelta]`
prerequisite.
## Additional context
The first draft was written against pg-delta 1.0.0-alpha.42.
supabase/cli#6300 (engine upgrade to alpha.46) then changed two
documented behaviors, both reflected here: generated SQL now defaults to
uppercase pretty-printed keywords, and user RLS policies on
`storage.objects`/`storage.buckets`/`realtime.messages` are included via
the engine's `SUPABASE_USER_POLICY_SURFACES` allowlist. A follow-up
dogfood run on `develop` `38f31b4` then falsified three more claims
(pg-delta emits no grant noise, `_schema_changes`/`_after_enum_values`
multi-file names, directive on every split file), all corrected in the
last commit.
**Update (Sep 14 to 17):**
[#49889](https://github.com/supabase/supabase/pull/49889) and
[#50220](https://github.com/supabase/supabase/pull/50220) were merged
into this branch, so this PR now carries the full stack. #50220
corrected the `schema_paths` warning wording (the CLI warns only when
the setting lists paths), added `auth` RLS policies to the
managed-schema partial, and described the migra initial pull accurately
(the `pg_dump` skips managed schemas and the migra diff pass that
follows appends the trigger and policy changes). It also reframed
`pg-delta` as the default for every project ahead of supabase/cli#6391.
That plan changed: no breaking default flip before Select, so
[#50332](https://github.com/supabase/supabase/pull/50332) restores the
opt-in framing (`pg-delta` requires `[experimental.pgdelta] enabled =
true`, which `supabase init` writes for new projects) and also resolves
the four CodeRabbit findings from the latest review round.
Two claims are pending confirmation from the owning teams: that
branching runs every migration in a transaction and ignores the `--
pg-delta: transaction=false` directive, and the `--db-url`
pooler-versus-direct connection advice, which currently disagrees with
the CLI's own `db pull` docs.
Stale spots found in the CLI repo's own docs while verifying (out of
scope here, worth follow-ups): four `SIDE_EFFECTS.md` files still claim
lowercase output, `docs/supabase/db/diff.md` still lists `migra`-era
"known failure cases" that alpha.46 fully models, the `supabase init`
template's commented `format_options` example shows `maxWidth: 80`
against an actual default of 180, and the CLI upgrade recipe appends
`--experimental` even when the config already enables pg-delta.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01SUuaVmXLRbV6tZjzhka3cp
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified `pg-delta` and legacy `migra` behavior, configuration, and
switching guidance.
* Expanded declarative schema workflows, including synchronization,
migration generation, baselines, deployment, and legacy-engine support.
* Documented managed schemas, permissions, extensions, transaction
handling, dependency ordering, and troubleshooting.
* Added guidance for strict coverage checks, output directories,
non-interactive workflows, and declarative pull modes.
* Added a dedicated diff engines guide and updated CLI navigation,
backup and restore, branching, deployment, and CI documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Wen Bo Xie <wenbox323@gmail.com>
Closes DOCS-1313
Closes FDBKIN-4573
Closes FDBKIN-15214
Closes FDBKIN-10628
## Problem
Four asks come up repeatedly in feedback intake. The Eval is green and
this feedback cannot be included in the Eval. Using the Evals work as an
excuse to action on the feedback. 😄
Readers can't tell which auth call verifies a token and which only reads
stored state. They don't know that the response the cookies were written
to is the response they have to return, because that only ever existed
as a code comment. Nobody is warned that refreshing in two places burns
a single-use refresh token, which surfaces as users being signed out at
random. And nothing in `apps/docs` says `proxy.ts` is Next.js 16 and
later, so a reader on 15 writes a file the framework never calls.
## Solution
- Add the fact that `getClaims()` refreshes a session close to expiring
before it verifies. It was only in the typedoc remarks, and it is what
makes the double refresh warning make sense.
- Say that `setAll` rebuilds `supabaseResponse` on every write, so a
response built earlier is stale, and show how to copy the cookies onto a
different one.
- Warn that a second refresh outside the reuse window revokes the
session, linking refresh token reuse detection.
- Note that `proxy.ts` is Next.js 16 and later, and that the file is
`middleware.ts` before that.
- Name the file in the proxy fence in
`examples/prompts/nextjs-supabase-auth.md`, which gave agents the export
name and no path.
The auth methods partial is shared by five other pages, so that first
change surfaces there too.
## Manual testing
1. Open the [SSR client
guide](https://docs-git-docs-ssr-client-feedback-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client)
on the deploy preview. The Next.js panel carries the version note, the
refresh warning, and the response guidance.
2. Select the refresh token reuse detection link. It resolves to the
sessions guide.
3. Open the [Next.js Auth
prompt](https://docs-git-docs-ssr-client-feedback-supabase.vercel.app/docs/guides/ai-tools/ai-prompts/nextjs-supabase-auth).
The proxy section names the file and says it is `proxy.ts` on Next.js 16
and later.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
- Clarified that `getClaims` refreshes sessions when access tokens are
near expiration, helping server-rendered sessions remain active.
- Expanded Next.js SSR guidance for session-refresh setup, including
file placement and version-specific naming.
- Added warnings about refresh-token reuse and session revocation after
repeated refreshes outside the reuse window.
- Added guidance for preserving authentication cookies and cache-related
headers when returning updated responses.
- Clarified that refreshed tokens should be passed to Server Components
to keep sessions active.
- Clarified the required session-refresh handler export and example
filename.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## TL;DR
aligns the remaining Phase 2 Edge Functions docs snippets with
`@supabase/server`
## Whats Fixed?
updated outdated imports and version references, and refreshed JSON
examples to use Response.json()
where it makes sense. left non-JSON responses as is where the
integration or format actually needs them
## Ref:
- towards COM-269
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated numerous Edge Function guides and examples to use modern
`npm:`/`jsr:` import specifiers instead of legacy Deno URL imports.
* Standardized success and error responses to return JSON consistently
(using `Response.json()` and equivalent helpers) and added/clarified
appropriate HTTP status codes.
* Improved example error payload shapes in several guides for clearer,
structured failures.
* **Chores**
* Refreshed version ranges in documentation and examples across SDKs and
client libraries.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
Migrates the Edge Functions **documentation** from the legacy
`Deno.serve` + manual `createClient` pattern to the
[`@supabase/server`](https://github.com/supabase/server) `withSupabase`
wrapper. This is the part of
[COM-269](https://linear.app/supabase/issue/COM-269) that AI coding
assistants index, so it's split out to ship first; the standalone
`examples/` functions follow in a second PR.
## Canonical pattern
```ts
import { withSupabase } from 'npm:@supabase/server@1'
export default {
fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
const { data } = await ctx.supabase.from('countries').select('*')
return Response.json({ data })
}),
}
```
- `export default { fetch }` object shape (not `Deno.serve`, not a bare
default export), versioned `npm:@supabase/server@1`.
- `auth` mode picks the caller: `user` → `ctx.supabase` (RLS);
`secret`/`publishable`/`none` → set `verify_jwt = false`, `secret` uses
`ctx.supabaseAdmin`.
- `Response.json(...)` over `new Response(JSON.stringify(...))`.
## Changes
- **AI prompt** (`examples/prompts/edge-functions.md`) — rewritten to
lead with `withSupabase` as the default; `auth`-mode table;
`@supabase/server@1`. Highest AI-indexing impact.
- **connect-to-postgres** — "Using supabase-js" now uses `ctx.supabase`
(+ its CodeSample deps `postgres-on-the-edge`, `drizzle`).
- **Example pages** — semantic-search, push-notifications,
amazon-bedrock, cloudflare-turnstile, og-image, send-emails,
slack-bot-mention, auth-send-email-hook.
- **Guides** — ai-models, background-tasks, routing (+ `restful-tasks`
dep), kysely-postgres, sentry-monitoring, upstash-redis, elevenlabs ×2,
websockets, cors (reframed: CORS is automatic with `withSupabase`).
## Notable fixes
- **websockets**: the JWT-auth examples had a latent bug — handler
wasn't `async` and called `getClaims()` without the extracted token. Now
`await supabase.auth.getUser(jwt)`. (`withSupabase` can't authenticate
WebSocket clients since they can't send headers — noted in the page.)
- **restful-tasks**: fixed a broken `npm:supabase-js` import →
`npm:@supabase/supabase-js`.
## Follow-ups (not in this PR)
- The ~42 standalone `examples/` edge functions → second PR.
- A dedicated `withSupabase` intro page (today it's only documented
inside the auth-framed "Securing Edge Functions" page).
- `.claude/skills/supabase-server/SKILL.md` is stale (`allow:` vs
`auth:`).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated Edge Function examples to the modern withSupabase + exported
fetch handler pattern across guides and examples.
* Standardized JSON response/error handling (uses built-in JSON helpers)
and preserved streaming/SSE behaviors where applicable.
* Clarified auth modes, context clients (user vs admin), and automatic
CORS handling; removed manual preflight boilerplate.
* Updated local serve/deploy instructions to include --no-verify-jwt for
relevant examples.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
Edge Function examples that use the new publishable/secret API keys read
them with a double lookup:
```ts
const SUPABASE_SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
const secretKey = Deno.env.get(SUPABASE_SECRET_KEYS['default']) // ❌ returns undefined
```
`SUPABASE_SECRET_KEYS` / `SUPABASE_PUBLISHABLE_KEYS` are a JSON object
that maps a key name to the **actual key value** (e.g.
`{"default":"sb_secret_..."}`), confirmed by:
- the self-hosted injection in `docker/docker-compose.yml`
(`SUPABASE_SECRET_KEYS: "{\"default\":\"${SUPABASE_SECRET_KEY:-}\"}"`)
- the `@supabase/server` SDK README
So `SUPABASE_SECRET_KEYS['default']` is already the key. Wrapping it in
another `Deno.env.get(...)` looks up an env var named `sb_secret_...`,
which doesn't exist, so the value is `undefined` and the examples fail
at runtime.
## Fix
Unwrap the outer `Deno.env.get(...)` so the key is read directly:
```ts
const SUPABASE_SECRET_KEYS = JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)
const secretKey = SUPABASE_SECRET_KEYS['default'] // ✅
```
Applied across 23 files (example functions, the
`examples/prompts/edge-functions.md` codegen guidance, and two docs
guides). The correct `JSON.parse(Deno.env.get('SUPABASE_SECRET_KEYS')!)`
declaration line is untouched. The generated `apps/docs/examples/` copy
regenerates from `examples/` at build time.
## Notes
- Docs context:
[#46600](https://github.com/supabase/supabase/pull/46600), which
documents the same key model.
- Follow-up (not in this PR): a few examples send the secret key on the
`Authorization: Bearer` header, which the new keys reject. Worth a
separate audit.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified examples and guides for correctly reading parsed Supabase
secret and publishable key maps.
* **Examples**
* Standardized credential usage across Edge Functions and samples so
Supabase clients consistently receive keys from the parsed key maps
rather than indirect lookups.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated examples and guides to use Supabase publishable (client) keys
instead of anon keys for client-side usage across frameworks and
platforms.
* Renamed environment variable examples and .env templates to reflect
publishable key naming.
* Adjusted sample requests and client-init examples to send/use the
publishable key via the apikey header where applicable.
* Updated references from service_role to secret for server-side
credential guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: fadymak <fady@fadymak.com>
## What
Updates all `setAll` cookie handler implementations across docs and
examples to accept the new `headers` second argument introduced in
`@supabase/ssr` v0.10.0
([supabase/ssr#176](https://github.com/supabase/ssr/pull/176)).
## Why
`@supabase/ssr` v0.10.0 introduced a breaking change: `setAll` now
receives a required second argument `headers: Record<string, string>`
alongside the cookies array. When a token refresh occurs, the library
passes cache headers (`Cache-Control`, `Expires`, `Pragma`) that must be
applied to the HTTP response to prevent CDN caching of auth responses.
Because TypeScript allows functions with fewer parameters to satisfy a
type expecting more, existing `setAll` implementations do not produce a
type error when the second argument is omitted. Users who copy an
outdated snippet will silently miss the CDN protection.
Root cause and context:
[supabase/supabase-js#1682](https://github.com/supabase/supabase-js/issues/1682)
## Changes
**Proxy/middleware contexts** (where token refreshes happen) now apply
the cache headers to their response:
- Next.js proxy files: `supabaseResponse.headers.set(key, value)`
- SvelteKit hooks: `event.setHeaders(headers)`
- Hono middleware: `c.header(key, value)`
- Pages Router (Express-style): `ctx.res.setHeader(key, value)`
- Remix/React Router loaders and actions: applied to response headers
(outer `headers` variable renamed to `responseHeaders` to avoid naming
conflict with the new param)
**Server Component and API route contexts** (no response object
available) accept `_headers` without applying them.
## Files updated
- `apps/docs/content/guides/auth/server-side/creating-a-client.mdx`
(inline Astro, Remix, React Router, Express snippets)
- `apps/docs/content/_partials/oauth_pkce_flow.mdx`
- `apps/docs/content/guides/auth/oauth-server/getting-started.mdx`
- `apps/docs/content/guides/auth/passwords.mdx`
-
`apps/docs/content/troubleshooting/how-to-migrate-from-supabase-auth-helpers-to-ssr-package-5NRunM.mdx`
- `examples/auth/nextjs/`, `examples/auth/nextjs-full/` (proxy + server)
- `examples/auth/sveltekit/`, `examples/auth/sveltekit-full/`
- `examples/auth/hono/`, `examples/auth/hono-full/`
- `examples/user-management/nextjs-user-management/` (proxy + server)
- `examples/user-management/sveltekit-user-management/`
- `examples/realtime/nextjs-authorization-demo/` (proxy + server)
- `examples/realtime/nextjs-auth-presence/` (pages router)
- `examples/prompts/nextjs-supabase-auth.md`
* Quickstart next 16 update
* Fix paths and env vars
* docs: refactor nextjs server-side auth to use Proxy instead of middleware
* docs: refactor nextjs server-side auth to match proxy
* docs: refactor nextjs example to match Proxy
* docs: refactor nextjs auth AI prompt to match Proxy
* docs: refactor nextjs sentry telemetry integration to match Proxy
* examples: update nextjs realtime example to match middleware
* docs: refactoring guides to use nextjs proxy
* examples: update nextjs-full example to match Next16 template
* example: update nextjs-user-management to match nextjs 16
* docs: refactoring nextjs user-management tutorial to use typescript only
* docs: refactoring nextjs quickstart, removing step 4
since this step is already included on `with-supabase` template, we can
just remove this redundant step
* docs: auth-helpers nextjs pages, Nextjs16 proxy disclaimer
* stamp: lint
* stamp: revert 'NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY'
* stamp: nextjs examples, revert to use cookie options
* fix(docs): typo
* docs: updating nextjs-auth troubleshoot guide to match proxy
* Update apps/docs/content/guides/getting-started/quickstarts/nextjs.mdx
* Revert auth-helpers changes
* Revert auth-helpers content
* Apply suggestions from code review
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Update apps/docs/content/troubleshooting/how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV.mdx
* Apply suggestions from code review
* Prettier
---------
Co-authored-by: kallebysantos <kalleby_santos@hotmail.com>
* remove glob from all examples
* Add declarative schema instructions
* run prettier
* update file extension for declarative-database-schema rule
* update the example prompts in the examples folder
* remove displaying heading for the AI prompts
* remove the prompt note for test
* revert the change for not displaying the heading for the menu
* Add back the title for each prompt
* allow putting frontmatter before heading
---------
Co-authored-by: Charis Lam <26616127+charislam@users.noreply.github.com>
* Update the instruction to add to project
* bringing Cursor at the front, because that is the most popular one of all
* Add sample description and globs for all sample prompt within the docs
* remove the cursor rule I created by mistake
* fix typo
