The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.mdxindex 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/dThe 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 automatApplication-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 poolersPostgres 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.<Imagealt="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 perDifferent 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.<Imagealt="Decision tree diagram showing when to connect directly to Postgres or use a connection pooler."