Connection management

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` function
await prisma.$connect()

Calling $disconnect() explicitly

When Prisma Client disconnects, it:

1. Runs the beforeExit hook
2. Ends child processes
3. 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:

1. 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
2. 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 available
    await prisma.message.create({
      data: {
        message: "Shutting down server";
      }
    })
})