Pre-built prompt for connecting Node/TypeScript applications to Neon using Prisma ORM. Prisma is an open-source, next-generation ORM for Node.js and TypeScript. This guide shows you how to connect a Prisma application to Neon using the recommended setup with the Neon serverless driver adapter. ## Prerequisites - A [Neon account and project](/guides/neon-docs-get-started-signing-up) - Node.js 18+ installed - A Node.js or TypeScript project (or create a new one) ## Setup ### Step 1: Install dependencies ```bash npm install @prisma/client @prisma/adapter-neon dotenv npm install prisma tsx --save-dev ``` ### Step 2: Get your connection strings From your Neon Console, click **Connect** and copy both connection strings: - **Pooled connection** (has `-pooler` in the hostname): for your application - **Direct (unpooled) connection**: for Prisma CLI commands (migrations, introspection) Add them to your `.env` file: ```ini # Pooled connection for your application DATABASE_URL="postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=require" # Direct (unpooled) connection for Prisma CLI DATABASE_URL_UNPOOLED="postgresql://[user]:[password]@[endpoint].[region].aws.neon.tech/[dbname]?sslmode=require" ``` :::callout{intent="tip"} The pooled connection has `-pooler` in the hostname. The direct (unpooled) connection does not. Both are available in your Neon Console. ::: ### Step 3: Configure your Prisma schema If you don't have a Prisma schema yet, run `npx prisma init` to create one. Then update `prisma/schema.prisma`: ```prisma generator client { provider = "prisma-client-js" output = "../src/generated/prisma" } datasource db { provider = "postgresql" } model User { id Int @id @default(autoincrement()) email String @unique name String? createdAt DateTime @default(now()) } ``` :::callout{intent="note"} In Prisma 7+, do not include a `url` property in the datasource block. The connection is configured via `prisma.config.ts` and the adapter. ::: ### Step 4: Create prisma.config.ts Create a `prisma.config.ts` file in your project root. This tells Prisma CLI where to connect for migrations and other commands: ```typescript import 'dotenv/config' import { defineConfig, env } from 'prisma/config' export default defineConfig({ schema: 'prisma/schema.prisma', datasource: { url: env('DATABASE_URL_UNPOOLED'), }, }) ``` ### Step 5: Create your Prisma Client Create a file to instantiate Prisma Client with the Neon adapter (for example, `src/db.ts`): ```typescript import 'dotenv/config' import { PrismaClient } from './generated/prisma' import { PrismaNeon } from '@prisma/adapter-neon' const adapter = new PrismaNeon({ connectionString: process.env.DATABASE_URL!, }) export const prisma = new PrismaClient({ adapter }) ``` ### Step 6: Generate client and push schema ```bash npx prisma generate npx prisma db push ``` You're connected. You can now use Prisma Client in your application: ```typescript import { prisma } from './db' const users = await prisma.user.findMany() ``` To verify the full setup, create a `src/main.ts` script that exercises CRUD operations: ```typescript import { prisma } from './db' async function main() { // CREATE const newUser = await prisma.user.create({ data: { name: 'Alice', email: `alice-${Date.now()}@example.com` }, }) console.log('Created user:', newUser) // READ const foundUser = await prisma.user.findUnique({ where: { id: newUser.id } }) console.log('Found user:', foundUser) // UPDATE const updatedUser = await prisma.user.update({ where: { id: newUser.id }, data: { name: 'Alice Smith' }, }) console.log('Updated user:', updatedUser) // DELETE await prisma.user.delete({ where: { id: newUser.id } }) console.log('Deleted user.') } main() .catch((error) => { console.error(error) process.exit(1) }) .finally(async () => { await prisma.$disconnect() }) ``` Run it with: ```bash npx tsx src/main.ts ``` ## Why two connection strings? Neon uses connection pooling to efficiently manage database connections in serverless environments: - **Pooled connection (`DATABASE_URL`)**: Your application connects through Neon's connection pooler, which is optimal for serverless functions that create many short-lived connections. - **Direct (unpooled) connection (`DATABASE_URL_UNPOOLED`)**: Prisma CLI commands like `prisma migrate` and `prisma db push` need a direct connection for schema operations. ## Advanced configuration ### Using a non-public PostgreSQL schema If you're using a PostgreSQL schema other than `public`, pass a `schema` option when creating the adapter: ```typescript const adapter = new PrismaNeon( { connectionString: process.env.DATABASE_URL! }, { schema: 'myPostgresSchema' } ) ``` ### Setting the search path for raw SQL queries For raw SQL queries that reference tables without schema qualification, use PostgreSQL's `options` parameter in your connection string: ``` postgresql://[user]:[password]@[neon_hostname]/[dbname]?options=-c%20search_path%3Dmyschemaname ``` ## Troubleshooting :::accordion{title="Connection timeouts"} If you see an error like: ``` Error: P1001: Can't reach database server at `ep-example-123456.us-east-2.aws.neon.tech`:`5432` ``` This usually means the Prisma query engine timed out before Neon activated the compute. Neon computes scale to zero after inactivity and take a few seconds to wake up. Add a `connect_timeout` parameter to your connection string: ``` DATABASE_URL="postgresql://...?sslmode=require&connect_timeout=15" ``` A value of `0` means no timeout. ::: :::accordion{title="Connection pool timeouts"} Prisma maintains its own connection pool. If you're seeing pool-related timeouts, you can configure: - `connection_limit`: Number of connections in the pool (default: `num_cpus * 2 + 1`) - `pool_timeout`: Seconds to wait for a connection from the pool (default: 10) ``` DATABASE_URL="postgresql://...?sslmode=require&connection_limit=20&pool_timeout=15" ``` See Prisma's [connection management guide](https://www.prisma.io/docs/guides/performance-and-optimization/connection-management) for details. ::: :::accordion{title="Using Prisma 6 or earlier"} In Prisma 6 and earlier, you configure the connection directly in `schema.prisma` instead of `prisma.config.ts`: ```prisma datasource db { provider = "postgresql" url = env("DATABASE_URL") directUrl = env("DATABASE_URL_UNPOOLED") } ``` The `directUrl` property is available in Prisma 4.10.0 and higher. ::: ## Next steps - [Schema migrations with Prisma](/guides/integrations-tooling-guides-prisma-migrations): Full tutorial for building an app with migrations - [Neon serverless driver](/guides/postgres-serverless-serverless-driver): Learn more about the driver powering the adapter ## Next steps: Neon backend services - [Set up Managed Better Auth](/guides/auth-index): Add managed authentication that branches with your database - [Add Object Storage](/guides/object-storage-index): S3-compatible file storage that branches with your database - [Deploy a Function](/guides/neon-functions-index): Run backend compute next to your database, no separate hosting needed - [Call an LLM with AI Gateway](/guides/ai-gateway-index): Access foundation models from Anthropic, OpenAI, Google, and more with one credential ## Resources - [Prisma documentation](https://www.prisma.io/docs/) - [Prisma connection management](https://www.prisma.io/docs/guides/performance-and-optimization/connection-management) - [PostgreSQL connector reference](https://www.prisma.io/docs/concepts/database-connectors/postgresql) :::accordion{title="Notes for AI-assisted setup"} * Import `PrismaClient` from `./generated/prisma` (or your configured `output` path), not from `@prisma/client`. The import path changed in Prisma 7. * Do not install `@neondatabase/serverless` or `ws` as separate packages. The `@prisma/adapter-neon` package bundles everything needed for the Neon connection. * In Prisma 7+, do not include a `url` property in the `prisma/schema.prisma` datasource block. The connection is configured via `prisma.config.ts` and the adapter. * You need both a pooled connection (`DATABASE_URL`) for your application and a direct (unpooled) connection (`DATABASE_URL_UNPOOLED`) for Prisma CLI commands. * Call `prisma.$disconnect()` in a `.finally()` block when running standalone scripts. Omitting this can leave connections open. ::: ## Need help? Join our [Discord Server](https://neon.com/discord) to ask questions or see what others are doing with Neon. For paid plan support options, see [Support](/guides/postgres-introduction-support). ## Related pages - [The Neon GitHub integration](./integrations-tooling-guides-neon-github-integration.md) - [Connect from Knex to Neon](./integrations-tooling-guides-knex.md) - [Connect from TypeORM to Neon](./integrations-tooling-guides-typeorm.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.