The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: restructure the connecting to Postgres guide by information type (#49869)
Miranda Limonczenko976e7338bc16
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 7be23d9e1a3..6a97bf6aa02 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -1034,6 +1034,20 @@ export const database: NavMenuConstant = {{name: 'Connecting to your database',url: '/guides/database/connecting-to-postgres' as `/${string}`,+ items: [+ {+ name: 'Connecting to your database',+ url: '/guides/database/connecting-to-postgres' as `/${string}`,+ },+ {+ name: 'Connection pooling and limits',+ url: '/guides/database/connecting-to-postgres/pooling-and-limits' as `/${string}`,+ },+ {+ name: 'Serverless drivers',+ url: '/guides/database/connecting-to-postgres/serverless-drivers' as `/${string}`,+ },+ ],},{ name: 'Importing data', url: '/guides/database/import-data' },{ name: 'Securing your data', url: '/guides/database/secure-data' },diff --git a/apps/docs/content/guides/database/connecting-to-postgres.mdx b/apps/docs/content/guides/database/connecting-to-postgres.mdxindex 9b1a234e2c2..b06d0b05a35 100644--- a/apps/docs/content/guides/database/connecting-to-postgres.mdx+++ b/apps/docs/content/guides/database/connecting-to-postgres.mdx@@ -4,24 +4,26 @@ description: 'Connect to Postgres from your frontend, backend, or serverless envsubtitle: 'Supabase provides several ways to connect to your Postgres database, whether your code runs in the frontend, in a persistent backend, or in a serverless function.'----## How to connect to your Postgres databases+Learn how to pick a connection method and where to find the connection string for it.-How you connect to your database depends on where your code runs:+- [Which connection method do you use?](#choose-a-connection-method) picks a method based on where your code runs.+- [Get your connection string](#get-your-connection-string) shows where each string comes from.+- [Quickstarts](#quickstarts) connect a specific ORM or database GUI.-- For frontend applications, use the [Data API](#data-apis-and-client-libraries).-- For Postgres clients, use a connection string:- - Use the [direct connection string](#direct-connection) for single sessions and Postgres native commands. This covers database GUIs, client applications such as [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html), [migrations](/docs/guides/deployment/database-migrations), [backup and restore](/docs/guides/platform/migrating-within-supabase/backup-restore), and [replication](/docs/guides/database/postgres/setup-replication-external). The direct endpoint is on IPv6, or on IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).- - Use [pooler session mode](#pooler-session-mode) for application traffic from persistent backends on IPv4-only networks.- - Use [pooler transaction mode](#pooler-transaction-mode) for application traffic from short-lived clients, such as serverless and edge functions.+For how pooling works and the limits that apply to your connections, see [Connection pooling and limits](/docs/guides/database/connecting-to-postgres/pooling-and-limits).-The following table summarizes each mode, its host and port, the IP version it supports on each plan, and what it's best used for:+## Which connection method do you use? [#choose-a-connection-method]-| Mode | Host:Port | Free | Paid | Paid + IPv4 add-on | Best for |-| ---------------------------------- | ----------------------------------------------- | ---- | ---- | ------------------ | ------------------------------------------ |-| Direct connection | `db.[PROJECT-REF].supabase.co:5432` | IPv6 | IPv6 | IPv4 | Migrations, `pg_dump`, persistent backends |-| Shared pooler, session mode | `aws-[INDEX]-[REGION].pooler.supabase.com:5432` | IPv4 | IPv4 | IPv4 | Persistent backends on IPv4-only networks |-| Shared pooler, transaction mode | `aws-[INDEX]-[REGION].pooler.supabase.com:6543` | IPv4 | IPv4 | IPv4 | Serverless and edge functions |-| Dedicated pooler, transaction mode | `db.[PROJECT-REF].supabase.co:6543` | - | IPv6 | IPv4 | High-performance app traffic on paid plans |+How you connect to your database depends on where your code runs. Find your case in the table, then get the matching connection string.++| Where your code runs | Use | Why |+| --------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- |+| A frontend application | [Data API](#data-apis-and-client-libraries) | Works over REST or GraphQL, so you don't need a Postgres client. Requires Row Level Security. |+| A serverless or edge function | [Shared pooler, transaction mode](#pooler-transaction-mode) | These environments open many short-lived connections. |+| A persistent backend on IPv6, or with the IPv4 add-on | [Direct connection](#direct-connection) | No pooler in the path. |+| A persistent backend on an IPv4-only network | [Shared pooler, session mode](#pooler-session-mode) | The shared pooler is IPv4-only on every plan. |+| A high-performance application on a paid plan | [Dedicated pooler](#dedicated-pooler) | Runs on the same machine as your database, so lower latency than the shared pooler. |+| Migrations, `pg_dump`, backup and restore, or replication | [Direct connection](#direct-connection) | These are single sessions and Postgres native commands. |<Admonition type="caution">@@ -29,88 +31,48 @@ The IPv4 add-on is not dual-stack: enabling it swaps the project's IPv6 (AAAA) D</Admonition>-## Quickstarts--<div className="grid grid-cols-[repeat(auto-fit,minmax(150px,1fr))] gap-6 not-prose">- <NavData data="ormQuickstarts">- {(data) =>- data.items?.map((quickstart) => (- <Link key={quickstart.url} href={quickstart.url} passHref>- <GlassPanel- key={quickstart.name}- title={quickstart.name}- className="[&>div]:p-2 flex justify-center [&_p]:text-foreground-light"- />- </Link>- ))- }- </NavData>- <NavData data="guiQuickstarts">- {(data) =>- data.items?.map((quickstart) => (- <Link key={quickstart.url} href={quickstart.url} passHref>- <GlassPanel- key={quickstart.name}- title={quickstart.name}- className="[&>div]:p-2 flex justify-center [&_p]:text-foreground-light"- />- </Link>- ))- }- </NavData>-</div>+For the host, port, and IP version of each mode, see [Endpoints and IP versions](#endpoints-and-ip-versions).-## Data APIs and client libraries+## Get your connection string [#get-your-connection-string]-The Data APIs let you interact with your database using REST or GraphQL requests. You can use these APIs to fetch and insert data from the frontend, as long as your tables have [Row Level Security](/docs/guides/database/postgres/row-level-security) (RLS) enabled and policies that allow the access. RLS with no policies denies every request.+Connecting from a frontend application? You don't need a connection string. Skip to [Data APIs and client libraries](#data-apis-and-client-libraries), which uses your project URL and an API key instead.-- [REST](/docs/guides/api)-- [GraphQL](/docs/guides/graphql/api)+For every Postgres connection mode, the string comes from the same place:-For convenience, you can also use the [Supabase client libraries](/docs/reference), which wrap the Data APIs with a developer-friendly interface and handle authentication for you:+1. Open your project in the [Supabase Dashboard](/dashboard/project/_).+2. Click **Connect** at the top of the page.+3. Choose the connection method you picked above.+4. Copy the string and replace `[YOUR-PASSWORD]` with your database password. [Percent-encode](https://en.wikipedia.org/wiki/Percent-encoding) any reserved characters it contains, such as `&`, `#`, `?`, or a space.-- [JavaScript](/docs/reference/javascript/introduction)-- [Flutter](/docs/reference/dart/introduction)-- [Swift](/docs/reference/swift)-- [Python](/docs/reference/python/introduction)-- [C#](/docs/reference/csharp/introduction)-- [Kotlin](/docs/reference/kotlin/introduction)+The sections below show what each string looks like and when to use it.-## Direct connection+### Direct connection [#direct-connection]The direct connection string connects directly to your Postgres instance. Use it for persistent backends, such as virtual machines (VMs) and long-running containers. Examples include AWS EC2 machines, Fly.io VMs, and DigitalOcean Droplets.<Admonition type="caution">-Direct connections are on IPv6, or on IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address). If your network is IPv4-only and you don't have the add-on, use [pooler session mode](#pooler-session-mode) instead.+Direct connections are on IPv6, or on IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address). If your network is IPv4-only and you don't have the add-on, use [session mode](#pooler-session-mode) instead.</Admonition>-The connection string looks like this:-```txtpostgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres```-Get your project's direct connection string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true).--## Poolers--Supabase offers two poolers. The shared pooler, [Supavisor](https://github.com/supabase/supavisor), is multi-tenant, available on every project, and IPv4-only. The dedicated pooler, [PgBouncer](https://www.pgbouncer.org/), is available on paid plans and runs alongside your Postgres instance. Like the direct connection, it is on IPv6, or on IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).+Get this string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true).-### Pooler session mode+### Shared pooler, session mode [#pooler-session-mode]The session mode connection string connects to your Postgres instance through the shared pooler. Use it as an alternative to a direct connection when you connect from an IPv4-only network.-The connection string looks like this:-```txtpostgresql://postgres.[PROJECT-REF]:[YOUR-PASSWORD]@[POOLER-HOST]:5432/postgres```-Get your project's session mode connection string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=session) and choosing **Session pooler**.+Get this string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=session) and choosing **Session pooler**.-### Pooler transaction mode+### Shared pooler, transaction mode [#pooler-transaction-mode]The transaction mode connection string connects to your Postgres instance through the shared pooler in transaction-pooling mode. Use it for serverless and edge functions, which open many short-lived connections.@@ -120,59 +82,39 @@ Transaction mode does not support [prepared statements](https://postgresql.org/d</Admonition>-The connection string looks like this:-```txtpostgresql://postgres.[PROJECT-REF]:[YOUR-PASSWORD]@[POOLER-HOST]:6543/postgres```-Get your project's transaction mode connection string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=transaction) and choosing **Transaction pooler**.+Get this string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=transaction) and choosing **Transaction pooler**.-## Dedicated pooler+### Dedicated pooler [#dedicated-pooler]-On paid plans, Supabase provisions a dedicated pooler, [PgBouncer](https://www.pgbouncer.org/), that runs alongside your Postgres database. The dedicated pooler runs in transaction mode only. For session mode, use the [shared pooler](#pooler-session-mode). It is reachable over IPv6, or over IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).--The connection string looks like this:+On paid plans, Supabase provisions a dedicated pooler that runs alongside your Postgres database. The dedicated pooler runs in transaction mode only. For session mode, use the [shared pooler](#pooler-session-mode). It is reachable over IPv6, or over IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).```txtpostgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:6543/postgres```-The dedicated pooler runs on the same machine as your database, so it connects with lower latency than the shared pooler. It also uses more of your project's compute resources. If your network supports IPv6, or you have the IPv4 add-on, use the dedicated pooler instead of the shared pooler.--Get your project's dedicated pooler connection string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=transaction).--## More about connection pooling--Connection pooling improves database performance by reusing existing connections between queries. This reduces the overhead of establishing connections and improves scalability.--You can use an application-side pooler or a server-side pooler, depending on whether your backend is persistent or serverless. Supabase provides a server-side pooler called Supavisor.--### Application-side poolers+Get this string from the Supabase Dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=transaction).-Application-side poolers are built into connection libraries and API servers, such as Prisma, SQLAlchemy, and PostgREST. They maintain several active connections with Postgres or a server-side pooler, which reduces the overhead of establishing connections between queries. When you deploy to a persistent backend, such as a long-running container or VM, an application-side pooler is enough on its own.+### Data APIs and client libraries [#data-apis-and-client-libraries]-### Server-side poolers--A Postgres connection is a long-lived session. Once established, it stays open until the client disconnects, or until the server or the network closes it. A server might make a single 10 ms query but hold its database connection for seconds or longer.+The Data APIs let you interact with your database using REST or GraphQL requests. You can use these APIs to fetch and insert data from the frontend, as long as your tables have [Row Level Security](/docs/guides/database/postgres/row-level-security) (RLS) enabled and policies that allow the access. RLS with no policies denies every request.-Server-side poolers, such as Supabase's [Supavisor](https://github.com/supabase/supavisor) in transaction mode, sit between clients and the database. Think of them as load balancers for Postgres connections.+- [REST](/docs/guides/api)+- [GraphQL](/docs/guides/graphql/api)-<Image- alt="A direct connection reserves one database connection per client. A connection pooler shares a smaller set of database connections across many clients."- src={{- dark: '/docs/img/guides/database/connecting-to-postgres/how-connection-pooling-works.png',- light:- '/docs/img/guides/database/connecting-to-postgres/how-connection-pooling-works--light.png',- }}- width={1851}- height={907}- caption="Connecting to the database directly compared with using a connection pooler"-/>+For convenience, you can also use the [Supabase client libraries](/docs/reference), which wrap the Data APIs with a developer-friendly interface and handle authentication for you:-Server-side poolers maintain hot connections with the database and share them with clients only when needed, which maximizes the number of queries a single connection can serve. Use them for queries from auto-scaling systems, such as edge and serverless functions.+- [JavaScript](/docs/reference/javascript/introduction)+- [Flutter](/docs/reference/dart/introduction)+- [Swift](/docs/reference/swift)+- [Python](/docs/reference/python/introduction)+- [C#](/docs/reference/csharp/introduction)+- [Kotlin](/docs/reference/kotlin/introduction)-## Connecting with SSL+### Connect with SSL [#connecting-with-ssl]Connect to your database using SSL wherever possible, to prevent snooping and man-in-the-middle attacks.@@ -180,162 +122,65 @@ Download your server root certificate from [Database settings](/dashboard/projec-## Resources--- [Connection management](/docs/guides/database/connection-management)-- [Connecting with psql](/docs/guides/database/psql)-- [Importing data into Supabase](/docs/guides/database/import-data)--## Troubleshooting and Postgres connection string FAQs--The following answers cover common connection problems and questions.--### What is a `connection refused` error?+### Endpoints and IP versions [#endpoints-and-ip-versions]-A `connection refused` error means your database isn't reachable. Check that your Supabase project is running, confirm your database's connection string, check your firewall settings, and validate your network permissions.+Each mode has its own host, port, and IP version support. IP version support depends on your plan and on whether the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).-### What is the `FATAL: Password authentication failed` error?+| Mode | Host:Port | Free | Paid | Paid + IPv4 add-on |+| ---------------------------------- | ----------------------------------------------- | ---- | ---- | ------------------ |+| Direct connection | `db.[PROJECT-REF].supabase.co:5432` | IPv6 | IPv6 | IPv4 |+| Shared pooler, session mode | `aws-[INDEX]-[REGION].pooler.supabase.com:5432` | IPv4 | IPv4 | IPv4 |+| Shared pooler, transaction mode | `aws-[INDEX]-[REGION].pooler.supabase.com:6543` | IPv4 | IPv4 | IPv4 |+| Dedicated pooler, transaction mode | `db.[PROJECT-REF].supabase.co:6543` | - | IPv6 | IPv4 |-This error means your credentials are incorrect. Check your username and password in the Supabase Dashboard. If the problem persists, reset your database password in the project settings.+The port routes the connection to the right pooler and mode. Port `5432` reaches Postgres for a direct connection and Supavisor for session mode. Port `6543` reaches PgBouncer for the dedicated pooler and Supavisor for shared transaction mode.-### How do you connect using IPv4?+To connect over IPv4, you have two options. The shared pooler is IPv4-only on every plan, in both session and transaction mode. Alternatively, add the [IPv4 add-on](/docs/guides/platform/ipv4-address) to your project, which makes the direct connection and the dedicated pooler reachable over IPv4 instead of IPv6.-You have two options. The shared pooler is IPv4-only on every plan, in both session and transaction mode. Alternatively, add the [IPv4 add-on](/docs/guides/platform/ipv4-address) to your project, which makes the direct connection and the dedicated pooler reachable over IPv4 instead of IPv6.+## Quickstarts [#quickstarts]-### Where is the Postgres connection string in Supabase?+Each quickstart connects one ORM or database GUI to your Supabase database.-Your connection string is in the Supabase Dashboard. Click [Connect](/dashboard/project/_?showConnect=true) at the top of the page.--### Can you use Supavisor and PgBouncer together?--You can use both, but don't do it unless you're trying to increase the total number of concurrent client connections. In most cases, choose either PgBouncer or Supavisor for pooled or transaction-based traffic. Direct connections remain the best choice for long-lived sessions, and shared pooler session mode is the alternative when those sessions need IPv4. Running both poolers at once increases the risk of hitting your database's maximum connection limit on smaller compute sizes.--### How does the default pool size work?--Supavisor and PgBouncer work independently, but both reference the same pool size setting. You can adjust it in [Database settings](/dashboard/project/_/database/settings) in the Supabase Dashboard.--Say you set the pool size to 30. Supavisor can then open up to 30 server-side connections to Postgres. Those 30 are shared between the session mode port, `5432`, and the transaction mode port, `6543`. Each mode can use all 30 on its own, or the two can split them, but the total across both modes cannot exceed 30.--PgBouncer can open up to 30 connections under the same limit. If both poolers reach their limits at the same time, you could have as many as 60 backend connections hitting your database, in addition to any direct connections.--### What is the difference between client connections and backend connections?--There are two limits to understand when working with poolers.--| Limit | What it counts | What sets it |-| ------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |-| Client connections | How many clients can connect to a pooler at the same time | Your [compute size's max pooler clients limit](/docs/guides/platform/compute-and-disk#postgres-replication-slots-wal-senders-and-connections) |-| Backend connections | How many active connections a pooler opens to Postgres | The pool size for that pooler |--Both limits apply independently to Supavisor and PgBouncer.--```txt-Total backend load on Postgres =- Direct connections +- Supavisor backend connections (≤ supavisor_pool_size) +- PgBouncer backend connections (≤ pgbouncer_pool_size)-≤ Postgres max connections for your compute instance-```--### What is the max pooler clients limit?--The max pooler clients limit for your compute size applies separately to Supavisor and PgBouncer. One pooler reaching its client limit doesn't affect the other. When a pooler reaches this limit, it stops accepting new client connections until existing ones close. The other pooler is unaffected. You can check your connection limits in the [compute and disk documentation](/docs/guides/platform/compute-and-disk#postgres-replication-slots-wal-senders-and-connections).--### Where can you see current connection usage?--You can track connection usage in the [Observability](/dashboard/project/_/observability/database) section of the Supabase Dashboard. There are three reports:--- **Database Connections:** total active connections by role, including direct and pooled connections.-- **Dedicated Pooler Client Connections:** active client connections to PgBouncer.-- **Shared Pooler (Supavisor) Client Connections:** active client connections to Supavisor.--These reports are not real-time. They show the connection count from the last refresh. For up-to-the-second data, set up Grafana or query `pg_stat_activity` directly in the SQL Editor. The following queries report on current connections.--```sql--- Count connections by application and user name-select- count(usename),- count(application_name),- application_name,- usename-from- pg_stat_ssl- join pg_stat_activity on pg_stat_ssl.pid = pg_stat_activity.pid-group by usename, application_name;-```--```sql--- View all connections-select- pg_stat_activity.pid,- ssl as ssl_connection,- datname as database,- usename as connected_role,- application_name,- client_addr,- query,- query_start,- state,- backend_start-from pg_stat_ssl-join pg_stat_activity on pg_stat_ssl.pid = pg_stat_activity.pid;-```--### Why are there active connections when the app is idle?--Even when your application isn't making queries, some Supabase services keep persistent connections to your database. Storage, PostgREST, and the health checker all maintain long-lived connections. You usually see a small baseline of active connections from these services.--### Why do connection strings have different ports?--Different modes use different ports:--- Direct connection: `5432`, for Postgres on your project instance-- Dedicated pooler, transaction mode: `6543`, for PgBouncer on your project instance-- Shared pooler, transaction mode: `6543`, for Supavisor-- Shared pooler, session mode: `5432`, for Supavisor--The port routes the connection to the right pooler and mode.--### Does connection pooling affect latency?--The dedicated pooler runs on the same machine as your database, so it connects with lower latency than the shared pooler, which runs on a separate server. Direct connections have no pooler overhead, but they require IPv6 unless you have the IPv4 add-on.--### How to choose the right connection method?--**Direct connection:**--- Best for persistent backends-- Use for migrations, `pg_dump`, and backup and management tools-- Reachable over IPv6, or over IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address)--**Shared pooler, Supavisor:**--- Best for connections from IPv4 networks. It is IPv4-only on every plan- - Session mode for a persistent backend on an IPv4 network- - Transaction mode for serverless functions and other short-lived tasks-- Use for application runtime traffic, such as queries and writes--**Dedicated pooler, PgBouncer, on paid plans:**+<div className="grid grid-cols-[repeat(auto-fit,minmax(150px,1fr))] gap-6 not-prose">+ <NavData data="ormQuickstarts">+ {(data) =>+ data.items?.map((quickstart) => (+ <Link key={quickstart.url} href={quickstart.url} passHref>+ <GlassPanel+ key={quickstart.name}+ title={quickstart.name}+ className="[&>div]:p-2 flex justify-center [&_p]:text-foreground-light"+ />+ </Link>+ ))+ }+ </NavData>+ <NavData data="guiQuickstarts">+ {(data) =>+ data.items?.map((quickstart) => (+ <Link key={quickstart.url} href={quickstart.url} passHref>+ <GlassPanel+ key={quickstart.name}+ title={quickstart.name}+ className="[&>div]:p-2 flex justify-center [&_p]:text-foreground-light"+ />+ </Link>+ ))+ }+ </NavData>+</div>-- Best for high-performance apps that need dedicated resources-- Use for application runtime traffic, such as queries and writes-- Transaction mode only. Use the shared pooler if you need session mode-- Reachable over IPv6, or over IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address)+## Related-See the [table of connection modes](#how-to-connect-to-your-postgres-databases) at the top of this page for a quick reference, or follow the decision flow in the diagram below to choose the right option for your environment.+- [Connection pooling and limits](/docs/guides/database/connecting-to-postgres/pooling-and-limits) explains poolers, pool size, and connection limits.+- [Serverless drivers](/docs/guides/database/connecting-to-postgres/serverless-drivers) covers Vercel, Cloudflare Workers, and Supabase Edge Functions.+- [Managing connections](/docs/guides/database/connection-management) covers monitoring and diagnosing stuck queries.+- [Connecting with psql](/docs/guides/database/psql)+- [Importing data into Supabase](/docs/guides/database/import-data)-```mermaid-flowchart TD- A[Where are you connecting from?] --> B[Persistent Backend]- A --> C[Serverless / Edge]- B --> D{IPv6 Supported?<br/>IPv4 Add-on?}- B --> E{IPv4 Needed?}- C --> H{IPv6 Supported?<br/>IPv4 Add-on?}- C --> I{IPv4 Needed?}- D --> F[Use Direct Connection]- E --> G[Use Supavisor Session Mode]- H --> J[Use Dedicated Pooler PgBouncer Pro]- I --> K[Use Supavisor Transaction Mode]-```+### Troubleshooting-The decision depends on where your code runs. For a persistent backend, use a direct connection if you can reach the database over IPv6 or have the IPv4 add-on. Otherwise, use the shared pooler in session mode. For serverless and edge environments, use the dedicated pooler on paid plans when IPv6 or the IPv4 add-on is available, or the shared pooler in transaction mode when you need IPv4.+- [Tenant or user not found](/docs/guides/troubleshooting/tenant-or-user-not-found), when the pooler can't match your host and username to a project.+- [FATAL: Password authentication failed](/docs/guides/troubleshooting/fatal-password-authentication-failed)+- [Connection refused](/docs/guides/troubleshooting/error-connection-refused-when-trying-to-connect-to-supabase-database-hwG0Dr), which is usually an IP ban rather than an outage.+- [Too many connections](/docs/guides/troubleshooting/too-many-connections-for-database-postgres)diff --git a/apps/docs/content/guides/database/connecting-to-postgres/pooling-and-limits.mdx b/apps/docs/content/guides/database/connecting-to-postgres/pooling-and-limits.mdxnew file mode 100644index 00000000000..2bb4fe24b57--- /dev/null+++ b/apps/docs/content/guides/database/connecting-to-postgres/pooling-and-limits.mdx@@ -0,0 +1,108 @@+---+title: 'Connection pooling and limits'+description: 'How connection pooling works, and the limits that apply to your connections'+subtitle: 'How Supabase pools database connections, and the limits that apply to them.'+---++Learn how to choose between connection modes, size a pool, and work out why you're running out of connections. To get connected, see [Connect to your database](/docs/guides/database/connecting-to-postgres).++## How connection pooling works [#how-connection-pooling-works]++Connection pooling improves database performance by reusing existing connections between queries. This reduces the overhead of establishing connections and improves scalability.++A Postgres connection is a long-lived session. Once established, it stays open until the client disconnects, or until the server or the network closes it. A server might make a single 10 ms query but hold its database connection for seconds or longer.++A pooler sits between clients and the database and shares a small set of database connections across many clients, so a connection isn't tied up while a client sits idle.++<Image+ alt="A direct connection reserves one database connection per client. A connection pooler shares a smaller set of database connections across many clients."+ src={{+ dark: '/docs/img/guides/database/connecting-to-postgres/how-connection-pooling-works.png',+ light:+ '/docs/img/guides/database/connecting-to-postgres/how-connection-pooling-works--light.png',+ }}+ width={1851}+ height={907}+ caption="Connecting to the database directly compared with using a connection pooler"+/>++### Application-side and server-side poolers [#application-side-poolers]++There are two kinds, and they work together.++**Application-side poolers** are built into connection libraries and API servers, such as Prisma, SQLAlchemy, and Postgres.js. They keep a few connections open and reuse them. On a persistent backend, such as a long-running container or VM, an application-side pooler is enough on its own.++**Server-side poolers**, such as Supavisor in transaction mode, run in front of the database and serve many clients. Use one when connections come from serverless or edge functions, or from anything that scales horizontally. These environments open many short-lived connections, which is the case an application-side pooler can't cover.++For more on when each is needed and how to size them, see the [Supavisor FAQ](/docs/guides/troubleshooting/supavisor-faq-YyP5tI).++### Shared and dedicated poolers [#shared-pooler]++Supabase offers two poolers. The shared pooler, [Supavisor](https://github.com/supabase/supavisor), is multi-tenant, available on every project, and IPv4-only. The dedicated pooler, [PgBouncer](https://www.pgbouncer.org/), is available on paid plans and runs alongside your Postgres instance. Like the direct connection, it is on IPv6, or on IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).++The dedicated pooler runs on the same machine as your database, so it connects with lower latency than the shared pooler, which runs on a separate server. It also uses more of your project's compute resources. If your network supports IPv6, or you have the IPv4 add-on, use the dedicated pooler instead of the shared pooler. Direct connections have no pooler overhead, but they require IPv6 unless you have the IPv4 add-on.++In most cases, choose either PgBouncer or Supavisor for pooled or transaction-based traffic. Direct connections remain the best choice for long-lived sessions, and shared pooler session mode is the alternative when those sessions need IPv4. Run both poolers at once only when you need to raise the total number of concurrent client connections, and expect a higher risk of hitting your database's maximum connection limit on smaller compute sizes.++## Connection limits++### Pool size [#pooler-pool-size]++Pool size sets how many connections a pooler is allowed to open to Postgres. You can adjust it in [Database settings](/dashboard/project/_/database/settings) in the Supabase Dashboard.++Supavisor and PgBouncer read the same setting but apply it independently, so raising it raises the ceiling for both.++For what the setting counts, and how it interacts with the user, database, and mode combinations connecting to your project, see [the Supavisor FAQ](/docs/guides/troubleshooting/supavisor-faq-YyP5tI).++### Client connections and backend connections [#client-connections-and-backend-connections]++There are two limits to understand when working with poolers.++| Limit | What it counts | What sets it |+| ------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |+| Client connections | How many clients can connect to a pooler at the same time | Your [compute size's max pooler clients limit](/docs/guides/platform/compute-and-disk#postgres-replication-slots-wal-senders-and-connections) |+| Backend connections | How many active connections a pooler opens to Postgres | The pool size for that pooler |++Both limits apply independently to Supavisor and PgBouncer. One pooler reaching its client limit doesn't affect the other. When a pooler reaches this limit, it stops accepting new client connections until existing ones close.++```txt+Direct connections ++ Supavisor backend connections ++ PgBouncer backend connections+< Postgres max connections for your compute instance+```++Stay below the maximum rather than at it. Supabase services hold their own connections, including Auth, Storage, PostgREST, and the health checker, and those come out of the same total. [Managing connections](/docs/guides/database/connection-management) covers how much headroom to leave.++For the connection counts that come with each compute size, see [compute and disk](/docs/guides/platform/compute-and-disk#postgres-replication-slots-wal-senders-and-connections). For the terminology, see [Supavisor and connection terminology explained](/docs/guides/troubleshooting/supavisor-and-connection-terminology-explained-9pr_ZO).++### Monitor connection usage [#monitor-connection-usage]++Track connection usage in the [Observability](/dashboard/project/_/observability/database) section of the Supabase Dashboard. There are three reports:++- **Database Connections:** total active connections by role, including direct and pooled connections.+- **Dedicated Pooler Client Connections:** active client connections to PgBouncer.+- **Shared Pooler (Supavisor) Client Connections:** active client connections to Supavisor.++These reports are not real-time. They show the connection count from the last refresh. For up-to-the-second data, query `pg_stat_activity` in the SQL Editor:++```sql+-- Count connections by application and user name+select+ count(usename),+ count(application_name),+ application_name,+ usename+from+ pg_stat_ssl+ join pg_stat_activity on pg_stat_ssl.pid = pg_stat_activity.pid+group by usename, application_name;+```++To list every connection with its state and query, and to read which Supabase service each role belongs to, see [Managing connections](/docs/guides/database/connection-management#observing-live-connections).++## Related++- [Connect to your database](/docs/guides/database/connecting-to-postgres)+- [Managing connections](/docs/guides/database/connection-management)+- [Supavisor FAQ](/docs/guides/troubleshooting/supavisor-faq-YyP5tI)diff --git a/apps/docs/content/guides/database/connecting-to-postgres/serverless-drivers.mdx b/apps/docs/content/guides/database/connecting-to-postgres/serverless-drivers.mdxindex 45a51a39244..36642ee20a3 100644--- a/apps/docs/content/guides/database/connecting-to-postgres/serverless-drivers.mdx+++ b/apps/docs/content/guides/database/connecting-to-postgres/serverless-drivers.mdx@@ -7,12 +7,16 @@ subtitle: 'Choose a driver for connecting to your Postgres database from a serveLearn how to connect to your Postgres database from a serverless environment. The driver you use depends on which runtime your code runs in.-[supabase-js](/docs/reference/javascript/introduction) is an isomorphic JavaScript client that uses the [auto-generated REST API](/docs/guides/api), so it works in any environment that supports HTTPS connections. This API has a built-in [connection pooler](/docs/guides/database/connecting-to-postgres#poolers) and can serve thousands of simultaneous requests, which suits serverless workloads.+[supabase-js](/docs/reference/javascript/introduction) is an isomorphic JavaScript client that uses the [auto-generated REST API](/docs/guides/api), so it works in any environment that supports HTTPS connections. This API has a built-in [connection pooler](/docs/guides/database/connecting-to-postgres/pooling-and-limits#how-connection-pooling-works) and can serve thousands of simultaneous requests, which suits serverless workloads.++If you connect with a Postgres client instead, use the [shared pooler in transaction mode](/docs/guides/database/connecting-to-postgres#pooler-transaction-mode). Transaction mode doesn't support [prepared statements](https://postgresql.org/docs/current/sql-prepare.html), so [turn them off](https://github.com/orgs/supabase/discussions/28239) in your connection library.## Vercel Edge FunctionsVercel's [Edge runtime](https://vercel.com/docs/functions/runtimes/edge-runtime) runs on the [V8 engine](https://v8.dev/) and exposes a limited set of Web Standard APIs.+Start from a deploy template, or configure the connection yourself.+### QuickstartChoose one of these Vercel Deploy Templates. They use the [Vercel Deploy Integration](https://vercel.com/integrations/supabase) to configure your connection strings as environment variables on your Vercel project.@@ -125,6 +129,8 @@ export { sql } from 'kysely'Cloudflare's Workers runtime also uses the [V8 engine](https://v8.dev/), but it provides polyfills for a subset of Node.js APIs and the [TCP Sockets API](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/). That gives you three options:+### Drivers [#cloudflare-workers-drivers]+- [supabase-js](https://developers.cloudflare.com/workers/databases/native-integrations/supabase/)- [Postgres.js](https://github.com/porsager/postgres?tab=readme-ov-file#cloudflare-workers-support)- [node-postgres](https://developers.cloudflare.com/workers/tutorials/postgres/)@@ -133,6 +139,8 @@ Cloudflare's Workers runtime also uses the [V8 engine](https://v8.dev/), but itSupabase Edge Functions use the [Deno runtime](https://deno.com/), which has native support for TCP connections. You can choose any of these clients:+### Drivers [#supabase-edge-functions-drivers]+- [supabase-js](/docs/guides/functions/connect-to-postgres#using-supabase-js)- [Deno Postgres driver](/docs/guides/functions/connect-to-postgres#using-a-postgres-client)- [Postgres.js](https://github.com/porsager/postgres)diff --git a/apps/docs/content/guides/database/postgres/dropping-all-tables-in-schema.mdx b/apps/docs/content/guides/database/postgres/dropping-all-tables-in-schema.mdxindex 9af8ef0795c..bfacb3be120 100644--- a/apps/docs/content/guides/database/postgres/dropping-all-tables-in-schema.mdx+++ b/apps/docs/content/guides/database/postgres/dropping-all-tables-in-schema.mdx@@ -25,4 +25,4 @@ end $$;This query works by listing out all the tables in the given schema and then executing a `drop table` for each (hence the `for... loop`).-You can run this query using the [SQL Editor](/dashboard/project/_/sql) in the Supabase Dashboard, or via `psql` if you're [connecting directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).+You can run this query using the [SQL Editor](/dashboard/project/_/sql) in the Supabase Dashboard, or via `psql` if you're [connecting directly to the database](/docs/guides/database/connecting-to-postgres#direct-connection).diff --git a/apps/docs/content/guides/database/postgres/first-row-in-group.mdx b/apps/docs/content/guides/database/postgres/first-row-in-group.mdxindex b20a3eaa8b8..12333740ef6 100644--- a/apps/docs/content/guides/database/postgres/first-row-in-group.mdx+++ b/apps/docs/content/guides/database/postgres/first-row-in-group.mdx@@ -42,4 +42,4 @@ The important bits here are:- The `desc` keyword to order the `points` from highest to lowest.- The `distinct` keyword that tells Postgres to only return a single row per team.-This query can also be executed via `psql` or any other query editor if you prefer to [connect directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).+This query can also be executed via `psql` or any other query editor if you prefer to [connect directly to the database](/docs/guides/database/connecting-to-postgres#direct-connection).diff --git a/apps/docs/content/guides/database/postgres/indexes.mdx b/apps/docs/content/guides/database/postgres/indexes.mdxindex 4982a26e37d..5cd249b2ba7 100644--- a/apps/docs/content/guides/database/postgres/indexes.mdx+++ b/apps/docs/content/guides/database/postgres/indexes.mdx@@ -28,7 +28,7 @@ create table persons (<Admonition type="note">-All the queries in this guide can be run using the [SQL Editor](/dashboard/project/_/sql) in the Supabase Dashboard, or via `psql` if you're [connecting directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).+All the queries in this guide can be run using the [SQL Editor](/dashboard/project/_/sql) in the Supabase Dashboard, or via `psql` if you're [connecting directly to the database](/docs/guides/database/connecting-to-postgres#direct-connection).</Admonition>diff --git a/apps/docs/content/guides/database/postgres/timeouts.mdx b/apps/docs/content/guides/database/postgres/timeouts.mdxindex 3415ac23e93..c831515f0fe 100644--- a/apps/docs/content/guides/database/postgres/timeouts.mdx+++ b/apps/docs/content/guides/database/postgres/timeouts.mdx@@ -5,7 +5,7 @@ subtitle: Extend database timeouts to execute longer transactions<Admonition type="note">-Dashboard and [Client](/docs/guides/api/rest/client-libs) queries have a max-configurable timeout of 60 seconds. For longer transactions, use [Supavisor or direct connections](/docs/guides/database/connecting-to-postgres#quick-summary).+Dashboard and [Client](/docs/guides/api/rest/client-libs) queries have a max-configurable timeout of 60 seconds. For longer transactions, use [Supavisor or direct connections](/docs/guides/database/connecting-to-postgres#choose-a-connection-method).</Admonition>diff --git a/apps/docs/content/guides/database/postgres/which-version-of-postgres.mdx b/apps/docs/content/guides/database/postgres/which-version-of-postgres.mdxindex 5d51d77f916..f6516547146 100644--- a/apps/docs/content/guides/database/postgres/which-version-of-postgres.mdx+++ b/apps/docs/content/guides/database/postgres/which-version-of-postgres.mdx@@ -19,4 +19,4 @@ Which should return something like:PostgreSQL 15.1 on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 10.3.0-1ubuntu1~20.04) 10.3.0, 64-bit```-This query can also be executed via `psql` or any other query editor if you prefer to [connect directly to the database](/docs/guides/database/connecting-to-postgres#direct-connections).+This query can also be executed via `psql` or any other query editor if you prefer to [connect directly to the database](/docs/guides/database/connecting-to-postgres#direct-connection).diff --git a/apps/docs/content/guides/database/tables.mdx b/apps/docs/content/guides/database/tables.mdxindex a2f32f4a4aa..22b348dbfc7 100644--- a/apps/docs/content/guides/database/tables.mdx+++ b/apps/docs/content/guides/database/tables.mdx@@ -361,7 +361,7 @@ For example, if you wanted to load a CSV file into your movies table:"Return of the Jedi", "After a daring mission to rescue Han Solo from Jabba the Hutt, the Rebels dispatch to Endor to destroy the second Death Star."```-You would [connect](../../guides/database/connecting-to-postgres#direct-connections) to your database directly and load the file with the COPY command:+You would [connect](../../guides/database/connecting-to-postgres#direct-connection) to your database directly and load the file with the COPY command:```bashpsql -h DATABASE_URL -p 5432 -d postgres -U postgres \diff --git a/apps/docs/content/guides/observability/reports.mdx b/apps/docs/content/guides/observability/reports.mdxindex 3daa92daeaf..ab6e6c63b5a 100644--- a/apps/docs/content/guides/observability/reports.mdx+++ b/apps/docs/content/guides/observability/reports.mdx@@ -169,12 +169,12 @@ Why this matters for Postgres:Actions you can take:-| Action | Description |-| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |-| [Use connection pooling](/docs/guides/database/connecting-to-postgres#how-connection-pooling-works) | Route clients through Supavisor or PgBouncer to cap fork-driven commit pressure. |-| Lower `max_connections` or per-pool sizes | Reduce the upper bound on concurrent backends so spikes cannot exceed the Commit limit. |-| [Tune `work_mem`](https://pgtune.leopard.in.ua) | Reduce per-operation memory allocations on workloads with many concurrent queries. |-| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Raise both physical RAM and the Commit limit so the workload fits with headroom. |+| Action | Description |+| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |+| [Use connection pooling](/docs/guides/database/connecting-to-postgres/pooling-and-limits#how-connection-pooling-works) | Route clients through Supavisor or PgBouncer to cap fork-driven commit pressure. |+| Lower `max_connections` or per-pool sizes | Reduce the upper bound on concurrent backends so spikes cannot exceed the Commit limit. |+| [Tune `work_mem`](https://pgtune.leopard.in.ua) | Reduce per-operation memory allocations on workloads with many concurrent queries. |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Raise both physical RAM and the Commit limit so the workload fits with headroom. |### CPU usage@@ -345,11 +345,11 @@ How it helps debug issues:Actions you can take:-| Action | Description |-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |-| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |-| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#shared-pooler) | Optimize connection management for high direct connection usage |-| Review application code | Ensure proper connection handling and cleanup |+| Action | Description |+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |+| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#choose-a-connection-method) | Optimize connection management for high direct connection usage |+| Review application code | Ensure proper connection handling and cleanup |{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}@@ -369,11 +369,11 @@ How it helps debug issues:Actions you can take:-| Action | Description |-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |-| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |-| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#shared-pooler) | Optimize connection management for high direct connection usage |-| Review application code | Ensure proper connection handling and cleanup |+| Action | Description |+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |+| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#choose-a-connection-method) | Optimize connection management for high direct connection usage |+| Review application code | Ensure proper connection handling and cleanup |{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}@@ -393,11 +393,11 @@ How it helps debug issues:Actions you can take:-| Action | Description |-| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |-| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |-| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#shared-pooler) | Optimize connection management for high direct connection usage |-| Review application code | Ensure proper connection handling and cleanup |+| Action | Description |+| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |+| [Upgrade compute size](/docs/guides/platform/compute-and-disk#compute-size) | Increase maximum connection limits |+| Implement [connection pooling](/docs/guides/database/connecting-to-postgres#choose-a-connection-method) | Optimize connection management for high direct connection usage |+| Review application code | Ensure proper connection handling and cleanup |### Disk Usagediff --git a/apps/docs/content/guides/platform/manage-your-usage/egress.mdx b/apps/docs/content/guides/platform/manage-your-usage/egress.mdxindex b05dbb00359..09e49705282 100644--- a/apps/docs/content/guides/platform/manage-your-usage/egress.mdx+++ b/apps/docs/content/guides/platform/manage-your-usage/egress.mdx@@ -47,7 +47,7 @@ Data pushed to clients via Supabase Realtime for subscribed events.Data sent to the client when using the shared connection pooler (Supavisor) to access your database. When using the shared connection pooler, we do not count database egress, as this would otherwise count double (Database -> Shared Pooler + Shared Pooler -> Client).-**Example:** You are using our [shared connection pooler](/docs/guides/database/connecting-to-postgres#shared-pooler) and you query a list of invoices in your backend. The data returned from that query is contributing to Shared Pooler Egress.+**Example:** You are using our [shared connection pooler](/docs/guides/database/connecting-to-postgres/pooling-and-limits#shared-pooler) and you query a list of invoices in your backend. The data returned from that query is contributing to Shared Pooler Egress.### Log Drain Egressdiff --git a/apps/docs/content/guides/platform/performance.mdx b/apps/docs/content/guides/platform/performance.mdxindex 246ad18e91d..d0ff40d8d37 100644--- a/apps/docs/content/guides/platform/performance.mdx+++ b/apps/docs/content/guides/platform/performance.mdx@@ -31,7 +31,7 @@ In such a scenario, you can consider:You can use the [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) view to debug which clients are holding open connections on your DB. `pg_stat_activity` only exposes information on direct connections to the database. Information on the number of connections to Supavisor is available [via the metrics endpoint](../telemetry/metrics).-Depending on the clients involved, you might be able to configure them to work with fewer connections (e.g. by imposing a limit on the maximum number of connections they're allowed to use), or shift specific workloads to connect via [Supavisor](/docs/guides/database/connecting-to-postgres#poolers) instead. Transient workflows, which can scale up and down rapidly in response to traffic (e.g. serverless functions), can especially benefit from using a connection pooler rather than connecting to the DB directly.+Depending on the clients involved, you might be able to configure them to work with fewer connections (e.g. by imposing a limit on the maximum number of connections they're allowed to use), or shift specific workloads to connect via [Supavisor](/docs/guides/database/connecting-to-postgres/pooling-and-limits#shared-pooler) instead. Transient workflows, which can scale up and down rapidly in response to traffic (e.g. serverless functions), can especially benefit from using a connection pooler rather than connecting to the DB directly.### Allowing higher number of connectionsdiff --git a/apps/docs/content/troubleshooting/database-error-remaining-connection-slots-are-reserved-for-non-replication-superuser-connections-3V3nIb.mdx b/apps/docs/content/troubleshooting/database-error-remaining-connection-slots-are-reserved-for-non-replication-superuser-connections-3V3nIb.mdxindex 6a200efb796..ac619a13b85 100644--- a/apps/docs/content/troubleshooting/database-error-remaining-connection-slots-are-reserved-for-non-replication-superuser-connections-3V3nIb.mdx+++ b/apps/docs/content/troubleshooting/database-error-remaining-connection-slots-are-reserved-for-non-replication-superuser-connections-3V3nIb.mdx@@ -15,6 +15,6 @@ This error usually occurs when the database reaches the maximum number of connecTo overcome this, the connections need to be optimized as mentioned here: https://supabase.com/docs/guides/platform/performance#optimizing-the-number-of-connectionsAdditionally, you can try using the connection pool to help solve this issue:-https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler+https://supabase.com/docs/guides/database/connecting-to-postgres/pooling-and-limits#how-connection-pooling-worksIf you're already using connection pooling and still hitting the maximum connections, then it is suggested to upgrade your compute add-on that allows more connections: https://supabase.com/docs/guides/platform/compute-and-diskdiff --git a/apps/docs/content/troubleshooting/fatal-password-authentication-failed.mdx b/apps/docs/content/troubleshooting/fatal-password-authentication-failed.mdxnew file mode 100644index 00000000000..5dbb9e869d9--- /dev/null+++ b/apps/docs/content/troubleshooting/fatal-password-authentication-failed.mdx@@ -0,0 +1,31 @@+---+title = "FATAL: Password authentication failed"+date_created = "2026-09-02T00:00:00+00:00"+topics = [ "database", "supavisor" ]+keywords = [ "password", "authentication", "credentials", "fail2ban" ]+[[errors]]+message = "FATAL: password authentication failed for user"+---++A `FATAL: Password authentication failed` error means Postgres rejected your credentials. Check the username before the password, because the username is the more common mistake.++## Check the username first++The username depends on how you connect:++- Direct connections and the dedicated pooler use `postgres`.+- Shared pooler connections use `postgres.[PROJECT-REF]`.++Supplying the wrong one usually produces [Tenant or user not found](/docs/guides/troubleshooting/tenant-or-user-not-found) rather than this error, but a valid username with the wrong password lands here.++## Check the password++Reserved characters in a password have to be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) when they appear in a connection string. This covers `&`, `#`, `?`, and spaces, among others. A password that works in a GUI field can fail in a URI for this reason alone.++If you don't have the password, [reset it](/docs/guides/troubleshooting/how-do-i-reset-my-supabase-database-password-oTs5sB) in [Database settings](/dashboard/project/_/database/settings).++## Repeated failures cause a different error++Repeated authentication failures from the same address get that address banned. Once banned, connections stop failing with this error and start failing with [connection refused](/docs/guides/troubleshooting/error-connection-refused-when-trying-to-connect-to-supabase-database-hwG0Dr) instead.++If your error changes from authentication failed to connection refused while you're testing credentials, you're banned rather than locked out. That page has the unban procedure.diff --git a/apps/docs/content/troubleshooting/http-api-issues.mdx b/apps/docs/content/troubleshooting/http-api-issues.mdxindex de8836ef69d..3ac17e74db1 100644--- a/apps/docs/content/troubleshooting/http-api-issues.mdx+++ b/apps/docs/content/troubleshooting/http-api-issues.mdx@@ -47,7 +47,7 @@ Errors about too many open connections can be _temporarily_ resolved by [restart- 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#connection-pool) instead.+- 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 refuseddiff --git a/apps/docs/content/troubleshooting/tenant-or-user-not-found.mdx b/apps/docs/content/troubleshooting/tenant-or-user-not-found.mdxnew file mode 100644index 00000000000..f3982d98c27--- /dev/null+++ b/apps/docs/content/troubleshooting/tenant-or-user-not-found.mdx@@ -0,0 +1,34 @@+---+title = "Tenant or user not found when connecting through the shared pooler"+date_created = "2026-09-02T00:00:00+00:00"+topics = [ "database", "supavisor" ]+keywords = [ "pooler", "supavisor", "tenant", "hostname", "username" ]+[[errors]]+message = "Tenant or user not found"+[[errors]]+message = "FATAL: (ENOTFOUND) tenant/user postgres.<project-ref> not found"+---++A `Tenant or user not found` error means the shared pooler couldn't match your host and username to a project. Some drivers report it as `FATAL: (ENOTFOUND) tenant/user postgres.<project-ref> not found`.++The error reads like a credentials problem, so it often sends people to reset a password that was never wrong. The cause is almost always the host or the username, not the password.++## The host was typed instead of copied++Shared pooler hosts look like `aws-1-us-east-2.pooler.supabase.com`. The number is a pooler cluster index, not part of the region name, and a region can have more than one. `aws-0` is not a safe default, and you can't work the host out from your region.++Copy the host from the [Connect](/dashboard/project/_?showConnect=true) dialog rather than composing it.++## The username is missing the project ref++Shared pooler connections use `postgres.[PROJECT-REF]`, not `postgres`. Direct connections and the dedicated pooler use `postgres`.++If you connect as a custom role through the shared pooler, the username is `[ROLE].[PROJECT-REF]`. Supplying only the role name, with no project ref, produces this error rather than an authentication failure.++## How to fix it++1. Open the [Connect](/dashboard/project/_?showConnect=true) dialog in the Supabase Dashboard.+2. Choose **Session pooler** or **Transaction pooler**.+3. Copy the whole string, and replace only the password placeholder.++For the full set of hosts, ports, and usernames, see [Connect to your database](/docs/guides/database/connecting-to-postgres).