Prisma + Neon: pooled URL for the app, direct URL for the CLI

Prisma + Neon: two connection strings, each with its job

The trap

Agents set a single DATABASE_URL and use it everywhere. Point Prisma CLI (migrate, db push, introspection) at the pooled string and migrations misbehave under PgBouncer transaction mode. Point the app at the direct string and every serverless instance eats a real Postgres connection until max_connections is gone.

The rule (current docs)

From the Neon Console, copy both strings:

• Pooled (hostname has -pooler): the application's runtime connection.
• Direct (no -pooler): Prisma CLI commands.

Prisma 7+ (prisma.config.ts):

import { defineConfig, env } from 'prisma/config';
export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: { url: env('DATABASE_URL_UNPOOLED') },
});

The Prisma Client itself gets the pooled string through the Neon adapter:

import { PrismaNeon } from '@prisma/adapter-neon';
const adapter = new PrismaNeon({ connectionString: process.env.DATABASE_URL });

Prisma 6 and earlier: url = env("DATABASE_URL") plus directUrl = env("DATABASE_URL_UNPOOLED") in the datasource block (directUrl exists since 4.10).

Checklist

• DATABASE_URL = pooled, DATABASE_URL_UNPOOLED = direct. Both set, everywhere you deploy.
• In Prisma 7, do not put a url in the schema datasource block; the CLI reads prisma.config.ts.
• prisma migrate deploy in CI uses the direct string. If CI only has the pooled one, add the direct one.
• Import PrismaClient from your generated path (./generated/prisma), not @prisma/client, on Prisma 7.