feat: revised pooling docs

.gitignore

@@ -29,6 +29,7 @@ pnpm-debug.log*
 .env*.local
 .vercel
 next-env.d.ts
+.codex
 
 # Playwright
 /test-results/

apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-mysql.mdx

@@ -11,7 +11,7 @@ This guide provides step-by-step instructions for importing data from an existin
 You can accomplish this migration in four steps:
 
 1. Create a new Prisma Postgres database.
-1. Connect directly to a Prisma Postgres instance using a [direct connection](/postgres/database/direct-connections).
+1. Connect directly to a Prisma Postgres instance using a [direct connection](/postgres/database/connecting-to-your-database).
 1. Migrate your MySQL data to Prisma Postgres using [pgloader](https://pgloader.io/).
 1. Configure your Prisma project for Prisma Postgres.
 
@@ -53,7 +53,7 @@ Save the connection string, as you'll need it in step 3.
 
 ## 2. Prepare your direct connection string
 
-In this step, you'll use the [direct connection string](/postgres/database/direct-connections) you obtained in step 1 to connect to your Prisma Postgres instance.
+In this step, you'll use the [direct connection string](/postgres/database/connecting-to-your-database) you obtained in step 1 to connect to your Prisma Postgres instance.
 
 Your direct connection string should look like this:
 

apps/docs/content/docs/(index)/prisma-postgres/import-from-existing-database-postgresql.mdx

@@ -14,7 +14,7 @@ You can accomplish this migration in three steps:
 1. Export your existing data via `pg_dump`.
 1. Import the previously exported data into Prisma Postgres via `pg_restore`.
 
-In the third step, you will be using a [direct connection](/postgres/database/direct-connections) to securely connect to your Prisma Postgres database to run `pg_restore`.
+In the third step, you will be using a [direct connection](/postgres/database/connecting-to-your-database) to securely connect to your Prisma Postgres database to run `pg_restore`.
 
 ## Prerequisites
 
@@ -110,7 +110,7 @@ Running this command will create a backup file named `db_dump.bak` which you wil
 
 ## 3. Import data into Prisma Postgres
 
-In this section, you'll use your [direct connection string](/postgres/database/direct-connections) to connect to your Prisma Postgres instance and import data via `pg_restore`.
+In this section, you'll use your [direct connection string](/postgres/database/connecting-to-your-database) to connect to your Prisma Postgres instance and import data via `pg_restore`.
 
 Your direct connection string from step 1 should look like this:
 

apps/docs/content/docs/guides/postgres/vercel.mdx

@@ -8,7 +8,7 @@ metaDescription: Learn how to create Prisma Postgres databases via the Vercel Ma
 
 The [Vercel Marketplace integration for Prisma Postgres](https://www.vercel.com/marketplace/prisma) connects your Vercel projects with Prisma Postgres instances. Once connected, the integration will automatically set the following environment variable on your deployed Vercel app:
 
-- `DATABASE_URL`: The [direct TCP connection URL](/postgres/database/direct-connections) starting with `postgres://...`
+- `DATABASE_URL`: A Prisma Postgres [connection string](/postgres/database/connecting-to-your-database) starting with `postgres://...`
 
 These enable you to connect to the Prisma Postgres instances via any ORM or database library you want to use (Prisma ORM, Drizzle, Kysely, ...).
 

apps/docs/content/docs/guides/runtimes/bun.mdx

@@ -82,7 +82,7 @@ This command creates:
 
 ### 2.3. Configure environment variables for direct connection
 
-We're going to use a direct connection string for connecting to Prisma Postgres. To get your [direct connection string](/postgres/database/direct-connections#how-to-connect-to-prisma-postgres-via-direct-tcp):
+We're going to use a direct connection string for connecting to Prisma Postgres. To get it, follow [Connecting to your database](/postgres/database/connecting-to-your-database):
 
 1. Navigate to your recently created Prisma Postgres project dashboard (e.g. "My Bun Project")
 2. Click the **Connection Strings** tab in the project's sidebar

apps/docs/content/docs/guides/runtimes/deno.mdx

@@ -112,7 +112,7 @@ export default defineConfig({
 
 ### 2.3. Configure environment variables for direct connection
 
-We're going to use a direct connection string for connecting to Prisma Postgres. To get your [direct connection string](/postgres/database/direct-connections#how-to-connect-to-prisma-postgres-via-direct-tcp):
+We're going to use a direct connection string for connecting to Prisma Postgres. To get it, follow [Connecting to your database](/postgres/database/connecting-to-your-database):
 
 1. Navigate to your recently created Prisma Postgres project dashboard (e.g. "My Deno Project")
 2. Click the **Connection Strings** tab in the project's sidebar

apps/docs/content/docs/guides/switch-to-prisma-postgres/from-neon.mdx

@@ -74,7 +74,7 @@ pg_dump \
 
 ## 3. Import data into Prisma Postgres
 
-Export your [direct connection string](/postgres/database/direct-connections) from step 1 as an environment variable:
+Export your [direct connection string](/postgres/database/connecting-to-your-database) from step 1 as an environment variable:
 
 ```bash
 export PRISMA_POSTGRES_DATABASE_URL='postgres://...'

apps/docs/content/docs/guides/switch-to-prisma-postgres/from-supabase.mdx

@@ -74,7 +74,7 @@ pg_dump \
 
 ## 3. Import data into Prisma Postgres
 
-Export your [direct connection string](/postgres/database/direct-connections) from step 1 as an environment variable:
+Export your [direct connection string](/postgres/database/connecting-to-your-database) from step 1 as an environment variable:
 
 ```bash
 export PRISMA_POSTGRES_DATABASE_URL='postgres://...'

apps/docs/content/docs/postgres/database/backups.mdx

@@ -28,7 +28,7 @@ In the future, Prisma Postgres will provide more fine-grained backup mechanisms
 
 ## Manually creating a backup file via `pg_dump`
 
-If you would like to create a backup file of your database, you can use `pg_dump` and use a [direct connection](/postgres/database/direct-connections). This is useful for migrating data between databases or creating a local copy of your database.
+If you would like to create a backup file of your database, you can use `pg_dump` with a [direct connection](/postgres/database/connecting-to-your-database). This is useful for migrating data between databases or creating a local copy of your database.
 
 ## Prerequisites
 
@@ -69,7 +69,7 @@ If you installed PostgreSQL but still see a “command not found” error for `p
 
 ### 2. Creating the Backup with `pg_dump`
 
-Get your direct connection string for Prisma Postgres by following the instructions [here](/postgres/database/direct-connections#how-to-connect-to-prisma-postgres-via-direct-tcp).
+Get your direct connection string by following [Connecting to your database](/postgres/database/connecting-to-your-database).
 
 You can now dump the database by running the following command and using your own connection string:
 

apps/docs/content/docs/postgres/database/connecting-to-your-database.mdx

@@ -0,0 +1,149 @@
+---
+title: Connecting to your database
+description: Choose the right Prisma Postgres connection string for your runtime, tool, and workload.
+url: /postgres/database/connecting-to-your-database
+metaTitle: Connecting to your Prisma Postgres database
+metaDescription: Learn where to get Prisma Postgres connection strings, when to use pooled or direct connections, and how to debug connection issues.
+---
+
+Every Prisma Postgres database has two connection strings: **pooled** for application traffic, **direct** for migrations and admin tooling. This page covers how to get them, where each one goes, and the recommended setup for common runtimes.
+
+For pooling behavior, limits, and timeouts, see [Connection pooling](/postgres/database/connection-pooling).
+
+## Get your connection strings
+
+1. Open your project in the [Prisma Console](https://console.prisma.io).
+1. Select your database.
+1. Click **Connect to your database**.
+1. Click **Generate new connection string**.
+1. Copy both the **pooled** and **direct** connection strings.
+
+![Animated walkthrough of generating a connection string in Prisma Console: navigating to the database, clicking Connect, generating a new connection string, and copying the result.](/img/postgres/connection-string.gif)
+
+## Connection string format
+
+Both strings share the same credentials. The only difference is the hostname:
+
+```bash title=".env"
+# Pooled — routes through the connection pooler
+DATABASE_URL="postgres://USER:PASSWORD@pooled.db.prisma.io:5432/?sslmode=require"
+
+# Direct — connects straight to the database
+DIRECT_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require"
+```
+
+| Part       | Description                                               |
+| ---------- | --------------------------------------------------------- |
+| `USER`     | Database user (generated in Console)                      |
+| `PASSWORD` | Database password (generated in Console)                  |
+| Host       | `pooled.db.prisma.io` (pooled) or `db.prisma.io` (direct) |
+| Port       | `5432`                                                    |
+| `sslmode`  | Always `require` - SSL is mandatory                       |
+
+## Which connection to use
+
+| If you are...                                                    | Use        | Why                                                                  |
+| ---------------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
+| Running application queries (API handlers, workers, functions)   | **Pooled** | Safer under concurrency. Reuses a small set of database connections. |
+| Running migrations, introspection, `pg_dump`, `pg_restore`, Prisma Studio, or admin tooling | **Direct** | These workflows need session continuity or should bypass the pooler. |
+| Using `LISTEN/NOTIFY` or session-level `SET` commands            | **Direct** | The pooler does not preserve session state across transactions.      |
+| Running queries or jobs that may exceed 10 minutes               | **Direct** | Pooled connections enforce a 10-minute query timeout.                |
+
+If you swap them, the failure modes are asymmetric. Using the pooled string for migrations produces obvious errors (lock failures, prepared statement errors). Using the direct string for application traffic works at low concurrency but silently exhausts connections under production load. See [Connection pooling](/postgres/database/connection-pooling) for details.
+
+## Recommended setups
+
+### Prisma ORM in Node.js
+
+Set `DATABASE_URL` to the pooled string for runtime queries. Set `DIRECT_URL` to the direct string so the Prisma CLI (migrations, introspection, Studio) bypasses the pooler.
+
+```bash title=".env"
+DATABASE_URL="postgres://USER:PASSWORD@pooled.db.prisma.io:5432/postgres?sslmode=require"
+DIRECT_URL="postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require"
+```
+
+```ts title="prisma.config.ts"
+import "dotenv/config";
+import { defineConfig, env } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  datasource: {
+    url: env("DIRECT_URL"),
+  },
+});
+```
+
+```ts title="src/db.ts"
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "./generated/prisma/client";
+
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
+
+export const prisma = new PrismaClient({ adapter });
+```
+
+This gives you pooled runtime traffic for application queries and direct CLI access for migrations, introspection, and schema changes.
+
+### Serverless and edge runtimes
+
+For serverless runtimes that support PostgreSQL over TCP, use the same setup as above but wrap the client in a singleton. Without this, each warm invocation creates a new client and a new connection, making it easy to exhaust your plan's pooled connection limit.
+
+```ts title="src/db.ts"
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "./generated/prisma/client";
+
+const globalForPrisma = globalThis as unknown as {
+  prisma?: PrismaClient;
+};
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    adapter: new PrismaPg({
+      connectionString: process.env.DATABASE_URL,
+    }),
+  });
+
+if (process.env.NODE_ENV !== "production") {
+  globalForPrisma.prisma = prisma;
+}
+```
+
+**When TCP is not a good fit:** If your runtime is short-lived, globally distributed, or does not support PostgreSQL TCP connections well, use the [serverless driver (`@prisma/ppg`)](/postgres/database/serverless-driver) instead. It communicates over HTTP and WebSockets rather than TCP and has built in connection pooling. See the [serverless driver docs](/postgres/database/serverless-driver) for setup.
+
+<CalloutContainer type="info">
+  <CalloutDescription>
+    The serverless driver uses the **direct** connection string but does **not** open a TCP connection to the database. The direct hostname is used for routing only, the transport is HTTP/WebSocket, not PostgreSQL wire protocol.
+  </CalloutDescription>
+</CalloutContainer>
+
+### PostgreSQL tools and other ORMs
+
+Use the **direct** connection string with `psql`, `pg_dump`, `pg_restore`, and GUI tools (TablePlus, DataGrip, DBeaver, Postico):
+
+```bash
+psql "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require"
+```
+
+For non-Prisma ORMs, see the getting-started guides for [Drizzle](/prisma-postgres/quickstart/drizzle-orm), [Kysely](/prisma-postgres/quickstart/kysely), or [TypeORM](/prisma-postgres/quickstart/typeorm).
+
+## Troubleshooting
+
+### Migrations or db push fail with lock or prepared statement errors
+
+The pooled connection string is being used where the direct string is required. Check that `prisma.config.ts` points at `DIRECT_URL` (`db.prisma.io`), not `DATABASE_URL`.
+
+### "Too many connections"
+
+Your application is exceeding the connection limit for your plan. See the [Connection pooling troubleshooting](/postgres/database/connection-pooling#too-many-connections-or-connection-limit-errors) for specific causes and fixes.
+
+### Connection refused or timeout on first connect
+
+Check that your connection string includes `sslmode=require` and uses port `5432`. If you are behind a corporate firewall or VPN that blocks outbound PostgreSQL traffic, you may need to allowlist `*.db.prisma.io` on port 5432, or use the [serverless driver](/postgres/database/serverless-driver) which operates over HTTPS.
+
+## Related pages
+
+- [Connection pooling](/postgres/database/connection-pooling)
+- [Serverless driver](/postgres/database/serverless-driver)
+- [Backups](/postgres/database/backups)