Connect from Prisma to Neon

Prisma is an open-source, next-generation ORM that allows you to manage and interact with your database. This guide describes how to connect from Prisma to Neon.

Create a Neon project

If you do not have one already, create a Neon project. Save your connection string. It is required when defining connection settings.

1. Navigate to the Projects page in the Neon Console.
2. Click New Project.
3. Specify your project settings and click Create Project.

Connect to Neon from Prisma

To connect to Neon from Prisma:

1. Add the following lines to your prisma/schema.prisma file to identify the data source and database URL:

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

2. Add a DATABASE_URL setting to your .env file and set it to the Neon connection string that you copied in the previous step.

   DATABASE_URL="postgres://<user>:<password>@<host>:5432/neondb"

   where:

   • <host> the hostname of the Neon compute endpoint. The hostname has an ep- prefix and appears similar to this: ep-tight-salad-272396.us-east-2.aws.neon.tech.
   • <user> is the database user.
   • <password> is the database user's password.

You can find all of the connection details listed above in the Connection Details widget on the Neon Dashboard. For more information, see Connect from any application.

Configure a shadow database for Prisma Migrate

Prisma Migrate is a migration tool that allows you to evolve your database schema from prototyping to production. Prisma Migrate requires a shadow database to detect schema drift. This section describes how to configure a second Neon database as a shadow database, which is required to run the prisma migrate dev command.

To configure a shadow database:

1. Create another database in your Neon project and copy the connection string. Refer to Create a database for instructions. For information about obtaining a connection string, see Connect from any application.

2. Add the shadowDatabaseUrl setting to your prisma/schema.prisma file to identify the shadow database URL:

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

3. Add a SHADOW_DATABASE_URL environment variable to your .env file and set it to the Neon connection string that you copied in the previous step.

   SHADOW_DATABASE_URL="postgres://<user>:<password>@<host>:5432/<dbname>"

For more information about shadow databases, refer to About the shadow database, in the Prisma documentation.

Prisma Migrate with PgBouncer

Prisma Migrate requires a direct connection to the database. It does not support connection pooling with PgBouncer. Attempting to run Prisma Migrate commands with a pooled connection causes the following error:

Error undefined: Database error
Error querying the database: db error: ERROR: prepared statement
"s0" already exists

If you encounter this error, ensure that you are using a direct connection to the database. Neon supports both pooled and non-pooled connections to the same database. See Enable connection pooling for more information.

You can configure Prisma Migrate to use a non-pooled connection string by adding the directUrl property to the datasource block in your schema.prisma file. For example:

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

Next, update your .env file with both the DATABASE_URL and DIRECT_URL variables settings. As shown in the following example, set DATABASE_URL to the pooled connection string for your Neon database, and set DIRECT_URL to the non-pooled connection string.

DATABASE_URL="postgres://casey:<password>@ep-square-sea-260584-pooler.us-east-2.aws.neon.tech:5432/neondb?pgbouncer=true"
DIRECT_URL="postgres://casey:<password>@ep-square-sea-260584.us-east-2.aws.neon.tech:5432/neondb"

Prisma Client with PgBouncer for serverless functions

Serverless functions may require a large number of database connections. If you are using Prisma Client from a serverless function, enable connection pooling in Neon and add the ?pgbouncer=true flag to your connection URL. You can enable connection pooling in Neon for individual connections by adding a -pooler suffix to the endpoint ID, which is part of the hostname. For example:

postgres://sally:<password>@ep-square-sea-260584-pooler.us-east-2.aws.neon.tech/neondb?pgbouncer=true

For more information, see Enable connection pooling. For related information, refer to the Prisma documentation.

Connection timeouts

A connection timeout that occurs when connecting from Prisma 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 Prisma query engine timed out before the Neon compute instance was activated.

A Neon compute instance has two main states: Active and Idle. Active means that the compute instance is currently running. If there is no query activity for 5 minutes, Neon places a compute instance into an idle state. For more information, see Compute lifecycle.

When you connect to an idle compute instance from Prisma, Neon automatically activates it. Activation typically happens within a few seconds but added latency can result in a connection timeout. To address this issue, try adjusting your Neon connection string with the following parameters:

• Set connect_timeout to 0 or a higher value. This setting defines the maximum number of seconds to wait for a new connection to be opened. The default value is 5 seconds. A setting of 0 means no timeout. A higher setting should provide the time required to avoid connection timeout issues. For example:

  postgres://sally:<password>@ep-square-sea-260584-pooler.us-east-2.aws.neon.tech/neondb?connect_timeout=10

• If you are using connection pooling, set pool_timeout to 0 or a higher value. This setting defines the number of seconds to wait for a new connection from the pool. The default is 10 seconds. A setting of 0 means no timeout. A higher setting should provide the time required to avoid connection timeout issues. For example:

  postgres://sally:<password>@ep-square-sea-260584-pooler.us-east-2.aws.neon.tech/neondb?pgbouncer=true&pool_timeout=20

For additional information about connecting from Prisma, refer to the following resources in the Prisma documentation:

• Connection management
• Database connection issues
• PostgreSQL database connector
• Increasing the pool timeout

Need help?

Send a request to support@neon.tech, or join the Neon community forum.