Connection management
Prisma Client connects and disconnects from your data sources using the following two methods:
In most cases, you do not need to explicitly call either of these methods.
Calling $connect()
explicitly
It is not necessary to call prisma.$connect()
thanks to the lazy connect behavior: The PrismaClient
instance connects lazily when the first request is made to the API ($connect()
is called for you under the hood).
If you need the first request to respond instantly and cannot wait for a lazy connection to be established, you can explicitly call prisma.$connect()
to establish a connection to the data source:
const prisma = new PrismaClient()// run inside `async` functionawait prisma.$connect()
Calling $disconnect()
explicitly
When Prisma Client disconnects, it:
- Runs the
beforeExit
hook - Ends child processes
- Ends the Node.js process if there are no other active listeners (for example,
SIGINT
)
In a long-running application such as a GraphQL API, which constantly serves requests, it does not make sense to $disconnect()
after each request - it takes time to establish a connection, and doing so as part of each request will slow down your application.
Tip: To avoid too many connections, we recommend that you use a single instance of
PrismaClient
across your application.
One scenario where you should call $disconnect()
explicitly is where a script:
- Runs infrequently (for example, a scheduled job to send emails each night), which means it does not benefit from a long-running connection to the database and
- Exists in the context of a long-running application, such as a background service. If the application never shuts down, Prisma Client never disconnects.
The following script creates a new instance of PrismaClient
, performs a task, and then disconnects - which closes the connection pool:
import { PrismaClient } from "@prisma/client";const prisma = new PrismaClient()const emailService = new EmailService();async function main() {const allUsers = await prisma.user.findMany();const emails = allUsers.map(x => x.email)await emailService.send(emails, "Hello!");}main().catch(e => {throw e}).finally(async () => {await prisma.$disconnect()})
If the above script runs multiple times in the context of a long-running application without calling $disconnect()
, a new connection pool is created with each new instance of PrismaClient
.
Connection management in serverless environments
In serverless environments, such as AWS Lambda, there are nuances that make it sensible to reuse database connections and not call $disconnect()
. Refer to the deployment docs for more examples.
Connection pool
Once $connect
was called, the query engine immediately creates a connection pool for the amount of connections that were specified as theconnection_limit
parameter on your database connection URL.
For example, with the following datasource
configuration in your Prisma schema the connection pool will have exactly five connections:
datasource db {provider = "postgresql"url = "postgresql://johndoe:mypassword@localhost:5432/mydb?connection_limit=5"}
If the connection_limit
argument is omitted, the default number of connections is calculated according to this formula: num_physical_cpus * 2 + 1
where num_physical_cpus
represents the number of physical CPUs on your machine.
datasource db {provider = "postgresql"url = "postgresql://johndoe:mypassword@localhost:5432/mydb"}
If your machine has four physical CPUs, your connection pool will contain nine connections (4 * 2 + 1 = 9
).
Exit hooks
The beforeExit
hook runs before Prisma ends its child processes and allows you to issue queries beore the client disconnects - for example, as part of a graceful shutdown of a service:
const prisma = new PrismaClient();prisma.$on('beforeExit', async () => {// PrismaClient still availableawait prisma.message.create({data: {message: "Shutting down server";}})})