Connecting to your database (/docs/postgres/database/connecting-to-your-database)

For the complete Prisma documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL.

Choose the right Prisma Postgres connection string for your runtime, tool, and workload.

Location: Postgres > Database > Connecting to your database

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.

1. Open your project in the Prisma Console.
2. Select your database.
3. Click Connect to your database.
4. Click Generate new connection string.
5. Copy both the pooled and direct connection strings.

Both strings share the same credentials. The only difference is the hostname:

# 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"

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 for details.

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.

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"

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: env("DIRECT_URL"),
  },
});

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.

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, which can exhaust your plan's pooled connection limit.

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) instead. It communicates over HTTP and WebSockets rather than TCP and has built in connection pooling. See the serverless driver docs for setup.

[!NOTE] 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.

Use the direct connection string with psql, pg_dump, pg_restore, and GUI tools (TablePlus, DataGrip, DBeaver, Postico):

psql "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require"

For non-Prisma ORMs, see the getting-started guides for Drizzle, Kysely, or TypeORM.

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.

Your application is exceeding the connection limit for your plan. See the Connection pooling troubleshooting for specific causes and fixes.

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 which operates over HTTPS.

• Connection pooling
• Serverless driver
• Backups

• Backups: Manage and restore database backups in Prisma Postgres
• Connect to Prisma Postgres without Accelerate: Replace a hosted Prisma Postgres Accelerate connection without moving your database or data
• Connection pooling: Use Prisma Postgres connection pooling for concurrent application traffic.
• Extensions: Enable and use standard PostgreSQL extensions with Prisma Postgres.
• Query Insights: Inspect slow queries, connect Prisma calls to SQL, and apply focused fixes with Prisma Postgres.