This PR syncs the latest troubleshooting guides from the
supabase/troubleshooting repository.
---------
Co-authored-by: github-docs-bot <github-docs-bot@supabase.com>
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## 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 navigation links in the getting started guide to direct users
to the correct documentation pages.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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 CLI installation guidance to recommend “global CLI usage”
phrasing and link to platform-specific installation pages
* Removed duplicate legacy note in the npm install guidance
* Reworded CLI update guidance to state updates use the “same channels”
* Expanded “Running Supabase locally” walkthrough with clear post-init
steps, start instructions, and clarified credentials output
* Clarified analytics schema wording from “will be stored” to “are
stored”
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This PR syncs the latest troubleshooting guides from the
supabase/troubleshooting repository.
Co-authored-by: github-docs-bot <github-docs-bot@supabase.com>
## 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 the database size guide to link read-only mode management
instructions to the correct documentation section for improved
navigation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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?
Guide to troubleshoot a warning that can be emitted by Realtime DB
broadcast.
Ref: https://github.com/supabase/realtime/pull/1941
Preview:
https://docs-git-docs-realtime-warn-send-supabase.vercel.app/docs/guides/troubleshooting/realtime-warn-sending-broadcast-message
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a troubleshooting guide for a broadcast-message warning observed
in Postgres logs.
* Explains why messages may be dropped when partitions/replication
streaming aren’t yet available and when they become available.
* Provides diagnostic steps and remediation (ensure a subscriber/client
is connected) and guidance for when repeated warnings indicate a real
issue requiring error inspection.
<!-- 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
## What kind of change does this PR introduce?
Docs update
## What is the current behavior?
Documenting limited regional availability which is no longer the case
## What is the new behavior?
Section about regional availability limits removed
## Additional context
Privatelink is now available in `eu-central-2`
## 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 -->
Reading through the guides and troubleshooting docs I found a set of
code examples that don't parse or run as written. Each is a small,
self-contained fix:
- **troubleshooting/postgres-logs**: the `regexp_contains(...)` call was
missing its closing parenthesis.
- **troubleshooting/rls-performance**: the PL/pgSQL `return` statement
was missing its terminating semicolon.
- **troubleshooting/supavisor-faq**: the `CREATE USER ... WITH PASSWORD`
string literal was unterminated (missing closing quote).
- **troubleshooting/google-auth-fails**: missing comma between
`provider` and `options` in the `signInWithOAuth` object literal.
- **integrations/supabase-for-platforms**,
**database/extensions/pg_graphql**,
**deployment/branching/working-with-branches**: missing commas between
JSON properties.
- **database/extensions/pgjwt**: the default algorithm was written
`'HSA256'`; the real default is `'HS256'` (used in both `sign` and
`verify`).
- **auth/auth-email-passwordless** (Dart): `signinwithotp` should be
`signInWithOtp`.
- **auth/third-party/firebase-auth**: `async function
setRoleCustomClaim() => {` mixed a function declaration with arrow
syntax.
- **storage/management/copy-move-objects**: the storage helper is
`storage.foldername(name)`, not `storage.folder(name)`.
- **troubleshooting/hsnw-index**: prose referred to
`maintance_work_mem`; the setting is `maintenance_work_mem` (the SQL in
the same file spells it correctly).
- **troubleshooting/pgcron-debugging**: a stray double quote inside the
`cron.job_run_details` code span.
13 files, all one-line fixes. Happy to split if you'd prefer.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Corrected code examples across authentication, database, storage, and
troubleshooting guides
* Fixed method naming and syntax errors in code snippets (Dart auth,
Node.js Firebase, SQL functions)
* Updated API signatures and variable names for accuracy
* Improved JSON formatting in example payloads
* Corrected typos in documentation text
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
## 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 project variables guidance to include publishable and secret
keys alongside existing options.
* Updated code examples across multiple frameworks to use publishable
keys instead of anon keys.
* Updated tool descriptions to reflect publishable key terminology.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This PR syncs the latest troubleshooting guides from the
supabase/troubleshooting repository.
---------
Co-authored-by: github-docs-bot <github-docs-bot@supabase.com>
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
## What kind of change does this PR introduce?
Docs update
## What is the current behavior?
Auth hooks documentation doesn't explicitly state that the hook name
configured in `config.toml` must correspond to available hooks to
prevent errors, which has caused confusion for some users.
## What is the new behavior?
Doc includes mention that hook name must correspond to available hooks.
## Additional context
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added clarification note regarding authentication hook configuration
requirements, specifying that hook names in configuration files must
correspond to available hook types.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
removes three extensions from the list on the Postgres Extensions docs
page because we do not expose those extensions to users. extensions
removed are: amcheck, pg_surgery, pg_freespacemap
also adds a small cosmetic change to clarify that "public" refers to the
`public` schema on the same documentation page
## 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?
extensions are listed at
https://supabase.com/docs/guides/database/extensions that will result in
permissions errors should users try to install them themselves, as they
require superuser access to install
## What is the new behavior?
removes those items from the list
## Additional context
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated extensions overview documentation with improved formatting for
better readability
* **Chores**
* Removed three extensions from the available extensions metadata
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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?
Document Realtime broadcast of binary payloads
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified binary payload behavior across SDKs and runtimes, including
version-gated support and which clients silently drop binaries.
* Added examples for sending binary messages via JavaScript, Swift, REST
(including file upload), and database broadcasts.
* Clarified REST payload handling (Content-Type selects JSON vs binary),
private messaging flag, and that batch endpoints accept JSON-only.
* Noted that channel.httpSend() uses REST starting in supabase-js
2.107.0.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
The Supabase MCP repo transferred from `supabase-community/supabase-mcp`
-> `supabase/mcp`. This updates links on docs and www to point to the
new location: https://github.com/supabase/mcp
The main one needing this change is the MCP docs page at `mcp.mdx`:
https://supabase.com/mcp
I also updated links in the changelog / blog for good measure, though I
can remove those changes if desired since the old URL redirects to the
new location.
Related: https://github.com/supabase/mcp/pull/295
Ref: AI-792
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated Supabase MCP server repository references across all
documentation guides, blog articles, changelog entries, and supporting
materials to direct users to the current official location.
* Refreshed documentation links including feature groups, setup
instructions, abilities documentation, and GitHub issue tracking URLs
for consistency.
* Updated MCP server release links in changelog.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
Sustained memory overcommitment is one of the failure patterns that most
often leads to databases being killed when the system runs out of
memory. Today the database report only shows used memory against total
RAM, which hides the kernel's commit accounting: a project can sit far
above its commit limit (RAM plus swap, adjusted by the overcommit ratio)
and the dashboard gives no signal until something breaks.
A combined chart with swap, overcommitment, and main memory was
considered too dense, and a standalone swap chart was not useful enough
on its own.
Linear: [DEBUG-119](https://linear.app/supabase/issue/DEBUG-119)
## Fix
Adds a separate "Memory commitment" chart between the existing memory
usage and swap charts. It plots `ram_commit_used` (Committed_AS) as the
main series with `ram_commit_limit` (CommitLimit) as the max-value
threshold line, so values approaching or crossing the limit are visually
obvious. Backend support for the two new metric attributes ships in
supabase/platform#33321.
## How to test
- Wait for the platform PR (supabase/platform#33321) to deploy so the
two new attributes are accepted by the infra monitoring endpoint.
- Open any project, navigate to Database -> Reports.
- Confirm the new "Memory commitment" chart appears between "Memory
usage" and "Swap usage".
- Confirm the chart shows two series: the committed memory bars/area and
a max line for the commit limit.
- Hover the legend and the chart to confirm the tooltips read clearly.
- Confirm the time range selector and chart sync (`syncId:
'database-reports'`) keep this chart aligned with the others.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added comprehensive guide for interpreting memory commitment patterns
in telemetry reports, including component breakdown, chart pattern
guidance, and actionable recommendations.
* **New Features**
* Added memory commitment chart to database observability dashboard,
displaying RAM commitment usage and limits.
* Extended monitoring API to support new RAM commitment metrics.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
## 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?
Currently, this doc outlines how to restore a dashboard backup which
only applies to projects that still use logical backups. Newer projects
cannot follow this process.
## What is the new behavior?
Adds an admonition to direct users with projects that use physical
backups to the correct guide.
Keeping the legacy guide content for now for older projects that may
still be using logical backups.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added clarification that dashboard backups are only available for
Supabase projects using logical backups. Projects using physical backups
are directed to refer to the CLI backup and restore guide instead.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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**
* Consolidated API key deprecation guidance into a reusable notice for
consistent messaging across docs. Announces deprecation of legacy
anon/service_role JWT-secret keys by end of 2026, instructs switching to
sb_publishable_xxx / sb_secret_xxx, and provides steps to locate and
copy both new and legacy keys. Applied across auth, getting-started,
API, and realtime guides.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: fadymak <dev@fadymak.com>
## What
Adds a getting-started guide for migrating an existing project from the
legacy JWT-based `anon` and `service_role` keys to the new publishable
(`sb_publishable_...`) and secret (`sb_secret_...`) keys.
The guide walks through the migration step by step:
- **Before you start** — maps legacy keys to their replacements.
- **Step 1** — create the new `default` keys.
- **Step 2 / 3** — swap the publishable key in client code and the
secret key in backend code.
- **Database Webhooks and `pg_net`** — move the key from the
`Authorization: Bearer` header to the `apikey` header (the new keys
aren't JWTs and are rejected on `Authorization`), with a Vault note for
not inlining secrets.
- **Step 4** — update Edge Functions, with two options: read the new env
vars (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`) and set
`verify_jwt = false`, or adopt the `@supabase/server` SDK.
- **Step 5 / 6** — verify nothing uses the legacy keys, then deactivate
them (reversible).
- **Next steps** — clarifies that JWT signing keys are a separate,
independent migration.
## Notes
While writing this we found Studio issues to fix separately (the Invoke
Function cURL snippet and the Database Webhooks editor both put the new
keys on the `Authorization` header).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a comprehensive migration guide for moving from legacy JWT-based
API keys to the new publishable and secret keys with zero‑downtime
steps, verification, limitations, and next steps.
* Clarified API key behavior and recommended migration actions in the
getting‑started docs.
* Added a navigation entry linking to the new migration guide.
* **Style**
* Relaxed documentation lint rules to allow expected wording/phrases
(e.g., "backends", "Database Webhooks").
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
## 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>
New guide at `/guides/api/handling-errors-in-supabase-js` that leads
with `error.hint` as the most useful field on a Postgres error. When the
database knows the fix (a `GRANT` statement to run for a `42501`, a
column name you probably meant), it puts the literal SQL in `hint`.
Logging only `error.message` hides it.
The guide covers the `PostgrestError` shape (fields ordered by
usefulness: hint first, message last), branching on `error.code`, and
parallel patterns for Auth, Storage, Edge Functions, and Realtime.
Linked from the API > Guides sidebar next to the existing PostgREST
error codes reference.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a comprehensive guide on handling errors in supabase-js,
explaining the {data, error} pattern and recommending logging full error
objects.
* Provides a recommended error-handling pattern, guidance to branch on
error codes, and example error fields.
* Adds component-specific advice for Auth, Storage, Edge Functions, and
Realtime, plus a “Related” links section.
* Added a navigation entry so the guide appears in the API guides
submenu.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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?
The access-control permissions matrix shows Developer-role users can
create development branches, but doesn't mention the implicit
production-branch registration step that runs on the first "Create
branch" click for a gitless project — which is
Owner/Administrator only. Customers reading the matrix conclude
Developers can branch from the start; in reality, an
Owner/Administrator has to perform the first branch creation to register
the production branch.
## What is the new behavior?
Adds a footnote on the "Development Branches → Create" row that flags
the one-time first-branch admin requirement and links to the
dashboard branching guide for the full explanation. Short cross-link
only — long-form mechanism explanation lives on the dashboard
branching guide (companion PR #46471).
## Additional context
- Companion PR adding the long-form admonition on the branching guide
page: #46471
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified branching permissions for dashboard (gitless) workflows: the
first branch creation (one-time) without a GitHub integration requires
Owner or Administrator to register the production branch; after that
initial step, Developers may create, update, and delete branches as
normal.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
# Second try of making a new better process for SDK automation
Instead of building a new pipeline. We will take the lessons learned
form round 1, plus the good design and improvement on DX quality for
drop-in file as a single step required from SDK team and produce almost
identical set of files as used right now to render using the current
pipeline.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* New reference-content pipeline producing per-library reference
artifacts and integrating into prebuilds, search ingestion, and
rendering (type-aware examples).
* **Documentation**
* Added comprehensive JavaScript SDK v2 reference content and partials
(Auth MFA, passkeys, admin, TypeScript support, filters, modifiers,
Installing, Initializing, Buckets, etc.).
* **Tests & CI**
* Added regression snapshot test and updated workflows to refresh
reference snapshots and ensure spec downloads.
* **Chores**
* Updated ignore rules, build scripts, Makefile targets, and package
lifecycle hooks.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Katerina Skroumpelou <mandarini@users.noreply.github.com>
Co-authored-by: Katerina Skroumpelou <sk.katherine@gmail.com>
## 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?
Bug fix (documentation) — fixes three internal links that currently 404.
## What is the current behavior?
Three docs pages link to internal paths that do not resolve (no matching
page, and no redirect in `apps/www/lib/redirects.js`):
| File | Link | Problem |
| --- | --- | --- |
| `guides/telemetry/reports.mdx` (×3) |
`/docs/content/guides/database/query-optimization` | Stray `content/`
path segment (the content folder name leaked into the public URL) |
| `guides/database/prisma.mdx` |
`/docs/guides/database/prisma-troubleshooting` | Page lives under the
`prisma/` subfolder |
| `guides/database/postgres/data-deletion.mdx` |
`/docs/blog/postgres-bloat` | Blog posts are served from `/blog`, not
`/docs/blog` |
No related issue — these are self-evident broken links found by checking
every internal `/docs/...` link against the actual pages, the redirects
config, and the dynamic doc routes.
## What is the new behavior?
The links now point to the correct, existing pages:
- `/docs/guides/database/query-optimization` (page:
`apps/docs/content/guides/database/query-optimization.mdx`)
- `/docs/guides/database/prisma/prisma-troubleshooting` (page:
`apps/docs/content/guides/database/prisma/prisma-troubleshooting.mdx`)
- `/blog/postgres-bloat` (post:
`apps/www/_blog/2024-04-26-postgres-bloat.mdx`; consistent with the ~30
other `/blog/...` links across the docs)
Docs-only change; no wording changes beyond the URLs. The `reports.mdx`
tables were re-aligned by Prettier as a result of the shortened links.
## Additional context
For each link I confirmed the target page/post file exists, that the
broken path has no rule in `apps/www/lib/redirects.js`, and that it is
not served by a dynamic Next.js route under `apps/docs/app/`.
After improving error handling on guides loader, of course, an error
emerged about a missing partial that doesn't exist anymore within the
project.
Removing the partial importing within MDX to fix search embedding
script.
**I have read the CONTRIBUTING.md file.**
YES
**What kind of change does this PR introduce?**
Docs update
**What is the current behavior?**
The Prisma quickstart and troubleshooting pages reference Prisma v6
patterns: `prisma-client-js` generator, `datasource db` with
`url`/`directUrl`, CommonJS imports, `ts-node`, and no driver adapter
setup.
**What is the new behavior?**
Updated for Prisma ORM v7:
- Install steps use `tsx`, `@prisma/adapter-pg`, `dotenv`, and `pg`
- New step for `prisma.config.ts` with `dotenv/config` and `DIRECT_URL`
- Schema uses `prisma-client` generator with explicit output,
provider-only `datasource db`
- Removed old `datasource db { url, directUrl }` block from serverless
tab
- Test file uses ESM imports from `./generated/prisma/client` and
`PrismaPg` driver adapter
- Troubleshooting cross-schema example updated to match v7 patterns
**Additional context**
Prisma v7 requires driver adapters, moves datasource config to
`prisma.config.ts`, and deprecates the `prisma-client-js` generator in
favor of `prisma-client`.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated Prisma quickstart: refreshed install and setup steps, added a
new runtime configuration step, adjusted migration + generate workflow,
and replaced the test API example with an ESM-style, dotenv-powered
snippet.
* Refined troubleshooting examples: clarified schema configuration
syntax and improved multi-schema guidance.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46082?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: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com>
## 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?
The troubleshooting entry
`edge-functions-worker-timeouts-and-websocket-drops.mdx` includes
frontmatter fields that are not part of the troubleshooting
template/schema, so it does not conform to the expected metadata shape.
## What is the new behavior?
The document now matches the supported troubleshooting template
metadata.
- **Frontmatter cleanup**
- Removed unsupported `teams` and `types` fields.
- Kept the existing supported metadata (`title`, `topics`, `keywords`)
unchanged.
- **Template alignment**
- Brings the page in line with
`/apps/docs/content/troubleshooting/_template.mdx`.
- Avoids schema drift for troubleshooting content.
```mdx
---
title = "Edge Functions worker timeouts and WebSocket drops"
topics = [ "functions" ]
keywords = [ "websocket", "timeout", "earlydrop", "wall clock", "cpu limit", "streaming", "cold start" ]
---
```
## Additional context
This is a surgical docs-only change to make the page consistent with the
troubleshooting content schema used by the docs app.
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Rodrigo Mansueli <rodrigo@mansueli.com>
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
## What kind of change does this PR introduce?
docs update
## What is the current behavior?
Storage RLS polices unintentionally allow list access to buckets
potentially setting a bad example for people starting a new project.
## What is the new behavior?
Use more restrictive RLS polices that only allow the intended operations
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated Supabase Storage access-control policies and examples across
docs and starter projects.
* Tightened avatar image access rules to require explicit operation
checks for public reads.
* Clarified guidance and added explanatory comments in migration and
README examples to illustrate the updated access patterns.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46172?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: Chris Chinchilla <chris.ward@supabase.io>
## 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?
The dashboard branching guide doesn't mention that the first "Create
branch" action on a project requires Owner/Administrator access.
Combined with cosmetic UI behavior: the branch dropdown displays `main /
PRODUCTION` on every project from day one, even though the backend
hasn't registered a production branch yet. Developer-role users hit a
403 with a generic "Not authorized to enable preview branching" toast on
their first branch attempt, with no docs or UI hint that an implicit
production-branch registration step is happening.
Customer-reported in
[SU-383693](https://supabase.frontapp.com/open/cnv_1mz95u3i?key=wbyHQkruuZ_KYRGnRPB5_yHzm5-fr_k4)
## What is the new behavior?
Adds an admonition under the "Creating a branch" heading in the
dashboard-branching guide explaining:
- The cosmetic UI vs. backend state mismatch (`main / PRODUCTION` shown
before any row exists)
- That the first "Create branch" click is what technically enables
branching on the project (populates `preview_branches` with`is_default =
true`)
- This step requires Owner/Administrator access
- After that one-time step, anyone with the Developer role can create,
update, and delete preview branches
Scoped to the gitless dashboard flow only. The GitHub-integrated path
bootstraps automatically during admin-only integration setup.
## Additional context
- Mechanism confirmed with the team in
[Slack](https://supabase.slack.com/archives/C02BJ2239GA/p1779978863774239)
"the first time branching is used we populate the preview_branches table
with the base project and have is_default set as true. This is
technically what enables branching. A developer role can't do that."
- Related FE improvement being escalated separately (clearer error
message and/or disabling the Create branch button for Developers when
the production branch hasn't been registered yet)
- The [Branching 2.0
announcement](https://supabase.com/blog/branching-without-git-is-now-the-default)
(May 2026) made gitless branching the default for new projects, and more
customers can walk into the dashboard flow without ever touching GitHub
integration.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added clarification on dashboard branching behavior when GitHub
integration is not configured, including details on branch dropdown
display and initial setup requirements with permission levels.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46471?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: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## 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?
Currently, we have a doc that was created to provide details about
platform audit logs (organization level)
## What is the new behavior?
This adds a detail about account audit logs, which provide the same
details as the platform audit log. The difference is account audit logs
only show logs for the specific user account.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Enhanced Platform Audit Logs guide to clarify that each account has
access to separate Account Audit logs for tracking individual user
activity.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46467?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 -->
## 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?
Adds details about error handling in the protocol and what users can
expect when handling them in client libs
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Expanded Realtime protocol "Error handling": describes four error
delivery paths, client lifecycle and recovery behaviors, and which
errors close or preserve channels.
* Clarifies join rejection parsing and retry/backoff guidance for join
error codes, plus special-case join reasons.
* Details channel-level system errors, Postgres subscription
degraded-state and ID-consistency rules, broadcast/presence error
shapes, in-band access_token refresh, and reconnection sequencing.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46292?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 -->
## What kind of change does this PR introduce?
Feature / abuse-prevention update. Resolves DEPR-198.
## What is the current behaviour?
Free projects using Supabase's built-in email service can edit raw Auth
email template subjects and HTML in Studio. That is the risky cohort
this project is trying to constrain.
## What is the new behaviour?
### Template editing restrictions
For free projects using Supabase's built-in email service, Studio keeps
Auth email templates viewable and previewable but disables subject/body
editing and saving. Editing is unlocked by setting up Custom SMTP,
configuring a send-email hook, or upgrading to a paid plan.
**Grandfathering:** projects created before `2026-06-01T00:00:00Z` (the
platform enforcement cutoff) are exempt; their editing UI stays
unlocked. This mirrors `FREE_TIER_TEMPLATE_BLOCK_CUTOFF_DATE` in the
platform PR exactly.
| After |
| --- |
| <img width="1024" height="759" alt="Emails Authentication Fizz Test
Supabase-173BB09B-0FB9-4133-8202-9E310DDB347A"
src="https://github.com/user-attachments/assets/c966212d-ed0c-443b-8197-440cc2937ef6"
/> |
| <img width="1024" height="759" alt="Emails Authentication Fizz Test
Supabase-CD5845EB-0E45-4779-8989-44E775B2411A"
src="https://github.com/user-attachments/assets/055a64d6-b5e8-4d37-a261-6e280f04536a"
/> |
### Warning dialogs on transitions that reset templates
Two flows now surface a warning before the user commits to a state
change that resets their custom email templates to defaults:
1. **Disabling custom SMTP** (SMTP settings page): a confirmation dialog
warns that templates will be reset to defaults and the email rate limit
reduced to 2 per hour. On confirm, Studio resets all 13 templates via
the existing per-template reset endpoint (`Promise.allSettled`). The
"won't be able to edit" sentence is shown only for post-cutoff projects;
grandfathered projects skip it. The corresponding server-side
enforcement is in the Platform PR:
https://github.com/supabase/platform/pull/33129
2. **Downgrading to the Free plan** (billing settings): an admonition in
the existing downgrade confirmation modal warns that custom templates
will be reset to defaults and won't be editable without custom SMTP. The
admonition is shown only when the org has at least one post-cutoff
project; orgs whose projects are all grandfathered skip it.
| Custom SMTP | Downgrading |
| --- | --- |
| <img width="862" height="586" alt="66764"
src="https://github.com/user-attachments/assets/6470c8a6-2f79-40a5-ad3b-bfe5b0ba9c54"
/> | <img width="1268" height="1552" alt="CleanShot 2026-05-22 at 17 28
37@2x-FEB1901E-38E6-42DF-8C27-0A036D8A1B94"
src="https://github.com/user-attachments/assets/e8caa9e6-c3ed-4787-b771-af77a43eb854"
/> |
### Informational admonition when enabling SMTP
When a user enables custom SMTP for the first time, a sandwiched
admonition above the save footer informs them that the email rate limit
will be increased to 30 per hour and can be adjusted.
_This is just a minor cosmetic change, unrelated to the email template
disabling. Sorry._
| Before | After |
| --- | --- |
| <img width="1024" height="759" alt="Emails Authentication Chisel
Toolshed Supabase-54317D18-803C-4A58-8211-2359355D083B"
src="https://github.com/user-attachments/assets/29eff649-02dc-40f3-a379-0b4d484a76c7"
/> | <img width="1024" height="759" alt="Emails Authentication Chisel
Toolshed Supabase-9E12399E-E9FB-4F9A-B029-A08008EA4B50"
src="https://github.com/user-attachments/assets/e542ed86-4da6-407e-8293-0f4c0f071e18"
/> |
## How to test
All existing projects pre-date the enforcement cutoff
(`2026-06-01T00:00:00Z`) and are grandfathered, so the restriction UI
won't appear by default. To force the restricted state locally,
back-date the cutoff in one file:
In
`apps/studio/components/interfaces/Auth/EmailTemplates/EmailTemplates.utils.ts`,
temporarily change:
```ts
export const FREE_TIER_TEMPLATE_BLOCK_CUTOFF_DATE = '2026-06-01T00:00:00Z'
```
to:
```ts
export const FREE_TIER_TEMPLATE_BLOCK_CUTOFF_DATE = '2025-01-01T00:00:00Z'
```
Revert before committing. With the cutoff back-dated, use a free-plan
project and:
- **Template restriction + admonition:** navigate to Authentication >
Emails with no custom SMTP configured. Subject/body fields should be
read-only and the "Set up SMTP" admonition should appear, with its
dropdown offering upgrade and send-email hook options.
- **SMTP disable warning:** enable custom SMTP on a project, then
disable it via Authentication > SMTP Settings. The confirmation dialog
should warn that templates will reset to defaults and that editing will
be restricted after disabling.
- **Downgrade warning:** in billing settings, initiate a downgrade to
the Free plan. The downgrade modal should include an admonition warning
about template reset and restricted editing (only if the org has at
least one post-cutoff project).
## Additional context
The default Auth email template copy was also improved across docs,
examples, and UI library snippets (separate prior commits).
The per-template reset button (`ResetTemplateDialog`) was migrated to
the async `AlertDialogAction` pattern introduced in #45960; the dialog
stays open and shows a loading state while the reset is in-flight,
closes on success, and stays open on error.
Closes PRODSEC-183
---------
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Stephen Morgan <stephen@doublethink.co.nz>
## Summary
Adds documentation for the new Logs pricing SKUs (Ingest and Query)
ahead of the July 1 launch. Part of the [O11Y Logs Pricing
RFC](https://linear.app/supabase/project/rfc-supabase-observability-product-packaging-and-pricing-77990c05a767)
rollout (PRD R6).
**This is the docs PR.** Pricing page changes (`apps/www`) and Studio
dashboard changes are separate PRs.
### New pages
- **Logs overview** (`manage-your-usage/logs.mdx`) — both SKUs at a
glance, summary pricing table, Logs vs Log Drains clarification
- **Logs Ingest detail** (`manage-your-usage/logs-ingest.mdx`) — full
billing details, invoice examples, optimization tips
- **Logs Query detail** (`manage-your-usage/logs-query.mdx`) — full
billing details, invoice examples, optimization tips
- **Pricing partials** for both SKUs (`pricing_logs_ingest.mdx`,
`pricing_logs_query.mdx`)
### Updated pages
- **Cost control** — added Logs Ingest + Logs Query to "Usage items
covered by the Spend Cap" list
- **Telemetry/logs** — added link to the new manage-usage overview page
- **Navigation sidebar** — added Logs, Logs Ingest, Logs Query entries
before Log Drains
### Notes
- Screenshots are marked as TODO placeholders — will be added once
Studio surfaces are live
- Follows the existing manage-usage page pattern (storage-size, MAU,
etc.)
- Canonical pricing: Ingest $0.50/GB over 5 GB, Query $0.002/GB over
1,000 GB (Free/Pro/Team)
## Test plan
- [x] Verify pages render at
`/docs/guides/platform/manage-your-usage/logs`, `/logs-ingest`,
`/logs-query`
- [x] Verify sidebar navigation shows new entries
- [x] Verify cost-control page lists both items under "covered by Spend
Cap"
- [x] Verify `<$Partial />` pricing tables render correctly
- [x] Verify telemetry/logs page shows new billing link
- [x] Verify no broken links
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added guides for managing Logs, Logs Ingest, and Logs Query usage with
pricing, billing scenarios, quota examples, and optimization tips
* Added Platform → Billing navigation items: Logs, Logs Ingest, Logs
Query
* Included overage pricing tables, Spend Cap coverage updates, “Coming
soon” billing caveats, clarified Logs vs. Log Drains, and linked usage
management from the Logging guide
* **Chore**
* Whitelisted "Better Stack" in spelling checks
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46095?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: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
## What kind of change does this PR introduce?
Docs update (new guides + follow-up documentation fix from review
feedback).
## What is the current behavior?
There was no consolidated docs example for resumable WebSockets with
Edge Functions, and no dedicated troubleshooting guide for worker
timeouts / WebSocket drops.
## What is the new behavior?
- Adds a resumable WebSockets guide for Edge Functions, including:
- session persistence
- event replay
- idempotency pattern and schema examples
- client/server example flow
- Adds an Edge Functions troubleshooting guide for worker timeouts and
WebSocket drops.
- Updates docs navigation to surface the new guides.
- Follow-up fix from review feedback: the browser client example now
stores `sessionId` and `lastEventId` in `sessionStorage` (instead of
`localStorage`).
## Additional context
- Branch has been updated with latest `origin/master`.
- This PR remains documentation-focused; no production runtime code
changes were introduced.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a guide on resumable WebSockets covering session persistence,
event replay, idempotency patterns, SQL schema examples, and
client/server usage.
* Added a troubleshooting guide on Edge Functions worker timeouts and
WebSocket drops with scenarios, symptoms, and practical workarounds.
* Enhanced WebSocket docs with a production note on worker lifecycle and
keeping runtime promises open to avoid premature shutdown.
* Navigation updated to surface the new guides.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46178?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: Lakshan Perera <lakshan@supabase.io>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: CodeRabbit <noreply@coderabbit.ai>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
