Re-does #50082 against the redesigned `connecting-to-postgres.mdx` (see
[Slack
discussion](https://supabase.slack.com/archives/C04JR9DBNQL/p1789991651381399?thread_ts=1788980733.712609&cid=C04JR9DBNQL)).
What changed vs. #50082:
- `connecting-to-postgres.mdx`: the pipelining caution now lives in the
new **Transaction mode limitations** section (the old "Pooler
transaction mode" prose it was in got redesigned), and is a short
redirect to the Postgres.js guide rather than a full explanation.
- `postgres-js.mdx`: keeps the full warning, the `{ prepare: false }`
workaround, and now explains *why* pipelining can't just be turned off
(`max_pipeline: 0` breaks `sql.begin()`, tracked in
porsager/postgres#1189), plus a "contact support" prompt for anyone
still stuck, and a note that Supavisor v2.10 will add native pipelining
support.
- Drops the standalone troubleshooting page from #50082 — the team
wasn't confident enough yet to officially point everyone at the
`postgres.js` patch, so support is the escalation path for now instead.
- Re-adds the `Rule003Spelling.toml` allow-list entry for "pipelining"
(not present on `master`).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified that query pipelining is unsupported in transaction mode and
may cause hangs or mismatched results.
* Documented Postgres.js pipeline behavior, recommended workarounds, and
planned native support in a future Supavisor release.
* Updated the Postgres.js connection example to disable prepared
statements for improved compatibility.
* Added a support contact link for assistance with transaction-mode
pipeline issues.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Preview
* pipelining mentioned in the Supavisor TX mode:
https://docs-git-docs-postgres-js-pipelining-warning-supabase.vercel.app/docs/guides/database/connecting-to-postgres#pooler-transaction-mode
* pipelining mentioned in more detail in TX mode limitations:
https://docs-git-docs-postgres-js-pipelining-warning-supabase.vercel.app/docs/guides/database/connecting-to-postgres#transaction-mode-limitations
* `postgres.js` pipelining warning with even more details:
https://docs-git-docs-postgres-js-pipelining-warning-supabase.vercel.app/docs/guides/database/postgres-js
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@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 troubleshooting entry + cross-links).
## What is the current behavior?
There's no public troubleshooting entry for a transient `password
authentication failed` (`28P01`) error through the Shared Pooler
(Supavisor) right after a database password rotation. The closest
existing entry only covers the IP-lockout circuit-breaker case (`FATAL:
Circuit breaker open`), and the generic FAQ answer for "FATAL: Password
authentication failed" in `connecting-to-postgres.mdx` reads as "your
credentials are simply wrong," with no mention that this is expected
right after a legitimate rotation.
## What is the new behavior?
- New entry:
`supavisor-error-password-authentication-failed-after-password-rotation.mdx`
— explains this is expected, by-design pooler-cache behavior (not a
bug), scopes it to SCRAM/password auth (not JIT), and walks through
confirming the new password via a direct connection before contacting
support.
- Cross-links added from the existing circuit-breaker entry, the "How do
I reset my Supabase database password?" entry, and the FAQ in
`connecting-to-postgres.mdx`.
## Additional context
Prettier check passes on all 4 touched files. `lint:mdx`
(`supa-mdx-lint`) could not be run locally due to a pre-existing,
unrelated native-module issue (`node-pty` missing its compiled binary
for this platform) — expected to run in CI.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
* Added troubleshooting guidance for `28P01` password authentication
failures after database password rotation.
* Clarified Shared Pooler credential-refresh behavior, affected
connection patterns, the built-in `postgres` role, and unaffected JIT
access-token connections.
* Added steps to verify credentials, retry connections, handle rate
limits, and avoid repeated rotations.
* Added guidance for updating credentials across live application
instances and cross-references between related troubleshooting guides.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Changed docs
* the new guide:
[docs-git-docs-supavisor-password-rotation-troub-026280-supab/…/supavisor-error-password-authentication-failed-after-password-rotation](https://docs-git-docs-supavisor-password-rotation-troub-026280-supabase.vercel.app/docs/guides/troubleshooting/supavisor-error-password-authentication-failed-after-password-rotation)
* mention the new guide + info on auth_error Circuit Breaker
[docs-git-docs-supavisor-password-rotation-troub-026280-supabase.vercel.app/docs/…/fatal-password-authentication-failed](https://docs-git-docs-supavisor-password-rotation-troub-026280-supabase.vercel.app/docs/guides/troubleshooting/fatal-password-authentication-failed)
* mention the new guide:
[docs-git-docs-supavisor-password-rotation-troub-026280-supabase.vercel.app/docs/…/how-do-i-reset-my-supabase-database-password…](https://docs-git-docs-supavisor-password-rotation-troub-026280-supabase.vercel.app/docs/guides/troubleshooting/how-do-i-reset-my-supabase-database-password-oTs5sB)
* mention of the new guide:
[docs-git-docs-supavisor-password-rotation-troub-026280-supabase.ver/…/supavisor-error-circuit-breaker-open-after-password-rotation…](https://docs-git-docs-supavisor-password-rotation-troub-026280-supabase.vercel.app/docs/guides/troubleshooting/supavisor-error-circuit-breaker-open-after-password-rotation-0fdb72)
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Nik Richers <nrichers@gmail.com>
Co-authored-by: felipe stival <14948182+v0idpwn@users.noreply.github.com>
Co-authored-by: Codesmith <codesmith-bot@users.noreply.github.com>
Closes FDBKIN-31335
Closes FDBKIN-13040
Closes FDBKIN-8653
Closes FDBKIN-19912
Closes DOCS-740
## 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. While we are revising this document, this PR gathers docs
feedback via AI magic and applies that feedback.
## What is the current behavior?
These findings stand on feedback intake rather than on the baseline.
Worth doing, and the eval won't show a score change for any of them.
- **Nothing explains the pooler host.** #49868 switched the strings to
`[POOLER-HOST]`, but the page never says why you can't compose the host,
and agents that recite `aws-0` get `Tenant or user not found`.
agent-skills#92.
- **The page gives the instruction to turn prepared statements off, but
not the flag.** It also links the GitHub discussion rather than the
troubleshooting entry that mirrors it. FDBKIN-8248, FDBKIN-7883.
- **SSL goes undiscussed.** Four of six eval runs set `ssl: 'require'`
unprompted.
- **The pooled username format only appears inside example strings**,
never as a rule. DOCS-740, FDBKIN-19912.
- **Third-party tools have no answer.** Session mode is the right one,
and the decision table had no row for a BI client or database GUI at
all. FDBKIN-8653.
- **Only one of transaction mode's three limitations is documented.**
FDBKIN-13040 names prepared statements, cursors, and session-level
settings. The page covered prepared statements.
## What is the new behavior?
- Tell the reader to copy the host, port, and username rather than
typing the placeholders, and explain the pooler cluster index next to
the reference table. The placeholders themselves changed in #49868.
- State the username rule: direct connections and the dedicated pooler
use `postgres`, shared pooler connections use `postgres.<project-ref>`.
- Add a per-driver prepared statements table for Postgres.js, Drizzle,
Prisma, asyncpg, and JDBC, and link [Disabling prepared
statements](https://supabase.com/docs/guides/troubleshooting/disabling-prepared-statements-qL8lEL)
for the rest. Add JDBC's `prepareThreshold=0` to that entry too, so the
two pages agree.
- Document SSL: `require` rather than the `prefer` default, which falls
back to plaintext.
- Link the `CONNECT_TIMEOUT` entry for stale sockets in frozen
serverless runtimes.
- Add a decision table row for a third-party tool, and point at
Quickstarts for named tools.
- Cover all three transaction mode limitations. Cursors work inside a
single transaction only, and session-level state is lost between
transactions: `set` and `reset`, session-level advisory locks, `listen`
and `notify`, and temporary tables. Renamed the section from "Prepared
statements", since it now covers the cause rather than one symptom.
- Promote Configure your client to an H2 and fold the SSL certificate
section into it. The table of contents only renders H2 and H3, so the
client settings were invisible as H4s.
## Manual testing
1. Open [Connect to your
database](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres)
on the deploy preview.
2. Read the Get your connection string lead-in. It tells you to copy the
host, port, and username rather than typing the placeholders.
3. Check the table of contents. Configure your client is an H2 with
Application-side pool size, Prepared statements, SSL, and Stale
connections under it.
4. Follow the prepared statements link. It lands on the in-docs
troubleshooting entry, not GitHub.
5. Open the [endpoint
reference](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres#endpoints-and-ip-versions).
The table shows `aws-[INDEX]-[REGION]`, and the prose below explains the
index and the username rule.
6. Read the decision table. It has a row for a third-party BI client or
database GUI, pointing at session mode.
7. Read [Transaction mode
limitations](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres#transaction-mode-limitations).
It covers prepared statements, cursors, and session-level state.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
- Expanded the Postgres connection guide with clearer client
configuration guidance, including pool sizing, SSL, stale connections,
and transaction mode limitations.
- Added recommendations for BI tools and database GUIs using the shared
pooler.
- Clarified connection strings, pooler hosts, usernames, ports, and IP
version behavior.
- Updated serverless driver guidance for transaction mode configuration.
- Added JDBC troubleshooting instructions for disabling prepared
statements with `prepareThreshold=0`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Closes DOCS-1312
## 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. One technical addition, isolated so the eval can attribute
a score change to it.
I re-ran the preview link on a scratch Eval branch and found that this
PR will resolve the Eval.
## What is the current behavior?
The eval baseline for `build-docs-004-postgres-connection` fails one
check, 3 of 6 runs: the application-side pool cap for a serverless
invocation.
- Two failing runs left `max` unset, which is 10 on the Postgres.js
default.
- One set `max: 5`.
The page says nothing about the application-side pool, so there was
nothing for an agent to read. Every other check passes 6/6, including
the connection string, port, username, and prepared statements. The mode
choice already transmits from the page.
Baseline notes are on
[DOCS-1312](https://linear.app/supabase/issue/DOCS-1312).
## What is the new behavior?
Add a **Configure your client** section to the procedure group. Pool
sizing is its only subject.
- Set the application-side pool to 1 connection per serverless
invocation, and raise it only on evidence.
- Name the trap concretely. Library defaults assume a persistent
backend, and 10 connections is 10 per warm instance, with the instance
count outside your control.
- One Postgres.js sample setting `max` and `prepare`, created at module
scope.
- Cite the [Supavisor
FAQ](https://supabase.com/docs/guides/troubleshooting/supavisor-faq-YyP5tI)
and [Prisma
troubleshooting](https://supabase.com/docs/guides/database/prisma/prisma-troubleshooting),
which already carries the equivalent `connection_limit` guidance for one
ORM. The gap is that the connection guide didn't carry it for readers
not using Prisma.
`prepare: false` is in the sample because a transaction mode sample is
wrong without it, and the page already instructs it. It isn't new
guidance. `ssl: 'require'` is, so it waits for #49928.
## Additional context
PR 3 of 4. Base is #49869.
This ships alone on purpose. It's the only change with baseline evidence
behind it, so a score change after this PR is attributable to one edit.
#49928 carries the rest of the eval feedback and is not expected to move
the score.
**Run the eval against this preview before #49928 lands.**
## Manual testing
1. Open [Connect to your
database](https://docs-git-docs-connecting-to-postgres-pool-size-supabase.vercel.app/docs/guides/database/connecting-to-postgres)
on the deploy preview.
2. Check the table of contents. "Configure your client" appears under
Get your connection string.
3. Read the section. It states 1 connection per invocation and names the
Postgres.js default of 10.
4. Read the sample. It sets `max: 1` and `prepare: false`, and says the
client is created once at module scope.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Added guidance for configuring application-side Postgres clients when
connecting through Supabase poolers.
- Documented recommended serverless settings, including creating the
client once, limiting connections per invocation, and disabling prepared
statements in transaction mode.
- Added a Postgres.js configuration example and links to relevant
Supavisor FAQ and Prisma troubleshooting resources.
<!-- 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. 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 -->
## 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. Style only.
## What is the current behavior?
The connecting to Postgres guide and its serverless drivers child page
have drifted from `WORD_LIST.md` and `CONTRIBUTING.md`. They also carry
six defects:
- The connection pooling diagram's alt text describes migrations on a
preview instance.
- The SSL screenshot's alt text and the sentence above it both promise
connection info. The image shows the SSL Configuration panel: a toggle
and a Download Certificate button.
- "Where can you see current connection usage?" lists three
Observability reports, then says the Roles page is not real-time. The
Roles page appears nowhere else in that answer.
- The serverless drivers manual configuration step has no main clause.
- "For example, If you set the pool size to 30".
- One of the two monitoring queries uses uppercase SQL keywords.
Three of the four connection strings use `postgres://` and two carry
literal project refs. The Connect dialog emits `postgresql://` with
placeholders.
The pooler host is templated as `aws-[region]`, which reads as
composable and isn't. Hosts are
`aws-<index>-<region>.pooler.supabase.com`, and the index is a pooler
cluster index, not part of the region. Both `aws-0-us-west-1` and
`aws-1-us-west-1` appear in this repo, so a reader can't derive it.
Studio doesn't compose the host either; it comes from the API.
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?
Word-level edit. No section is added, moved, or reordered, so the
restructure in the next PR of this stack lands as a readable set of
moved lines. Headings are untouched; PR 2 owns all heading changes.
- Fix the six defects above.
- Align the connection strings with what the Connect dialog emits:
`postgresql://` on all four, and `[PROJECT-REF]` in place of two literal
project refs.
- Use `[POOLER-HOST]` in the copyable pooler strings, the convention the
newer quickstarts already use. Keep the full `aws-[INDEX]-[REGION]`
shape in the summary table, where showing the shape is the point.
- Settle on one name per concept: shared and dedicated pooler in
sentence case, persistent backend, serverless and edge functions, and
paid plans.
- Drop bold used for plain emphasis, parenthetical asides, and claims
the page doesn't support: "ideal for", "ensures best performance and
latency", "satisfactory on their own".
- Format the two literal error strings as code, not quotes.
- Split the pool size answer into one paragraph per subject, and turn
the two pooler limits into a table.
- Serverless drivers: sentence case title, an intent sentence, and a
four-step procedure in place of the sentence fragment.
## Additional context
PR 1 of 2. Base is `master`.
Second commit applies review feedback. Third fixes the pooler host
placeholder, which belongs here rather than later in the stack: the
evidence is in the repo, not in the eval.
## Manual testing
1. Open [Connect to your
database](https://docs-git-docs-connecting-to-postgres-style-supabase.vercel.app/docs/guides/database/connecting-to-postgres)
on the deploy preview.
2. Read the four connection strings. All four use `postgresql://`, and
the two pooler strings use `[POOLER-HOST]` rather than a composable
region template.
3. Inspect the two images. The pooling diagram's alt text describes
pooling, and the SSL screenshot's describes the SSL Configuration panel.
4. Read "Where can you see current connection usage?". The paragraph
after the report list refers to the reports, not the Roles page.
5. Read "What is the difference between client connections and backend
connections?". The two limits are a table.
6. Open [Serverless
drivers](https://docs-git-docs-connecting-to-postgres-style-supabase.vercel.app/docs/guides/database/connecting-to-postgres/serverless-drivers).
Manual configuration is four numbered steps.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Clarified the PostgreSQL connection guide with updated connection
examples, pooling guidance, connection-mode tables, SSL information,
FAQs, and SQL formatting.
- Replaced sample connection values with generic placeholders in
documentation examples.
- Added clearer guidance that frontend Data API access requires
appropriate RLS policies.
- Updated explanations of client/backend connections and long-lived
PostgreSQL sessions.
- Updated serverless driver documentation with clearer setup guidance
for Vercel, Cloudflare, and Supabase Edge Functions.
- Reorganized manual configuration into numbered steps and standardized
connection string examples.
- Improved descriptions of runtime behavior and supported connection
methods.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What kind of change does this PR introduce?
Bug fix
## What is the current behavior?
Docs production builds can fail during prerender with:
`TypeError: Cannot read properties of undefined (reading 'children')`
Seen on `/guides/ai/going-to-prod` (and the same pattern exists on
several other guides).
Root cause: blank lines inside MDX JSX such as `<Image ...>` make the
MDX parser treat the element as closed early, which corrupts the AST.
Separately, `apps/docs/components/Image.tsx` forwarded accidental
`children` (and could overwrite `src`) onto `next/image`.
## What is the new behavior?
- Remove blank lines before the closing `/>` on the affected guide MDX
files so the JSX stays one element.
- Make the docs `Image` wrapper drop `children` and keep `src` from
props only, so a bad MDX tree is less likely to crash the build.
## Additional context
Split out of #48428 so that PR stays focused on Admonition/Alert
typography.
### To test
1. Check out this branch and run the docs app locally (`apps/docs`), or
wait for the Vercel docs preview on this PR.
2. Confirm these pages render without a prerender / `children` crash:
-
[/docs/guides/ai/going-to-prod](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/ai/going-to-prod)
-
[/docs/guides/ai/engineering-for-scale](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/ai/engineering-for-scale)
-
[/docs/guides/ai/choosing-compute-addon](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/ai/choosing-compute-addon)
-
[/docs/guides/ai/vector-indexes/hnsw-indexes](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/ai/vector-indexes/hnsw-indexes)
-
[/docs/guides/database/orioledb](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/database/orioledb)
-
[/docs/guides/database/connecting-to-postgres](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/database/connecting-to-postgres)
-
[/docs/guides/telemetry/reports](https://docs-git-fix-docs-image-mdx-blank-lines-supabase.vercel.app/docs/guides/telemetry/reports)
3. Spot-check that the guide images still show at the expected size (no
broken/missing images from the `Image` wrapper change).
4. Confirm Docs CI / Vercel docs build passes on this PR (this was the
failure mode on master-ish builds).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added zoomable behavior to the Disk Size chart, with optimized light
and dark theme images.
* **Bug Fixes**
* Improved image rendering in documentation pages by handling captions,
styling, and MDX content more reliably.
* Corrected image markup formatting across multiple guides to ensure
content parses and displays correctly.
<!-- 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
## 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.
## 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**
* Improved AI, database, storage, and platform guides with clearer
explanations and more detailed workflow steps.
* Added descriptive captions and accessible alt text for multiple
diagrams and benchmark charts.
* Expanded MFA, connection, replication, partitioning, and integration
docs with clearer decision points and setup/login flow guidance.
* Clarified database schema and seed-data examples to better explain how
tables and relationships fit together.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What is this PR?
This PR makes some images easier to understand by AI tools.
Some are removed as they served minimal purposes. Some are replaced with
mermaid versions instead, which are more understandable by AI tools.
Next steps after this PR are to continue migrating harder images as well
as improving the text around images in general.
## Testing
```
pnpm install
pnpm dev --filter=docs # or: cd apps/docs && pnpm dev
```
Then visit each converted page and verify:
Diagrams render as Mermaid (not a broken image / raw code fence) in both
light and dark mode:
- /docs/guides/auth/auth-mfa/phone, /totp
- /docs/guides/database/connecting-to-postgres
- /docs/guides/platform/read-replicas (inside the accordion)
- /docs/guides/storage/schema/design
- /docs/guides/local-development/seeding-your-database
- /docs/guides/auth/signing-keys (image gone, prose + table intact)
## 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>
* 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>
* Added new blog post and modified some docs for SEO
* ci: Autofix updates from GitHub workflow
* Fixed some linter errors
* Update apps/docs/content/guides/database/connecting-to-postgres.mdx
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* Update apps/docs/content/guides/database/connecting-to-postgres.mdx
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* Update all docs that make references to the database settings to find the connection strings.
Update all docs that references the database settings for the compute and disk page
* run prettier
* run pnpm format instead of prettier directly.
* first run through, fix grammar and reword awkward sentences
* Fix typos and remove unnecessary whitespace
* Apply suggestions from code review
Co-authored-by: Tyler <dshukertjr@gmail.com>
---------
Co-authored-by: Tyler <dshukertjr@gmail.com>
* adds blog post and stub
* Adds dates
* adds a description
* reworking the blog
* blog og
* fix description
* updates
* adds the form
* change date
---------
Co-authored-by: Francesco Sansalvadore <f.sansalvadore@gmail.com>
It seems (I am not an expert by any means) that beyond the 3 strategies described here, you can also connect to Supabase using the clients -- but that doesn't get mentioned here. For those just learning Supabase, like me, I feel like this would make the documentation clearer.
Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
