Connect from Prisma to Neon

Prisma is an open-source, next-generation ORM that enables you to manage and interact with your database. This guide explains how to connect Prisma to Neon, establish connections when using Prisma Client in serverless functions, and resolve connection timeout issues.

To configure Prisma Migrate with Neon, see Use Prisma Migrate with Neon.

Prerequisites

• A Neon project. See Create a project.
• A Prisma project. See Set up Prisma, in the Prisma documentation.

Connect to Neon from Prisma

To establish a basic connection from Prisma to Neon, perform the following steps:

1. Retrieve your Neon connection string. In the Connection Details widget on the Neon Dashboard, select a branch, a user, and the database you want to connect to. A connection string is constructed for you. The connection string includes the user name, password, hostname, and database name.

2. 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")
   }

3. Add a DATABASE_URL variable to your .env file and set it to the Neon connection string that you copied in the previous step. Your setting will appear similar to the following:

   DATABASE_URL="postgres://daniel:<password>@ep-restless-rice-862380.us-east-2.aws.neon.tech/neondb"

If you are using Prisma Client from a serverless function, see Connect from serverless functions. To adjust your connection string to avoid connection timeouts issues, see Connection timeouts.

Connect from serverless functions

Serverless functions typically require a large number of database connections. When connecting from Prisma Client to Neon from a serverless function, you should use a pooled connection string. Neon uses the PgBouncer connection pooler, which maintains a pool of connections to the database, allowing Neon to support a large number of concurrent connections.

To use a pooled connection from Prisma, adjust your Neon connection string by adding a -pooler suffix to the endpoint ID and appending the ?pgbouncer=true flag to the connection string, as shown:

DATABASE_URL=postgres://daniel:<password>@ep-restless-rice-862380-pooler.us-east-2.aws.neon.tech/neondb?pgbouncer=true

The -pooler suffix tells Neon to use a pooled connection to the database rather than a direct connection. The ?pgbouncer=true flag requires that the connection uses PgBouncer.

For more information about PgBouncer and pooled connection strings, see Enable connection pooling. For related information in the Prisma documentation, refer to the Add pgbouncer to the connection URL.

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 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. For more information, see Compute lifecycle.

When you connect to an idle compute 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, your can adjust your Neon connection string as follows:

• Add a connect_timeout parameter and set it to 0 or a higher value. This parameter 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:

  DATABASE_URL=postgres://daniel:<password>@ep-restless-rice-862380-pooler.us-east-2.aws.neon.tech/neondb?connect_timeout=10

• If using a pooled connection, 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:

  DATABASE_URL=postgres://daniel:<password>@ep-restless-rice-862380-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.