Prisma Connection String with PgBouncer

Two connection strings are required: one through PgBouncer for application queries, one direct to PostgreSQL for migrations. Prisma's migration engine uses advisory locks, which require session mode. Running migrations through PgBouncer in transaction mode will cause the migration to hang indefinitely.

The ?pgbouncer=true query parameter is the Prisma-specific signal to disable persistent prepared statements. Without it, Prisma sends PREPARE statements that reference server-side prepared statement names — names that won't exist on the next server connection PgBouncer assigns.

For deployment, run migrations using prisma migrate deploy which uses directUrl automatically. On Vercel, run migrations as a build step or as a separate migration job — never via the pooled URL.

Where to Run PgBouncer

For AWS workloads, RDS Proxy is AWS's managed PgBouncer equivalent. It handles the operational overhead (HA, failover, IAM auth) at the cost of added latency (~1–2ms) and per-connection pricing. For teams who don't want to operate PgBouncer themselves, RDS Proxy is reasonable.

For self-managed infrastructure: run PgBouncer as a sidecar container in the same Kubernetes pod as your application, or as a shared deployment in your VPC. Running it as a sidecar means it's local (sub-millisecond latency) but you have one PgBouncer per pod rather than one shared PgBouncer. The math changes: 10 pods × 20 PgBouncer server connections = 200 PostgreSQL connections. Still bounded, still predictable — just multiply default_pool_size by pod count.

---

Solution 2 — Neon Serverless Driver

PgBouncer is infrastructure you have to operate. For teams using Neon (serverless PostgreSQL) or who want to avoid the operational overhead, the Neon serverless driver takes a different approach: eliminate persistent TCP connections entirely.

The Architecture

The @neondatabase/serverless package provides two transports:

HTTP mode: Each query is a single HTTP POST request to Neon's API endpoint. No TCP connection is established. The query goes out as an HTTP request, the result comes back as an HTTP response, and that's it. No connection state, no pool, nothing to manage. Neon handles connection management on its end.

WebSocket mode: A WebSocket is established, used for one or more queries, and torn down. The connection lifecycle is ~1ms. From PostgreSQL's perspective, these appear as short-lived connections that don't linger.

Neither mode maintains a persistent pool on the application side. You cannot exhaust PostgreSQL's connection limit because you don't hold connections between queries.

This is architecturally different from PgBouncer. PgBouncer is a proxy that manages connections on your behalf. The Neon driver doesn't use persistent connections at all.

Using the Neon Driver with Drizzle

For Drizzle ORM, which integrates cleanly with the Neon HTTP driver:

Each call to db.select() (or any query method) goes out as an HTTP request. No pool, no persistent state.

Using the Neon Driver with Prisma

Prisma's driver adapter system lets you swap the underlying transport while keeping the Prisma ORM API:

With the Neon adapter, Prisma uses HTTP under the hood instead of TCP. The PrismaClient still needs to be instantiated (and the global singleton pattern still prevents multiple instances during HMR), but its underlying connections are stateless HTTP requests rather than pooled TCP sockets.

The Trade-Off: Latency vs Connection Safety

HTTP-based queries have measurable overhead versus a persistent TCP connection. In round numbers:

• Persistent TCP connection (direct or via PgBouncer): query latency ≈ network RTT to database + query execution time
• HTTP query (Neon driver): query latency ≈ network RTT to Neon's edge + query execution time + HTTP overhead (~10–30ms additional)

For applications making 1–3 database calls per request, this overhead is acceptable — it's on the order of the variance you'd see from query plan changes. For applications making 10+ database queries per request path (usually a sign of an N+1 problem worth fixing anyway), the HTTP overhead becomes noticeable.

The Neon driver also works in Edge Runtime — Vercel's Middleware environment and Edge Functions. Prisma's standard Node.js driver does not. If you need to query your database from Middleware (generally a code smell, but occasionally necessary), the Neon HTTP driver is one of very few options.

---

Solution 3 — Prisma Accelerate

Prisma Accelerate is Prisma's managed connection pooler plus edge caching service. It occupies the same architectural position as PgBouncer — it's a proxy between your application and PostgreSQL — but it's fully managed and adds query-level caching as a first-class feature.

How It Works

Your application connects to prisma://accelerate.prisma.io/ rather than directly to your PostgreSQL host. Accelerate handles:

1. Connection pooling: Accelerate maintains a pool of real PostgreSQL connections. Your application connects to Accelerate, which multiplexes those connections to your database. Identical behavior to PgBouncer from the application's perspective.
2. Query caching: Optionally, you can specify a TTL per query. Accelerate caches the result and serves it without touching the database on subsequent identical queries within the TTL window.
3. Global edge network: Accelerate runs on Prisma's edge network, meaning the proxy hop is geographically close to your users (if you're using edge functions) or to your serverless region.

Setup

The connection string format changes:

You still need a DIRECT_URL pointing at your actual PostgreSQL instance for migrations:

Query-Level Caching

This is the feature that distinguishes Accelerate from a plain connection pooler. Per-query cache control with TTL and stale-while-revalidate semantics:

The swr (stale-while-revalidate) parameter mirrors the HTTP cache-control pattern: serve the cached response immediately, kick off a background revalidation if the TTL has expired but the SWR window hasn't. Users get fast responses; the cache stays fresh eventually.

Cache invalidation by tag:

The Trade-Offs

Accelerate's connection pooling works. The caching layer is genuinely useful for read-heavy endpoints that can tolerate eventual consistency. The trade-offs are real:

Vendor dependency: Your database connectivity now depends on Prisma's infrastructure uptime. If Accelerate has an outage, your application loses database access even if your PostgreSQL instance is healthy. Evaluate whether this risk profile is acceptable for your workload.

Added latency hop: Every query goes through Accelerate's infrastructure before reaching your database. Prisma claims this is typically sub-5ms for co-located infrastructure, but it's a network hop you don't have with direct PgBouncer.

Pricing: Accelerate is a paid service beyond the free tier. Model the cost against your query volume before committing.

For teams already invested in the Prisma ecosystem and who want connection pooling and edge caching without operational overhead, Accelerate is a pragmatic choice. For teams who need full control, want to minimize external dependencies, or are running on self-managed infrastructure, PgBouncer is the more durable solution.

---

Solution 4 — Supabase Connection Pooler (Supavisor)

If you're using Supabase-hosted PostgreSQL, you have a managed connection pooler included without additional infrastructure: Supavisor.

Supabase replaced PgBouncer with Supavisor (a native Elixir pooler) in 2024. The behavior is similar to PgBouncer in transaction mode with some Supabase-specific enhancements (multi-tenant pooling, PostgreSQL parameter pass-through for row-level security).

Connection String Difference

Supabase provides two ports for every project:

• Port 5432 — direct PostgreSQL connection, no pooling. Use this only for migrations, not for application queries in serverless.
• Port 6543 — Supavisor pooled connection, transaction mode. Use this for all application queries in serverless and high-concurrency deployments.

The hostname and credentials are the same — only the port differs. This is the only configuration change required; everything else (Prisma schema, singleton pattern, query code) stays identical.

One Supabase-specific note: if you're using Row Level Security (RLS) with SET role or SET app.current_user, be aware that Supavisor in transaction mode has the same session-variable restrictions as PgBouncer transaction mode. Supabase has workarounds using connection string parameters for JWT passing — check the current Supabase docs for the specific RLS pattern if you need it, as this evolves faster than I want to hard-code here.

---

The Global Singleton Pattern for Non-Serverless

Everything above covers serverless. For always-on deployments — Kubernetes, Fly.io, Railway, a bare VM — the calculus is different.

In a traditional deployment, you have a fixed, known number of processes. Each process should have exactly one PrismaClient with a pool sized to its share of max_connections. The problem to avoid is not concurrency across hundreds of Lambda instances — it's the Next.js development server creating a new PrismaClient instance on every file change via hot module replacement.

Why HMR Kills Development Connections

Next.js's development server uses HMR to reload changed modules without restarting the entire server. When lib/prisma.ts (or any module it imports) changes, Node.js re-evaluates the module. Without special handling, this creates a new PrismaClient instance each time — complete with a new connection pool — while the old instance sits unreachable, its connections held open until they time out. Do this 50 times in a dev session and you've got 50 × 5 = 250 connections sitting idle.

The Correct Singleton Pattern

The mechanism: globalThis is not subject to HMR. Module-level variables are — they get reset on every hot reload. But globalThis persists for the lifetime of the Node.js process. The first time this module is evaluated, globalForPrisma.prisma is undefined, a new PrismaClient is created, and it's stored on globalThis. Every subsequent evaluation (every hot reload) finds the existing instance on globalThis and returns it.

The if (process.env.NODE_ENV !== 'production') guard is deliberate. In production, the module is evaluated once at startup and never again — storing on globalThis is unnecessary. The guard prevents the pattern from adding any overhead or confusion in production environments.

This is the only correct pattern for non-serverless Next.js. Variations that use module-level variables without the globalThis trick will leak connections in development. Patterns that create a new PrismaClient on every import (including the new PrismaClient() inside a Server Component) will exhaust connections in any environment.

Add import 'server-only' to lib/prisma.ts to make the build fail loudly if this module is ever imported in a Client Component:

Explicitly Disconnecting on Process Shutdown

In non-serverless environments, add a process shutdown handler to ensure Prisma closes its connections cleanly. Without this, a SIGTERM during a Kubernetes rolling deploy will leave connections dangling until PostgreSQL's idle timeout clears them:

---

Monitoring: How to Know You're Exhausting Connections

The time to know about connection exhaustion is not when users see 500s. It's an hour before that, when connection count starts trending toward the limit. Here are the queries to run:

The idle in transaction state is worth calling out specifically. A connection in this state is inside a transaction that hasn't committed or rolled back — usually because the application code started a transaction, hit an error, and didn't properly ROLLBACK. These connections hold locks. They block other transactions. They are often the root cause of cascading slowdowns that look like a connection exhaustion problem but are actually a lock contention problem.

If you see a high count of idle in transaction connections, look for:

• Unhandled exceptions inside Prisma $transaction() blocks
• Long-running background processes that open transactions and take time between statements
• Application code that manually starts transactions (BEGIN) but doesn't always commit or roll back

What to Alert On

Minimum viable alerting against pg_stat_activity:

• Warning: count(*) > max_connections * 0.7 — at 70% of your connection limit, something is trending wrong
• Critical: count(*) > max_connections * 0.85 — at 85%, start paging; you're 90 seconds from user-visible errors
• Emergency: count(*) WHERE state = 'idle in transaction' > 10 — investigate immediately; these connections are holding locks
• Latency signal: count(*) WHERE wait_event_type IS NOT NULL > 20 — connections are waiting; throughput is being throttled

A Datadog monitor on the RDS DatabaseConnections metric is simpler than polling pg_stat_activity and sufficient for most teams. Add an alert threshold at 70% and 90% of max_connections. On Supabase, the dashboard shows connection count by default.

For teams running self-managed PostgreSQL, pg_stat_activity polling via a simple cron job or Prometheus exporter (postgres_exporter is the standard tool) gives you the visibility you need before it becomes a production incident.

---

The Decision Matrix

Mapping your infrastructure to the right pooling strategy. Do not use direct connections to PostgreSQL in serverless. Do not add PgBouncer overhead to always-on servers that don't need it.

The "never" in the Vercel row is worth reinforcing: Vercel Functions are serverless, full stop. The global singleton pattern does not help you there. Every engineer who has shipped a Vercel application with a direct PostgreSQL connection and a Prisma singleton is running on borrowed time. They haven't hit the connection limit because they haven't hit enough concurrent traffic. The fix is not expensive or complicated — it's one of the solutions above. Do it before you're on call during a traffic spike.

---

The pool_size Formula

For always-on deployments where you're tuning the application-level pool rather than relying on a proxy, here is the actual math.

The constraint: Total connections across all running instances must not exceed max_connections - superuser_reserved. PostgreSQL's default is 100 total, 3 reserved for superuser, so 97 available for applications. In practice, add a safety buffer — don't run at 97.

The formula:

pool_size_per_instance = floor(max_connections / num_instances) - safety_buffer

Example: 100 max_connections, 10 Kubernetes pods, safety buffer of 5 (for monitoring tools, migration runners, manual psql connections):

pool_size = floor(100 / 10) - 5 = 10 - 5 = 5

Each pod runs a PrismaClient with connection_limit=5. Ten pods × 5 connections = 50 total. You have 47 headroom before hitting the limit (the other 50 are your buffer and superuser slots).

Setting connection_limit in Prisma:

Via the connection string:

Via PrismaClient constructor (for dynamic configuration):

Pass PG_MAX_CONNECTIONS and NUM_INSTANCES as environment variables per deployment environment. Your staging environment with 2 pods and a shared dev database uses different values than production with 10 pods and a dedicated RDS instance.

Adjusting for deployment scale changes: If you scale from 10 to 20 pods, halve the connection_limit per pod before the scale-out happens (or set it based on the maximum expected pod count, not current). If you increase PostgreSQL's max_connections (which requires a database restart on most managed services), recalculate and update the connection strings.

The pool_timeout consideration: Prisma's default pool timeout is 10 seconds — if a query waits more than 10 seconds for a connection from the pool to become available, Prisma throws PrismaClientKnownRequestError with code P2024 (pool timeout). Under high concurrency with a small pool, you'll see this before you see PostgreSQL-level connection rejection. Increase pool_timeout in the connection string if you're comfortable with queries waiting longer:

Longer timeout buys more buffering at the cost of slower failure detection. A pool timeout error returned to the client is better than a 500 — at minimum it's a recoverable error with a meaningful message rather than a raw connection failure.

---

Bringing It Together: The Configuration Checklist

Before shipping a Next.js application with a database:

For Vercel/serverless:

• DATABASE_URL points to a connection pooler (PgBouncer, Neon, Accelerate, Supavisor), not directly to PostgreSQL
• DIRECT_URL exists and points directly to PostgreSQL for migrations
• prisma/schema.prisma has both url = env("DATABASE_URL") and directUrl = env("DIRECT_URL")
• If using PgBouncer: ?pgbouncer=true is in DATABASE_URL
• Migration command (prisma migrate deploy) runs against DIRECT_URL
• Alert configured when connection count exceeds 70% of max_connections

For always-on (K8s/Railway/Fly.io):

• lib/prisma.ts uses the globalThis singleton pattern with import 'server-only'
• connection_limit per pod is set to floor(max_connections / num_pods) - buffer
• Graceful shutdown handler calls prisma.$disconnect() on beforeExit
• Alert configured when connection count exceeds 70% of max_connections

For both:

• new PrismaClient() is never called outside lib/prisma.ts
• lib/prisma.ts is never imported in a Client Component
• pg_stat_activity (or the managed service equivalent) is in your monitoring dashboard

The ProductHunt story at the top of this module didn't have to happen. The fix is one connection string change and a pooler config. The teams who get burned are the ones who read "use a singleton" in a tutorial, ship it, and don't revisit until the 3am alert fires.

Don't be that team.

---

Where We Go From Here

P-16 is the final module in the Practitioner phase's database track. The Architect phase begins with A-1 — React Server Components at the protocol level. Understanding the React Flight wire format explains why Server Components cannot import PrismaClient directly, why serialization boundaries exist, and how Next.js decides what runs where. The connection pooling rules you've internalized here make full sense once you understand the process topology RSC imposes.

---