Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

chore(docs): clarify Postgres connection options and IPv4/IPv6 support (#46294)

Andrey A.0f3fefbd5b2f
diff --git a/apps/docs/content/guides/database/connecting-to-postgres.mdx b/apps/docs/content/guides/database/connecting-to-postgres.mdx
index 9f811ac302c..b1ee6e35da7 100644
--- a/apps/docs/content/guides/database/connecting-to-postgres.mdx
+++ b/apps/docs/content/guides/database/connecting-to-postgres.mdx
@@ -10,9 +10,24 @@ How you connect to your database depends on where you're connecting from:
- For frontend applications, use the [Data API](#data-apis-and-client-libraries)
- For Postgres clients, use a connection string
- - For single sessions (for example, database GUIs) or Postgres native commands (for example, using client applications like [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html), [migrations](/docs/guides/deployment/database-migrations), [backup-restore](/docs/guides/platform/migrating-within-supabase/backup-restore), or specifying connections for [replication](/docs/guides/database/postgres/setup-replication-external)) use the [direct connection string](#direct-connection) if your environment supports IPv6. IPv4 available as [Add-on](/docs/guides/platform/ipv4-address).
- - For application traffic from persistent clients, and support for both IPv4 and IPv6, use [pooler session mode](#pooler-session-mode)
- - For application traffic from temporary clients (for example, serverless or edge functions) use [pooler transaction mode](#pooler-transaction-mode)
+ - **Use the [direct connection string](#direct-connection) for single sessions or Postgres native commands**. For example, database GUIs, client applications like [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html), [migrations](/docs/guides/deployment/database-migrations), [backup-restore](/docs/guides/platform/migrating-within-supabase/backup-restore), or specifying connections for [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 clients on IPv4-only networks,
+ - **Use [pooler transaction mode](#pooler-transaction-mode)** for application traffic from temporary clients (for example, serverless or edge functions).
+
+The table below summarizes each mode, its host and port, IP version support per project tier, and what it's best used for:
+
+| Mode | Host:Port | Free | Paid | Paid + IPv4 add-on | Best for |
+| ----------------------------------------------- | --------------------------------------- | ---- | ---- | ------------------ | ------------------------------------------ |
+| Direct connection | `db.[project-id].supabase.co:5432` | IPv6 | IPv6 | IPv4 | Migrations, `pg_dump`, long-lived backend |
+| Shared pooler (Supavisor) - session mode | `aws-[region].pooler.supabase.com:5432` | IPv4 | IPv4 | IPv4 | Persistent backend on IPv4-only networks |
+| Shared pooler (Supavisor) - transaction mode | `aws-[region].pooler.supabase.com:6543` | IPv4 | IPv4 | IPv4 | Serverless and edge functions |
+| Dedicated pooler (PgBouncer) - transaction mode | `db.[project-id].supabase.co:6543` | - | IPv6 | IPv4 | High-performance app traffic on paid tiers |
+
+<Admonition type="caution">
+
+The IPv4 add-on is not dual-stack: enabling it swaps the project's IPv6 (AAAA) DNS record for an IPv4 (A) record, so the project endpoint becomes reachable only over IPv4.
+
+</Admonition>
## Quickstarts
@@ -67,7 +82,7 @@ The direct connection string connects directly to your Postgres instance. It is
<Admonition type="caution">
-Direct connections use IPv6 by default. If your environment doesn't support IPv6, use [Supavisor session mode](#supavisor-session-mode) or get the [IPv4 add-on](/docs/guides/platform/ipv4-address).
+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.
</Admonition>
@@ -81,23 +96,23 @@ Get your project's direct connection string from your project dashboard by click
## Poolers
-Every Supabase project includes a connection pooler. This is ideal for persistent servers when IPv6 is not supported.
+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 co-located with 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).
### Pooler session mode
-The session mode connection string connects to your Postgres instance via a proxy. This is only recommended as an alternative to a Direct Connection, when connecting via an IPv4 network.
+The session mode connection string connects to your Postgres instance via the Shared Pooler (Supavisor). This is only recommended as an alternative to a Direct Connection when connecting from an IPv4-only network.
The connection string looks like this:
```
-postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
+postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-[REGION].pooler.supabase.com:5432/postgres
```
Get your project's Session pooler connection string from your project dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=session).
### Pooler transaction mode
-The transaction mode connection string connects to your Postgres instance via a proxy which serves as a connection pooler. This is ideal for serverless or edge functions, which require many transient connections.
+The transaction mode connection string connects to your Postgres instance via the Shared Pooler (Supavisor) in transaction-pooling mode. This is ideal for serverless or edge functions, which require many transient connections.
<Admonition type="caution">
@@ -108,14 +123,20 @@ Transaction mode does not support [prepared statements](https://postgresql.org/d
The connection string looks like this:
```
-postgres://postgres:[YOUR-PASSWORD]@db.abcdefghijklmnopqrst.supabase.co:6543/postgres
+postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-[REGION].pooler.supabase.com:6543/postgres
```
Get your project's Transaction pooler connection string from your project dashboard by clicking [Connect](/dashboard/project/_?showConnect=true&method=transaction).
## Dedicated pooler
-For paying customers, we provision a Dedicated Pooler ([PgBouncer](https://www.pgbouncer.org/)) that's co-located with your Postgres database. This will require you to connect with IPv6 or, if that's not an option, you can use the [IPv4 add-on](/docs/guides/platform/ipv4-address).
+For paying customers, we provision a Dedicated Pooler ([PgBouncer](https://www.pgbouncer.org/)) that's co-located with 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:
+
+```
+postgres://postgres:[YOUR-PASSWORD]@db.abcdefghijklmnopqrst.supabase.co:6543/postgres
+```
The Dedicated Pooler ensures best performance and latency, while using up more of your project's compute resources. If your network supports IPv6 or you have the IPv4 add-on, we encourage you to use the Dedicated Pooler over the Shared Pooler.
@@ -131,11 +152,11 @@ You can use an application-side pooler or a server-side pooler (Supabase automat
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, reducing the overhead of establishing connections between queries. When deploying to static architecture, such as long-standing containers or VMs, application-side poolers are satisfactory on their own.
-### Serverside poolers
+### Server-side poolers
Postgres connections are like a WebSocket. Once established, they are preserved until the client (application server) disconnects. A server might only make a single 10 ms query, but needlessly reserve its database connection for seconds or longer.
-Serverside-poolers, such as Supabase's [Supavisor](https://github.com/supabase/supavisor) in transaction mode, sit between clients and the database and can be thought of as load balancers for Postgres connections.
+Server-side poolers, such as Supabase's [Supavisor](https://github.com/supabase/supavisor) in transaction mode, sit between clients and the database and can be thought of as load balancers for Postgres connections.
<Image
alt="New migration files trigger migrations on the preview instance."
@@ -180,7 +201,7 @@ This error occurs when your credentials are incorrect. Double-check your usernam
### How do you connect using IPv4?
-Supabase’s default direct connection supports IPv6 only. To connect over IPv4, consider using the Supavisor session or transaction modes, or a connection pooler (shared or dedicated), which support both IPv4 and IPv6.
+You have two options. The Shared Pooler (Supavisor) is IPv4-only on every project tier - use it in either session or transaction mode. Alternatively, add the [IPv4 add-on](/docs/guides/platform/ipv4-address) to your project, which makes the direct connection and Dedicated Pooler reachable over IPv4 instead of IPv6.
### Where is the Postgres connection string in Supabase?
@@ -259,10 +280,10 @@ Even if your application isn’t making queries, some Supabase services keep per
Different modes use different ports:
-- Direct connection: `5432` (database server)
-- PgBouncer: `6543` (database server)
-- Supavisor transaction mode: `6543` (separate server)
-- Supavisor session mode: `5432` (separate server)
+- Direct connection: `5432` (Postgres on your project instance)
+- Dedicated pooler, transaction mode: `6543` (PgBouncer on your project instance)
+- Shared pooler, transaction mode: `6543` (Supavisor, multi-tenant)
+- Shared pooler, session mode: `5432` (Supavisor, multi-tenant)
The port helps route the connection to the right pooler/mode.
@@ -276,22 +297,23 @@ Because the dedicated pooler is hosted on the same machine as your database, it
- Best for: persistent backend services
- Use for migrations, pg_dump, backup and management tools
-- Limitation: IPv6 only by default. IPv4 available as [Add-on](/docs/guides/platform/ipv4-address).
+- Network: reachable over IPv6, or over IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address).
-**Shared pooler:**
+**Shared pooler (Supavisor):**
-- Best for: general-purpose connections (supports IPv4 and IPv6)
- - Supavisor session mode → persistent backend that require IPv4
+- Best for: connections from IPv4 networks (IPv4-only on every tier)
+ - Supavisor session mode → persistent backend on IPv4 networks
- Supavisor transaction mode → serverless functions or short-lived tasks
- Use for application runtime traffic (queries, writes)
-**Dedicated pooler (paid tier):**
+**Dedicated pooler (PgBouncer, paid tier):**
- Best for: high-performance apps that need dedicated resources
- Use for application runtime traffic (queries, writes)
-- Uses PgBouncer
+- Transaction mode only - use the Shared Pooler if you need session mode
+- Network: reachable over IPv6, or over IPv4 if the project has the [IPv4 add-on](/docs/guides/platform/ipv4-address)
-You can follow the decision flow in the connection method diagram to quickly choose the right option for your environment.
+See the [connection method matrix](#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.
<Image
alt="Decision tree diagram showing when to connect directly to Postgres or use a connection pooler."