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:

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, and add ?sslmode=require to the end of the connection string.

   Your setting will appear similar to the following:

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, use a pooled Neon connection string together with a pgbouncer=true flag, as shown:

• A pooled Neon connection string appends -pooler to the endpoint ID, which tells Neon to use a pooled connection rather than a direct connection. The Connection Details widget on the Neon Dashboard provides a Pooled connection checkbox that adds -pooler suffix to your connection string.
• Neon uses PgBouncer to provide connection pooling. Prisma requires the pgbouncer=true flag when using Prisma Client with PgBouncer, as described in the Prisma documentation.
• In summary, to use a pooled Neon connection with Prisma Client, you require a pooled Neon connection string (one that includes -pooler) and the pgbouncer=true flag, which is required by Prisma Client. See the example above.

Connection timeouts

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

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.

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 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 may provide the time required to avoid connection timeouts. For example:

Connection pool timeouts

Another possible cause of timeouts is Prisma's connection pool. The Prisma query engine manages a pool of connections. The pool is instantiated when a Prisma Client opens a first connection to the database. For an explanation of how this connection pool functions, read How the connection pool works, in the Prisma documentation.

The default size of the Prisma connection pool is determined by the following formula: num_physical_cpus * 2 + 1, where num_physical_cpus represents the number of physical CPUs on the machine where your application runs. For example, if your machine has four physical CPUs, your connection pool will contain nine connections (4 * 2 + 1 = 9). As mentioned in the Prisma documentation, this formula is a good starting point, but the recommended connection limit also depends on your deployment paradigm — particularly if you are using serverless. You can specify the number of connections explicitly by setting the connection_limit parameter in your database connection URL. For example:

For configuration guidance, refer to Prisma's Recommended connection pool size guide.

In addition to pool size, you can configure a pool_timeout setting. This setting defines the amount of time the Prisma Client query engine has to process a query before it throws an exception and moves on to the next query in the queue. The default pool_timeout setting is 10 seconds. If you still experience timeouts after increasing connection_limit setting, you can try setting the pool_timeout parameter to a value larger than the default (10 seconds). For configuration guidance, refer to Increasing the pool timeout, in the Prisma documentation.

You can disable the pool timeouts by setting pool_timeout=0.

JSON protocol for large Prisma schemas

If you are working with a large Prisma schema, Prisma recently introduced a new Preview feature that expresses queries using JSON instead of GraphQL. The JSON implementation uses less CPU and memory, which can help reduce latencies when connecting from Prisma.

To try the new protocol, enable the jsonProtocol Preview feature in your Prisma schema:

You can read more about this feature here: Preview feature feedback.

Learn more

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?

Join the Neon community forum to ask questions or see what others are doing with Neon. Neon Pro Plan users can open a support ticket from the console. For more detail, see Getting Support.