Skip to main content

Neon

This guide explains how to:

What is Neon?​

Neon's logo

Neon is a fully managed serverless PostgreSQL with a generous free tier. Neon separates storage and compute, and offers modern developer features such as serverless, branching, bottomless storage, and more. Neon is open source and written in Rust.

Learn more about Neon here.

Commonalities with other database providers​

Many aspects of using Prisma ORM with Neon are just like using Prisma ORM with any other PostgreSQL database. You can:

Differences to consider​

There are a few differences between Neon and PostgreSQL you should be aware of the following when deciding to use Neon with Prisma ORM:

  • Neon's serverless model — By default, Neon scales a compute to zero after 5 minutes of inactivity. During this state, a compute instance is in idle state. A characteristic of this feature is the concept of a "cold start". Activating a compute from an idle state takes from 500ms to a few seconds. Depending on how long it takes to connect to your database, your application may timeout. To learn more, see: Connection latency and timeouts.
  • Neon's connection pooler — Neon offers connection pooling using PgBouncer, enabling up to 10,000 concurrent connections. To learn more, see: Connection pooling.

How to use Neon's connection pooling​

If you'd like to use the connection pooling available in Neon, you will need to add pgbouncer=true to the end of the DATABASE_URL environment variable used in the url property of the datasource block of your Prisma schema:

.env
# Connect to Neon with PgBouncer.
DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417-pooler.us-east-2.aws.neon.tech:5432/neondb?pgbouncer=true

If you would like to use Prisma CLI in order to perform other actions on your database (e.g. for migrations) you will need to add a DIRECT_URL environment variable to use in the directUrl property of the datasource block of your Prisma schema so that the CLI will use a direct connection string (without PgBouncer):

.env
# Connect to Neon with PgBouncer.
DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417-pooler.us-east-2.aws.neon.tech/neondb?pgbouncer=true

# Direct connection to the database used by Prisma CLI for e.g. migrations.
DIRECT_URL="postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb"

You can then update your schema.prisma to use the new direct URL:

schema.prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")
}

More information about the directUrl field can be found here.

info

We strongly recommend using the pooled connection string in your DATABASE_URL environment variable. You will gain the great developer experience of the Prisma CLI while also allowing for connections to be pooled regardless of deployment strategy. While this is not strictly necessary for every app, serverless solutions will inevitably require connection pooling.

Resolving connection timeouts​

A connection timeout that occurs when connecting from Prisma ORM to Neon causes an error similar to the following:

Error: P1001: Can't reach database server at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`
Please make sure your database server is running at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`.

This error most likely means that the connection created by Prisma Client timed out before the Neon compute was activated.

A Neon compute has two main states: Active and Idle. Active means that the compute is currently running. If there is no query activity for 5 minutes, Neon places a compute into an idle state by default. Refer to Neon's docs to learn more.

When you connect to an idle compute from Prisma ORM, Neon automatically activates it. Activation typically happens within a few seconds but added latency can result in a connection timeout. To address this issue, your can adjust your Neon connection string by adding a connect_timeout parameter. This parameter defines the maximum number of seconds to wait for a new connection to be opened. The default value is 5 seconds. A higher setting should provide the time required to avoid connection timeout issues. For example:

DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb?connect_timeout=10
info

A connect_timeout setting of 0 means no timeout.

Another possible cause of connection timeouts is Prisma ORM's connection pool, which has a default timeout of 10 seconds. This is typically enough time for Neon, but if you are still experiencing connection timeouts, you can try increasing this limit (in addition to the connect_timeout setting described above) by setting the pool_timeout parameter to a higher value. For example:

DATABASE_URL=postgres://daniel:<password>@ep-mute-rain-952417.us-east-2.aws.neon.tech/neondb?connect_timeout=15&pool_timeout=15

How to use Neon's serverless driver with Prisma ORM (Preview)​

The Neon serverless driver is a low-latency Postgres driver for JavaScript and TypeScript that allows you to query data from serverless and edge environments over HTTP or WebSockets in place of TCP.

You can use Prisma ORM along with the Neon serverless driver using a driver adapter . A driver adapter allows you to use a different database driver from the default Prisma ORM provides to communicate with your database.

info

This feature is available in Preview from Prisma ORM versions 5.4.2 and later.

To get started, enable the driverAdapters Preview feature flag:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Generate Prisma Client:

npx prisma generate

Install the Prisma ORM adapter for Neon, Neon serverless driver and ws packages:

npm install @prisma/adapter-neon @neondatabase/serverless ws
npm install --save-dev @types/ws

Update your Prisma Client instance:

import { Pool, neonConfig } from '@neondatabase/serverless'
import { PrismaNeon } from '@prisma/adapter-neon'
import { PrismaClient } from '@prisma/client'
import dotenv from 'dotenv'
import ws from 'ws'

dotenv.config()
neonConfig.webSocketConstructor = ws
const connectionString = `${process.env.DATABASE_URL}`

const pool = new Pool({ connectionString })
const adapter = new PrismaNeon(pool)
const prisma = new PrismaClient({ adapter })

You can then use Prisma Client as you normally would with full type-safety. Prisma Migrate, introspection, and Prisma Studio will continue working as before, using the connection string defined in the Prisma schema.

Notes​

Specifying a PostgreSQL schema​

You can specify a PostgreSQL schema by passing in the schema option when instantiating PrismaNeon:

const adapter = new PrismaNeon(pool, {
  schema: 'myPostgresSchema'
})