## 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 -->
Closes FE-3966
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
- The admonition uses both 'tip' and 'note', but the visual distinction
has long-ago collapsed.
- 'Note' is used far more frequently than 'tip'
- The two are very similar and it is confusing to know which one to use
when they are visually identical
## Solution
Collapse 'tip' and 'note' into one by removing all places where there is
'tip' and updating all references to 'tip' into 'note'.
**Note:** This PR also resolves new broken links flagged by the E2E docs
checker. It may move to another PR since E2Es keep erroring.
### Specific changes
See below for an AI-generated list of changes:
- **Type system** — removed `'tip'` from `AdmonitionType`, its
`TYPE_TO_VARIANT`/`TYPE_LABEL` entries, and the test case in
[`packages/ui-patterns/src/Admonition/](packages/ui-patterns/src/Admonition/)
- **Remark plugin** —
[remarkAdmonition.ts](apps/docs/lib/mdx/plugins/remarkAdmonition.ts) now
maps mkdocs `tip` → `note`
- **Lint allowlist** — `tip` dropped from `supa-mdx-lint.config.toml`
- **Content migration** — all 109 files with `type="tip"` (across
`apps/docs`, `apps/www`, `apps/studio`) converted to `type="note"`; zero
remaining hits confirmed by repo-wide grep
- **Style guide** — `CONTRIBUTING.md` and `contributing/content.mdx`
updated to describe 4 admonition types instead of 5
### Usage before implementation
See the usage table that points toward 'note' as being dominant across
all apps:
Here's the usage table:
| Location | `note` | `tip` |
|---|---|---|
| apps/docs | ~480 | ~143 |
| apps/studio | 34 | 6 |
| apps/www (blog) | 19 | 3 |
| packages/ui-patterns (tests) | 3 | 1 (parametrized) |
| design-system / ui-library / packages/ui / packages/common | 0–1 (test
fixture only) | 0 |
## Preview links
| App | Page | Search text (Ctrl+F) | Verify |
|---|---|---|---|
| docs |
[/docs/guides/ai-tools/byo-mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/byo-mcp)
| official MCP TypeScript SDK | callout's aria-label="Note" |
| docs |
[/docs/guides/ai-tools/mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/mcp)
| MCP server is available at | callout's aria-label="Note" |
| docs |
[/docs/guides/ai/python-clients](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai/python-clients)
| Click Connect at the top of any project page | callout's
aria-label="Note" |
| docs |
[/docs/guides/auth/audit-logs](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/auth/audit-logs)
| Disabling Postgres storage reduces your database storage costs |
callout's aria-label="Note" |
| docs |
[/docs/guides/database/tables](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/database/tables)
| access a custom schema through the Supabase Data API | callout's
aria-label="Note" |
| docs |
[/docs/guides/troubleshooting/edge-function-404-error-response](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/troubleshooting/edge-function-404-error-response)
| Always configure an appropriate time frame | callout's
aria-label="Note" (was single-quoted type='tip') |
| www | [blog:
cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code)
| Detecting config drift | callout's aria-label="Note" |
| www | [blog:
cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code)
| Setting Edge Function secrets | callout's aria-label="Note" |
| www | [blog:
nosql-mongodb-compatibility-with-ferretdb-and-flydotio](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/nosql-mongodb-compatibility-with-ferretdb-and-flydotio)
| If your network supports IPv6 connections | callout's
aria-label="Note" |
Note: the `www` rows use the `zone-www-dot-com` preview host, not the
`docs` one you gave — since blog pages are served from the www app, not
docs.
## Manual testing
1. Open preview links for affected pages.
2. Inspect. Open console.
3. Paste the following in and see there is no 'Tip' on the page:
```
document.querySelectorAll('[role="alert"]').forEach(el => console.log(el.getAttribute('aria-label'), el.textContent.slice(0,60)))
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Standardized informational callouts across docs and tutorials from
**“Tip”** to **“Note”**, updating multiple examples and guidance blocks.
* Updated a few related doc references/links and conditional “Next
steps” content.
* **UI Updates**
* Switched various in-app banners and notices to the **“Note”** style
variant.
* **Bug Fixes / Improvements**
* Removed support for the retired **“Tip”** callout type and aligned
docs linting, component behavior, and aria labeling to the remaining
admonition types.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
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>
Contributes to DOCS-1052
Contributes to DOCS-1057
## 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 linting warning for "let's" and adds an exception for product
name.
## Tophatting
1. Read the diff and see if changes make sense in context.
2. Run `pnpm lint:mdx`, search for "let's" and see no instances.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated instructional copy across multiple AI, authentication,
database, functions, realtime, storage, and troubleshooting guides to
improve clarity and consistency.
* Replaced conversational phrasing (for example, “Let’s…/Let’s see…”)
with direct imperatives, tightened example lead-ins, and adjusted a few
step explanations for readability.
* Refreshed some tutorial text and code-sample presentation in guides
(no behavioral changes).
* Added/adjusted minor MDX lint guidance in a couple of documents.
<!-- 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>
Contributes to DOCS-1052
## 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 MDX linting errors related to "simple" where it applies.
There was a couple cases that did not apply. For example, a product with
"Simple" in the name.
These changes are made in context, either by removing or using a more
descriptive synonym like "minimal" or "basic".
## Tophatting
1. Read each of the diffs.
2. See that the text still makes sense in context.
For extra due diligence, you can run `pnpm lint:mdx` locally and see the
'simple' errors that remain and whether they are worth addressing.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Summary by CodeRabbit
* **Documentation**
* Updated many guide, tutorial, and troubleshooting pages with clearer
“basic”/“minimal” wording across setup steps, local testing
instructions, security cautions, and RLS guidance.
* Refined headings, example descriptions, and inline comments for
consistency (including deployment, MCP, metrics API, and search/function
phrasing).
* Improved readability with small snippet formatting tweaks (whitespace
plus import/comment ordering) and added a self-hosting debugging note
for Envoy admin endpoints via a short-lived `curl` container.
<!-- 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: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
Co-authored-by: Nik Richers <nrichers@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?
Updates verbiage throughout docs to use postgres over postgresql.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated terminology throughout documentation, guides, and resources
for consistent product naming across all user-facing materials,
including page titles, descriptions, and reference documentation.
<!-- 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?
New Go landing page for the upcoming Bolt webinar. This is where we will
direct customers who want to learn more to go to request a meeting.
---------
Co-authored-by: Alan Daniel <stylesshjs@gmail.com>
* 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>
* Move advisory things to Advisors page, move schema visualizer to top of database section
* Tiny clean up
* Tiny clean up
---------
Co-authored-by: Joshen Lim <joshenlimek@gmail.com>
Miranda Limonczenko