## 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. Restructure, mostly moved lines, plus inbound anchor fixes.
## What is the current behavior?
The page states the same routing decision four times and never states an
answer:
- Intro bullets
- A matrix table
- A "How to choose the right connection method?" section
- A Mermaid flowchart
An agent asked "I'm deploying to Vercel serverless functions, set up the
database connection" has to synthesize an answer from four partial,
inconsistent restatements. Context, procedure, and reference material
are interleaved throughout, so background reading interrupts the action
path.
The page is also too long at 2,883 words, and grouping alone doesn't fix
that. Explainer and reference material need their own page, and the
troubleshooting group belongs in troubleshooting entries.
16 of the 19 inbound anchor links to this page are already broken on
`master`, before any restructure: `#direct-connections`,
`#shared-pooler`, `#connection-pooler`, `#how-connection-pooling-works`,
`#quick-summary`, `#connection-pool`, and `#connecting-with-drizzle`.
Groundwork for [DOCS-1312](https://linear.app/supabase/issue/DOCS-1312).
The issue stays open until the paired eval is re-run.
## What is the new behavior?
Group the guide into a decision, a procedure, context, reference, and
troubleshooting, per CONTRIBUTING § Guides on mixed information types.
Review with `git diff --color-moved=zebra`.
- Lead with "Which connection method do you use?", a decision table
keyed on where your code runs. Section navigation sits directly below
the intro.
- Collect every connection string under "Get your connection string",
with the shared Connect dialog steps stated once as a procedure.
- Move the endpoint, port, pool size, and connection limit material into
"Connection reference". These were FAQ questions.
- Split the page. The guide keeps the decision, the connection strings,
and the quickstarts, at 1,180 words and three paths. A new child page,
Connection pooling and limits, carries how pooling works, pool size,
connection limits, and monitoring.
- Move the endpoint and IP version table up beside the connection
strings it explains.
- Replace the troubleshooting group with two new troubleshooting
entries, `tenant-or-user-not-found` and
`fatal-password-authentication-failed`, plus links to the existing
entries. The existing connection-refused entry is stronger than what was
here: it names the IP ban and gives the unban procedure.
- Cut the pool size worked example. It said a pool size of 30 is a
shared ceiling across session and transaction mode, while the Supavisor
FAQ and the terminology entry both say pool size is per user, database,
and mode combination. That text came from `master`, so the contradiction
is pre-existing. Link the FAQ as the authority rather than picking a
side.
- Drop the duplicate `pg_stat_ssl` query, which already exists in
`connection-management.mdx` and
`monitor-supavisor-postgres-connections.mdx`, both with column tables
this page lacked.
- Add the subsection to the navigation, which also adopts
`connecting-to-postgres/serverless-drivers`. That page existed on disk
and was referenced nowhere in the navigation constants.
- Delete the decision flowchart. It was the fourth restatement of the
decision table, and its logic was broken: `Persistent Backend` had two
unconditional edges into decision nodes that each had one unlabeled
output, so neither node decided anything.
- Fix every broken inbound anchor, and pin stable anchors on the
headings they target. This now includes six files in `apps/www` that no
earlier pass in this stack checked, most of which were already broken on
`master`.
- Repoint the Studio Connect sheet's Drizzle link at the Drizzle guide.
It pointed at a heading this page hasn't had for some time.
- Serverless drivers: state the guide's intent, give the three runtimes
parallel structure, and link the transaction mode prepared statements
constraint. That page never mentioned the constraint that most affects
serverless connections.
## Additional context
PR 2 of 2. Base is #49868, rebased on its review feedback commit.
Three of the 13 files are in `apps/studio`, so this runs the Studio unit
tests, build, and lint ratchet. They are link string changes only. The
ESLint warning count is unchanged at 1 on the touched files, so the
ratchet holds.
## Manual testing
1. Open [Connect to your
database](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/database/connecting-to-postgres)
on the deploy preview.
2. Check the table of contents. The top level reads: Which connection
method do you use?, Get your connection string, Quickstarts, Related.
The intro lists three paths.
3. Open
[Reports](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/monitoring-and-debugging/reports)
and follow "Implement connection pooling" under Disk IO. It lands on the
decision table.
4. Open [Serverless
drivers](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/database/connecting-to-postgres/serverless-drivers).
The intro links the transaction mode prepared statements constraint.
5. Check the sidebar. Connecting to your database expands to Connection
pooling and limits and Serverless drivers.
6. Open [Connection pooling and
limits](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/database/connecting-to-postgres/pooling-and-limits).
Pool size states the setting and links the Supavisor FAQ, with no worked
example.
7. Open [Tenant or user not
found](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/troubleshooting/tenant-or-user-not-found).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a dedicated guide covering connection pooling, limits,
configuration, and monitoring.
* Added troubleshooting guides for password authentication failures and
shared pooler tenant or user errors.
* Expanded connection guidance with method selection, endpoints, IP
versions, and serverless driver configuration.
* **Documentation**
* Reorganized database connection documentation and navigation.
* Updated related links throughout the documentation to current
connection and pooling guidance.
* Improved guidance for pooler modes, connection strings, and supported
deployment environments.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Stack
Draft stack extracted from `docs/monitoring`. Merge bottom-up. The
troubleshooting *catalog* rewrite (`content/troubleshooting` and the
Diagnosing UI) stays out of scope.
1. #49503 move inspect and advisors
2. #49501 split Studio logs from ClickHouse queries
3. #49500 treat reports as signal dashboards
4. #49502 add Observe the data hub
5. #49506 add agent setup components
6. #49504 add hire-an-agent templates
7. **#49505** restructure observability nav, overview, Detecting, and
flatten Observe the data ← **this PR**
## 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. Top layer in the observability stack.
## What is the current behavior?
The section is still titled Monitoring and Debugging, with a Debugging /
Monitoring split that does not match the new pages. The debugging guide
is still the master layer-isolation + symptom table. Observe the data is
split into “what data” vs “where to observe it,” which duplicates the
source pages.
## What is the new behavior?
- Section title is Observability
- Overview groups Observe the data, Detect and resolve, Hire an agent,
and Export
- **Observe the data is flattened by source.** Logs, Metrics API,
Database, Advisors, and Reports each list where to read that source.
There is no separate MCP/API/CLI/Studio nav group.
- **Observe vs Detecting:** Observe is the catalog (what exists, how to
access it). Detecting is how to *use* those sources to pick up a Health
/ Security / Performance / Usage signal. Named errors skip to
Diagnosing.
- Studio Logs sits under Logs. Reports sits beside the other sources.
- Troubleshooting stays in the global menu and also appears as
Diagnosing under Detect and resolve
## Additional context
This is the last PR in the stack. Together the seven PRs reconstruct the
`docs/monitoring` observability IA and guide content, without shipping
the troubleshooting catalog overhaul.
<!-- CURSOR_AGENT_PR_BODY_END -->
<div><a
href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a
href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>
Co-authored-by: Nik Richers <nik@validmind.ai>
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Stack
Draft stack extracted from `docs/monitoring`. Merge bottom-up.
Troubleshooting / debugging-guide rewrite is out of scope.
1. **#49503** move inspect and advisors ← **this PR**
2. #49501 split Studio logs from ClickHouse queries
3. #49500 treat reports as signal dashboards
4. #49502 add Observe the data hub
5. #49506 add agent setup components
6. #49504 add hire-an-agent templates
7. #49505 restructure observability nav and overview
## 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. First layer in the observability stack.
## What is the current behavior?
Inspect and advisors live under Database (`/guides/database/inspect`,
`/guides/database/database-advisors`). Observability readers have to
leave the monitoring section to find them.
## What is the new behavior?
- Moves inspect into `/guides/monitoring-and-debugging/inspect`
- Adds `/guides/monitoring-and-debugging/advisors` (replaces the
Database Advisors page)
- Adds redirects and updates Studio/docs links so old URLs keep working
- Adds both pages to the existing Monitoring nav so they are
discoverable before the later IA PR
## Additional context
Inspect and advisors pages render as standard MDX. Redirects cover
`/docs/guides/database/inspect`,
`/docs/guides/database/database-advisors`, and
`/docs/guides/database/database-linter`. Debugging-guide content is
unchanged except the inspect URL.
## Self-review
- No leftover `/guides/database/inspect` or
`/guides/database/database-advisors` links in docs guides or Studio
linter/AI surfaces (historical blog posts left as-is)
- Smoke test path updated to
`/docs/guides/monitoring-and-debugging/advisors`
<!-- CURSOR_AGENT_PR_BODY_END -->
<div><a
href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a
href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added a centralized Advisors guide for security and performance
checks.
- Updated database inspection guidance with live Postgres statistics,
cache hit-rate context, and query-analysis resources.
- **Documentation**
- Reorganized Advisors and database inspection content under Monitoring
and Debugging.
- Updated navigation, cross-references, in-product help links, and CLI
documentation links.
- Added permanent redirects from previous documentation URLs to preserve
access.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com>
Co-authored-by: Nik Richers <nik@validmind.ai>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
The Docs E2E link checker found broken links throughout docs, starting
with `phone-login.mdx` pointing to `/docs/guides/cli/config` (404).
Old links like `/docs/guides/cli/config` still work on the live site
because `supabase.com` has redirects set up for them, but these links
break on the docs preview site, which is what the E2E check tests
against. These issues look clean on the live site, and I didn't catch
them in my first pass because I was testing production instead of the
preview.
The E2E check only tests the ~20 pages a given PR happens to touch, so
fixing the pages it flagged kept exposing more of the same problem one
page at a time as each fix pulled in a new file. To stop chasing this
incrementally, I cross-referenced every `/docs/guides/*` and
`/docs/reference/*` redirect source in `apps/www/lib/redirects.js`
against actual usage across all of `apps/docs`, and verified each
candidate against the live preview.
## Solution
Rather than updating the Docs E2E link checker, this PR resolves the
links. **Why:** we own these docs, so keeping the links clean without
redirects is keeping the house maintained. See [Broken Window
Theory](https://blog.codinghorror.com/the-broken-window-theory/).
Updated every link still using an old path to point straight at the
current page instead of relying on a redirect. This covers old links
like:
- `/docs/guides/cli/config` →
`/docs/guides/local-development/cli/config`
- `/docs/guides/cli/getting-started` →
`/docs/guides/local-development/cli/getting-started`
- `/docs/guides/cli/local-development` →
`/docs/guides/local-development/database-migrations`
- `/docs/guides/cli/managing-environments` →
`/docs/guides/deployment/managing-environments`
- `/docs/guides/cli/seeding-your-database` →
`/docs/guides/local-development/seeding-your-database`
- bare `/docs/guides/cli` → `/docs/guides/local-development`
- `/docs/guides/platform/compute-add-ons` →
`/docs/guides/platform/compute-and-disk`
- `/docs/guides/platform/shared-responsibility-model` →
`/docs/guides/deployment/shared-responsibility-model`
- `/docs/guides/database` → `/docs/guides/database/overview`
- `/docs/reference/javascript`, `/docs/reference/dart`,
`/docs/reference/kotlin`, `/docs/reference/python`,
`/docs/reference/csharp` → their `/introduction` pages (the redirect's
own destination, `/start`, turned out to be dead even on production — a
separate bug in `redirects.js` I didn't touch here)
- and about 35 more of the same pattern, listed in the commit messages
Also fixed a handful of dead heading anchors found along the way (links
that resolve to the right page but point at a `#section` that got
renamed or moved), including the original `#bigquery` anchor and a few
in `connecting-to-postgres.mdx` where content moved to its own dedicated
page.
Left alone on purpose:
- `content/guides/cli.mdx` — this page has no route in the docs app at
all (no `app/guides/cli/` directory), so it 404s even in production
before the `www` redirect ever fires. Fixing its internal link wouldn't
change that; it needs an actual routing/content decision, not a link
fix.
- A few candidates that already resolve fine as-is (`pg_partman`, bare
`/docs/reference/api`, bare `/docs/reference/cli`) — confirmed via curl,
left untouched.
## Manual testing
1. Confirmed every new link target actually exists by checking the
destination file/page and matching heading anchors.
2. Cross-referenced every `/docs/guides/*` and `/docs/reference/*`
redirect source in `apps/www/lib/redirects.js` against real usage in
`apps/docs`, and curl-verified each old path (404) and new path (200)
against the live PR preview before fixing it.
3. Ran the Docs E2E link checker locally against changed pages.
4. Spot-checked the original broken link from CI
(`/docs/guides/cli/config`) to confirm it now points to a working page.
Follow-up to #48370, which merged the Compute and Disk settings page
into Infrastructure and made `/settings/compute-and-disk` a permanent
redirect.
**Changed:**
- Retargeted all 17 dashboard links from
`/dashboard/project/_/settings/compute-and-disk` to
`/dashboard/project/_/settings/infrastructure` (15 files across guides,
troubleshooting entries, and the `migration_warnings` partial)
- Updated link text that named the old page ("Compute and Disk settings"
→ "Infrastructure settings", plus one stale "Database Settings" label in
the compute-and-disk guide)
Links to the `/docs/guides/platform/compute-and-disk` docs guide are
untouched — that page still exists; only dashboard deep links changed.
> [!NOTE]
> Best merged after #48370 — until then the Infrastructure page doesn't
host the compute and disk config (the old URL keeps working either way
via the redirect).
## To test
- Spot-check a few changed pages on the preview (e.g.
`/guides/platform/database-size`,
`/guides/troubleshooting/high-cpu-usage`) and confirm the dashboard
links land on the Infrastructure settings page
- Confirm the compute-and-disk guide page itself still renders and its
docs-internal links are unchanged
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated migration and troubleshooting guidance to direct users to the
**Infrastructure** settings page, replacing outdated **Compute and
Disk** links.
- Refreshed platform/database/performance links for resizing, disk
throughput/IOPS, upgrade steps, and related troubleshooting to use the
updated **Infrastructure** routes and anchors.
- Adjusted “Using the CLI” to point to the current local development
getting-started page, and refined wording in the “Hit rate” section.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
Closes DOCS-1057
Contributes to DOCS-1052
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
We have hundreds of MDX lint warnings in our docs going against style
best practices.
## Solution
Remove and replace in context the following:
- PostgreSQL. There was only one. There was concern about exceptions,
but I found none.
- Just
- Quickly
- Actually
### What changed
Edits follow the [Google developer documentation style
guide](https://developers.google.com/style): concise, direct, active
voice. The flagged words were removed when the sentence still read well,
or replaced when meaning needed to be preserved.
### Common patterns
| Flagged word | Approach | Example |
|---|---|---|
| **just** (filler) | Removed | "you just installed" → "you installed" |
| **just** (limiting) | **only** | "just one row" → "only one row" |
| **just like** | **like** / **the same as** | "function just like
regular users" → "function like regular users" |
| **not just** | **not only** | "not just errors" → "not only errors" |
| **quickly** (performance) | **efficiently** or removed | "find rows
quickly" → "find rows efficiently" |
| **quickly** (time) | **soon** / **rapidly** / removed | "expires too
quickly" → "expires too soon" |
| **actually** (filler) | Removed | "actually execute" → "execute"; "is
actually the most common" → "is the most common" |
## Tophatting
1. See the diff.
2. See that content continues to make sense in context.
3. Locally, `cd apps/docs` and run `pnpm run lint:mdx`.
4. Search for "just," "actually," "quickly", and "PostgreSQL" and see
there are 0 warnings.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated wording across quickstarts, guides, and troubleshooting
articles for grammar, clarity, and consistent step-by-step phrasing.
* Clarified key concepts including Row Level Security policy evaluation
across Supabase products, deferred foreign key constraint behavior, and
when `EXPLAIN ANALYZE` executes queries (and related side effects).
* Refined several troubleshooting instructions and added guidance to cap
log payload size to reduce billed Logs Ingest volume.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Nik Richers <nrichers@gmail.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?
Resolves utilize lint warnings.
## What is the current behavior?
Utilize lint warnings are present.
## Tophatting
To see that this issue is resolved:
1. See the diff for content clarity.
2. Run `pnpm lint:mdx` to see no more remaining utilize errors.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
- Improved documentation clarity and consistency across platform guides,
including AI going-to-prod, custom claims/RLS RBAC, authentication
(anonymous, Web3, social login), and database connection/configuration.
- Refined technical wording throughout database, realtime, storage,
billing, performance, telemetry, and troubleshooting guides (for
example, standardizing phrasing like “use” vs “utilize”).
- Updated select guidance for clearer wording on database pre-warming
and clarified the scope of the Postgres logging note.
<!-- 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 (stale internal links / dead anchors).
## What is the current behavior?
The Metrics guide moved from `/docs/guides/platform/metrics` to
`/docs/guides/telemetry/metrics` and was split into sub-pages, but 15
internal links across the docs still use the old path:
1. **Redirect chain** — non-anchored links to
`/docs/guides/platform/metrics` only resolve via a two-hop permanent
redirect (`platform/metrics` → `monitoring-troubleshooting/metrics` →
`telemetry/metrics`, in `apps/www/lib/redirects.js`).
2. **Dead anchors** — `#accessing-the-metrics-endpoint` and
`#deploying-supabase-grafana` no longer exist on the restructured page,
so those links currently land at the top of the page instead of the
intended section.
## What is the new behavior?
- Non-anchored links now point directly at the canonical
`/docs/guides/telemetry/metrics` (relative links use
`../telemetry/metrics`), avoiding the redirect chain.
- `#accessing-the-metrics-endpoint` links →
`/docs/guides/telemetry/metrics` (the Metrics API endpoint access
content lives on that page).
- `#deploying-supabase-grafana` links →
`/docs/guides/telemetry/metrics/grafana-self-hosted`, the page that now
holds the Prometheus/Grafana installation instructions those links
referenced.
15 files changed, links only — no content changes.
## Additional context
Pure documentation link cleanup. Affected files include several guides
(`database/connection-management`, `database/inspect`,
`platform/performance`, `platform/read-replicas`) and troubleshooting
entries that reference the Metrics/Grafana setup guide.
* fix: rewrite relative URLs when syncing to GitHub discussion
Relative URLs back to supabse.com won't work in GitHub discussions, so
rewrite them back to absolute URLs starting with https://supabase.com
* fix: replace all supabase urls with relative urls
* chore: add linting for relative urls
* chore: bump linter version
* Prettier
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Miranda Limonczenko
