fix: update connection strings for ipv6/supavisor (supabase#20394)

* fix: update connection strings for ipv6/supavisor

* Update redwoodjs quickstarter with the latest prisma instructions

* Update screenshot for obtaining connection string

* Add the direct_url back to redwood quickstarter guide

* update redwood guide

* update screenshots and connecting text

---------

Co-authored-by: dshukertjr <[email protected]>
Co-authored-by: Inian <[email protected]>

Author: 3 people

apps/docs/pages/guides/ai/google-colab.mdx

@@ -39,14 +39,14 @@ pip install vecs
 
 ## Connect to your database
 
-Find the Postgres connection string for your Supabase project in the [database settings](https://supabase.com/dashboard/_/settings/database) of the dashboard. Copy the "URI" format, which should look something like `postgresql:/postgres:<password>@<host>:5432/postgres`
+Find the Postgres pooler connection string for your Supabase project in the [database settings](https://supabase.com/dashboard/_/settings/database) of the dashboard. Copy the "URI" format, which should look something like `postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres`
 
 Create a new code block below the install block (`ctrl+m b`) and add the following code using the Postgres URI you copied above:
 
 ```py
 import vecs
 
-DB_CONNECTION = "postgresql://postgres:<password>@<host>:5432/postgres"
+DB_CONNECTION = "postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres"
 
 # create vector store client
 vx = vecs.create_client(DB_CONNECTION)

apps/docs/pages/guides/database/connecting-to-postgres.mdx

@@ -22,54 +22,47 @@ Supabase provides auto-updating Data APIs. These are the easiest way to get star
 - [GraphQL](/docs/guides/graphql/api): interact with your database through a GraphQL interface.
 - [Realtime](/docs/guides/realtime#realtime-api): listen to database changes over websockets.
 
-## Direct connections
+## Connection pooler
+
+Every Supabase project comes with a connection pooler for managing connections to your Postgres database.
+
+A connection pooler is useful for managing a large number of _temporary_ connections - for example, if you are using Prisma, Drizzle, Kysely, or anything deployed to a Serverless environment (AWS Lambdas or Edge Functions). Supabase's connection pooler also supports ipv4 out of the box.
 
-Every Supabase project provides a full Postgres database. You can connect to the database using any tool which supports Postgres. Direct connections are on port `5432`. You can find the connection string in the [Database settings](https://supabase.com/dashboard/project/_/settings/database) inside the dashboard:
+You can find the connection pool config in the [Database settings](/dashboard/project/_/settings/database) inside the dashboard:
 
 1. Go to the `Settings` section.
 2. Click `Database`.
-3. Find your Connection Info and Connection String.
+3. Under `Connect to your database via connection pooling`, copy your `Connection string`.
 
-<video width="99%" muted playsInline controls={true}>
-  <source
-    src="https://xguihxuzqibwxjnimxev.supabase.co/storage/v1/object/public/videos/docs/postgres-connection.mp4"
-    type="video/mp4"
-  />
-</video>
+## Direct connections
 
-## Connection pooler
+You can use a direct connection to connect directly to your Postgres database. By default, this connection uses ipv6, which isn't supported by all network providers. If you need an ipv4 address, use the [connection pooler](#connection-pooler) instead.
 
-Every Supabase project comes with a connection pooler for managing connections to your Postgres database. A connection pooler is useful for managing a large number of _temporary_ connections - for example, if you are using Prisma, Drizzle, Kysely, or anything deployed to a Serverless environment (AWS Lambdas or Edge Functions). You can find the connection pool config in the [Database settings](/dashboard/project/_/settings/database) inside the dashboard:
+You can find the direct connection string in the [Database settings](https://supabase.com/dashboard/project/_/settings/database) inside the dashboard:
 
 1. Go to the `Settings` section.
 2. Click `Database`.
-3. Find your Connection Info and Connection String. Connection pooling is on port `6543`.
-
-<video width="99%" muted playsInline controls={true}>
-  <source
-    src="https://xguihxuzqibwxjnimxev.supabase.co/storage/v1/object/public/videos/docs/connection-pool-config.mp4"
-    type="video/mp4"
-  />
-</video>
+3. Under `Connect to your database directly`, copy your `Connection string`.
 
 ## Choosing a connection method
 
 - The Data APIs provide programmatic access and have [built-in connection pooling](https://postgrest.org/en/stable/references/connection_pool.html). You can use these for all browser and application interactions. We recommend using these wherever possible.
-- A "direct connection" is Postgres' native connection system. You should use this for tools which are always alive - usually installed on a long-running server, like Node.js, Ruby, Python, etc.
-- A "connection pooler" is a tool which keeps connections "alive". You should use this for serverless functions and tools which disconnect from the database frequently, like Prisma, Drizzle, Kysely, etc.
+- A "connection pooler" is a tool which keeps connections "alive". You should use this for serverless functions and tools which disconnect from the database frequently, like Prisma, Drizzle, Kysely, etc. You should also use this if your network doesn't support ipv6.
+- A "direct connection" is Postgres' native connection system. You can use this for tools which are always alive, such as long-running server, as long as your network supports ipv6.
 
 Why would you use a connection pool? Primarily because the way that Postgres handles connections isn't very scalable for a large number of _temporary_ connections. You can use these simple questions to determine which connection method to use:
 
-- Are you connecting to a database and _maintaining_ a connection? If yes, use a direct connection.
-- Are you connecting to your database and then _disconnecting_ immediately (e.g. a serverless environment)? If yes, use a connection pool.
+- Are you on a network that doesn't support ipv6? Use the connection pooler.
+- Are you connecting to your database and then _disconnecting_ immediately (e.g. a serverless environment)? Use the connection pooler.
+- Are you connecting to a database and _maintaining_ a connection, and does your network support ipv6? If yes, use a direct connection.
 
 ## Connecting with SSL
 
 You should connect to your database using SSL wherever possible, to prevent snooping and man-in-the-middle attacks.
 
 You can obtain your connection info and Server root certificate from your application's dashboard:
 
-![Connection Info and Certificate.](/docs/img/guides/database/connection-info-cert.png)
+![Connection Info and Certificate.](/docs/img/database/database-settings-ssl.png)
 
 ## Integrations
 

apps/docs/pages/guides/database/import-data.mdx

@@ -49,7 +49,7 @@ You can use it in conjunction with Supabase by following these steps:
    ```sql
    LOAD DATABASE
        FROM sourcedb://USER:PASSWORD@HOST/SOURCE_DB
-       INTO postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+       INTO postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
    ALTER SCHEMA 'public' OWNER TO 'postgres';
    set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
    ```

apps/docs/pages/guides/getting-started/quickstarts/laravel.mdx

@@ -62,7 +62,7 @@ export const meta = {
 
     ```bash .env
     DB_CONNECTION=pgsql
-    DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres
+    DATABASE_URL=postgres://postgres.xxxx:[email protected].supabase.com:6543/postgres
     ```
 
     </StepHikeCompact.Code>

apps/docs/pages/guides/getting-started/quickstarts/redwoodjs.mdx

@@ -29,12 +29,16 @@ export const meta = {
 
   <StepHikeCompact.Step step={2}>
     <StepHikeCompact.Details title="Gather Database Connection Strings">
-      After your project is ready, gather the following information about your [database connections](https://supabase.com/dashboard/project/_/settings/database):
 
-      * Connection String (port 5432)
-      * Connection Pooling / Connection String (port 6543)
+    Go to the [database settings page](https://supabase.com/dashboard/project/_/settings/database). In this quickstart, we are going to connect via the connection pooler. If your network supports IPv6, you can connect to the database directly without using the connection pooler.
 
-    You will need these to setup environment variables in Step 5.
+    We will use the pooler both in `Transaction` and `Session` mode. `Transaction` mode is used for application queries and `Session` mode is used for running migrations with Prisma.
+
+    To do this, set the connection mode to `Transaction` in the [database settings page](https://supabase.com/dashboard/project/_/settings/database) and copy the connection string and append `?pgbouncer=true&&connection_limit=1`. `pgbouncer=true` disables Prisma from generating prepared statements. This is required since our connection pooler does not support prepared statements in transaction mode yet. The `connection_limit=1` parameter is only required if you are using Prisma from a serverless environment. This is the Transaction mode connection string.
+
+    To get the Session mode connection pooler string, change the port of the connection string from the dashboard to 5432.
+
+    You will need the Transaction mode connection string and the Session mode connection string to setup environment variables in Step 5.
 
     <Admonition type="tip">
 
@@ -86,26 +90,22 @@ export const meta = {
 
   <StepHikeCompact.Step step={5}>
     <StepHikeCompact.Details title="Configure Environment Variables">
-      In your `.env` file, add the following environment variables for your database connection:
 
-      * The `DIRECT_URL` should use the `Connection String` from your Supabase project. Hint: the port is `5432`.
-
-      * The `DATABASE_URL` should use the `Connection Pooling / Connection String` from your Supabase project. Hint: the port is `6543`.
+      In your `.env` file, add the following environment variables for your database connection:
 
-      <Admonition type="note">
+      * The `DIRECT_URL` should use the Transaction mode connection string you copied in Step 1.
 
-        Also, replace `[YOUR-PASSWORD]` and `[YOUR-PROJECT-REF]` with the password you used when creating your Supabase project and the project reference from the URL in your browser.
+      * The `DATABASE_URL` should use the Session mode connection string you copied in Step 1.
 
-      </Admonition>
     </StepHikeCompact.Details>
 
     <StepHikeCompact.Code>
       ```bash .env
-      # PostgreSQL connection string used for migrations
-      DIRECT_URL="postgres://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres"
+      # Transaction mode connection string used for migrations
+      DIRECT_URL="postgres://postgres.[project-ref]:[db-password]@xxx.pooler.supabase.com:6543/postgres?pgbouncer=true&connection_limit=1"
 
-      # PostgreSQL pooler connection string with Supavisor config — used by Prisma Client
-      DATABASE_URL="postgres://postgres.[YOUR-PROJECT-REF]:[YOUR-PASSWORD]@aws-0-[YOUR-PROJECT-REGION].pooler.supabase.com:6543/postgres"
+      # Session mode connection string — used by Prisma Client
+      DATABASE_URL="postgres://postgres.[project-ref]:[db-password]@xxx.pooler.supabase.com:5432/postgres"
       ```
     </StepHikeCompact.Code>
 

apps/docs/pages/guides/getting-started/quickstarts/ruby-on-rails.mdx

@@ -43,7 +43,7 @@ export const meta = {
     <StepHikeCompact.Code>
 
     ```bash Terminal
-    export DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres
+    export DATABASE_URL=postgres://postgres.xxxx:[email protected].supabase.com:6543/postgres
     ```
 
     </StepHikeCompact.Code>

apps/docs/pages/guides/platform/branching.mdx

@@ -157,7 +157,7 @@ You can use the [Supabase CLI](/docs/guides/cli) to manage changes inside a loca
             supabase db pull --db-url <db_url>
 
             # Your Database URL looks something like:
-            # postgresql://username:password@db.ref.supabase.co:5432/postgres
+            # postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
             ```
 
             </CH.Code>
@@ -487,7 +487,7 @@ Dashboard changes aren't automatically reflected in your Git repository. If you'
          <CH.Code lineNumbers={false}>
 
         ```bash
-        supabase db pull --db-url "postgres://postgres:[password]@db.[branch-ref].supabase.co:5432/postgres"
+        supabase db pull --db-url "postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres"
         ```
 
         </CH.Code>

apps/docs/pages/guides/platform/migrating-and-upgrading-projects.mdx

@@ -139,6 +139,12 @@ Migrating projects can be achieved using the Supabase CLI. This is particularly
 - Set environment variables for the old project's database URL as `$OLD_DB_URL` and the new project's as `$NEW_DB_URL`.
   To find the database URL for a project, go to the project's dashboard page [Project Settings/Database](https://supabase.com/dashboard/project/_/settings/database) and look at `Connection string / URI`. For example, to set the `$OLD_DB_URL` you would run `export OLD_DB_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF#].supabase.co:5432/postgres`.
 
+<Admonition type="tip">
+
+Note that this direct connection string to the database uses IPv6. If your network provider doesn't yet support IPv6, you can connect via the pooler connection string, available under the **Connection pooling** section of [**Database settings**](https://supabase.com/dashboard/project/_/settings/database). The connection string has the format `postgres://postgres.xxxx:[email protected]:6543/postgres`.
+
+</Admonition>
+
 ### Backup your old database
 
 1. Run the following command from your terminal:

apps/docs/pages/guides/resources/migrating-to-supabase/amazon-rds.mdx

@@ -28,7 +28,7 @@ Supabase's core is Postgres, enabling the use of row-level security and providin
 1. Under **Connection Info**, note your Host (`$SUPABASE_HOST`).
 1. Save your password or [reset it](https://supabase.com/dashboard/project/_/settings/database) if you forgot it.
 
-![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/supabase_dashboard.png)
+![Finding Supabase host address](/docs/img/database/database-settings-host.png)
 
 ## Migrate the database
 
@@ -60,7 +60,7 @@ Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a fl
 ```sql
 load database
   from mysql://user:password@host/source_db
-  into postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+  into postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
 alter schema 'public' owner to 'postgres';
 set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
 ```
@@ -80,7 +80,7 @@ pgloader config.load
 ```sql
 LOAD DATABASE
     FROM mssql://USER:PASSWORD@HOST/SOURCE_DB
-    INTO postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+    INTO postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
 ALTER SCHEMA 'public' OWNER TO 'postgres';
 set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
 ```

apps/docs/pages/guides/resources/migrating-to-supabase/mssql.mdx

@@ -25,7 +25,7 @@ Before you begin the migration, you need to collect essential information about
 1. Under **Connection Info**, note your Host (`$SUPABASE_HOST`).
 1. Save your password or [reset it](https://supabase.com/dashboard/project/_/settings/database) if you forgot it.
 
-![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/supabase_dashboard.png)
+![Finding Supabase host address](/docs/img/database/database-settings-host.png)
 
 ## Migrate the database
 
@@ -57,7 +57,7 @@ Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a fl
 ```sql
 LOAD DATABASE
     FROM mssql://USER:PASSWORD@HOST/SOURCE_DB
-    INTO postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+    INTO postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
 ALTER SCHEMA 'public' OWNER TO 'postgres';
 set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
 ```

apps/docs/pages/guides/resources/migrating-to-supabase/mysql.mdx

@@ -26,7 +26,7 @@ Before you begin the migration, you need to collect essential information about
 1. Under **Connection Info**, note your Host (`$SUPABASE_HOST`).
 1. Save your password or [reset it](https://supabase.com/dashboard/project/_/settings/database) if you forgot it.
 
-![Finding Supabase host address](/docs/img/guides/resources/migrating-to-supabase/amazon-rds/supabase_dashboard.png)
+![Finding Supabase host address](/docs/img/database/database-settings-host.png)
 
 ## Migrate the database
 
@@ -58,7 +58,7 @@ Alternatively, you can use [pgloader](https://github.com/dimitri/pgloader), a fl
 ```sql
 load database
   from mysql://user:password@host/source_db
-  into postgres://postgres:password@db.xxxx.supabase.co:6543/postgres
+  into postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:6543/postgres
 alter schema 'public' owner to 'postgres';
 set wal_buffers = '64MB', max_wal_senders = 0, statement_timeout = 0, work_mem to '2GB';
 ```