mirror of
https://github.com/supabase/supabase.git
synced 2026-09-22 13:37:53 +08:00
Miranda Limonczenko
976e7338bc
## 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 -->
57 lines
4.1 KiB
Plaintext
57 lines
4.1 KiB
Plaintext
---
|
|
title = "Diagnose HTTP API issues"
|
|
topics = [ "platform" ]
|
|
keywords = [ "API", "REST API", "GraphQL", "HTTP" ]
|
|
database_id = "e9fb853f-a37f-442a-b180-4aefd234a385"
|
|
|
|
[[errors]]
|
|
code = "5xx"
|
|
|
|
[[errors]]
|
|
message = "Connections refused"
|
|
---
|
|
|
|
Symptoms of HTTP API issues include:
|
|
|
|
- HTTP timeouts
|
|
- 5xx response codes
|
|
- High response times
|
|
|
|
## Under-provisioned resources
|
|
|
|
The most common class of issues that causes HTTP timeouts and 5xx response codes is the under-provisioning of resources for your project. This can cause your project to be unable to service the traffic it is receiving.
|
|
|
|
Each Supabase project is provisioned with [segregated compute resources](../platform/compute-and-disk). This allows the project to serve unlimited requests, as long as they can be handled using the resources that have been provisioned. Complex queries, or queries that process larger amounts of data, will require higher amounts of resources. As such, the amount of resources that can handle a high volume of basic queries (or queries involving small amounts of data), will likely be unable to handle a similar volume of complex queries.
|
|
|
|
You can view the resource utilization of your Supabase Project using the [reports in the Dashboard](/dashboard/project/_/observability/database).
|
|
|
|
Some common solutions for this issue are:
|
|
|
|
- [Upgrading](/dashboard/project/_/settings/infrastructure) to a [larger compute add-on](../platform/compute-and-disk) in order to serve higher volumes of traffic.
|
|
- [Optimizing the queries](../platform/performance#examining-query-performance) being executed.
|
|
- [Using fewer Postgres connections](../platform/performance#configuring-clients-to-use-fewer-connections) can reduce the amount of resources needed on the project.
|
|
- [Restarting](/dashboard/project/_/settings/general) the project. This only temporarily solves the issue by terminating any ongoing workloads that might be tying up your compute resources.
|
|
- All databases of the project, including [Read replicas](/docs/guides/platform/read-replicas), will be restarted.
|
|
- If you only want to restart a specific Read Replica, you can do so from the [Infrastructure Settings page](/dashboard/project/_/settings/infrastructure).
|
|
|
|
If your [Disk IO budget](../platform/compute-and-disk#disk) has been drained, you will need to either wait for it to be replenished the next day, or upgrade to a larger compute add-on to increase the budget available to your project.
|
|
|
|
## Unable to connect to your Supabase project
|
|
|
|
Symptom: You're unable to connect to your Postgres database directly, but can open the Project in the [Supabase Dashboard](/dashboard/project/_/).
|
|
|
|
### Too many open connections
|
|
|
|
Errors about too many open connections can be _temporarily_ resolved by [restarting the database](/dashboard/project/_/settings/general). However, this won't solve the underlying issue for a permanent solution.
|
|
|
|
- If you're receiving a `No more connections allowed (max_client_conn)` error:
|
|
- Configure your applications and services to [use fewer connections](../platform/performance#configuring-clients-to-use-fewer-connections).
|
|
- [Upgrade](/dashboard/project/_/settings/infrastructure) to a [larger compute add-on](../platform/compute-and-disk) to increase the number of available connections.
|
|
- If you're receiving a `sorry, too many clients already` or `remaining connection slots are reserved for non-replication superuser connections` error message in addition to the above suggestions, switch to using the [connection pooler](/docs/guides/database/connecting-to-postgres#choose-a-connection-method) instead.
|
|
|
|
### Connection refused
|
|
|
|
If you receive a `connection refused` error after a few initial failed connection attempts, your client has likely been temporarily blocked in order to protect the database from brute-force attacks. You can wait 30 minutes before trying again with the correct password, or you can [contact support](/dashboard/support/new) with your client's IP address to manually unblock you.
|
|
|
|
If you're also unable to open the project using the [Supabase Dashboard](/dashboard/project/_/), review the solutions for [under-provisioned projects](#under-provisioned-resources).
|