跳到主要内容

连接池

查询引擎管理着一个数据库连接的连接池。连接池是在 Prisma Client 打开与数据库的第一个连接时创建的，这可以通过两种方式之一发生

关系型数据库连接器使用 Prisma ORM 自己的连接池，而 MongoDB 连接器使用 MongoDB 驱动程序连接池。

注意

自 v6.7.0 起，Prisma ORM 提供了 queryCompiler 预览特性。

启用后，您的 Prisma Client 将在生成时不包含基于 Rust 的查询引擎二进制文件:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["queryCompiler", "driverAdapters"] 
}

请注意，驱动程序适配器预览特性与 queryCompiler 同时需要。使用 queryCompiler 预览特性时，连接池由您使用的原生 JS 数据库驱动程序维护。

关系型数据库​

关系型数据库连接器使用 Prisma ORM 的连接池。连接池有连接限制和连接池超时，它们由连接 URL 参数控制。

连接池工作原理​

以下步骤描述了查询引擎如何使用连接池

  1. 查询引擎实例化一个具有可配置连接池大小和连接池超时的连接池。
  2. 查询引擎创建一个连接并将其添加到连接池。
  3. 当一个查询进来时，查询引擎从连接池中预留一个连接来处理查询。
  4. 如果连接池中没有空闲连接可用，查询引擎会打开额外的数据库连接并将其添加到连接池，直到数据库连接数量达到 connection_limit 定义的限制。
  5. 如果查询引擎无法从连接池中预留连接，查询将被添加到内存中的一个 FIFO（先入先出）队列。FIFO 意味着查询按照进入队列的顺序处理。
  6. 如果查询引擎在时间限制前无法处理队列中的某个查询，它会为该查询抛出错误代码 P2024 的异常，并继续处理队列中的下一个查询。

如果您持续遇到连接池超时错误，您需要优化连接池。

连接池大小​

默认连接池大小​

默认连接数（连接池大小）通过以下公式计算

num_physical_cpus * 2 + 1

num_physical_cpus 表示您的应用程序运行机器上的物理 CPU 数量。如果您的机器有四个物理 CPU，您的连接池将包含九个连接（4 * 2 + 1 = 9）。

虽然这个公式是一个好的起点，但推荐的连接限制也取决于您的部署范例——特别是如果您使用无服务器架构。

设置连接池大小​

您可以通过在数据库连接 URL 中显式设置 connection_limit 参数来指定连接数量。例如，在您的Prisma schema 中使用以下 datasource 配置，连接池将精确拥有五个连接

datasource db {
  provider = "postgresql"
  url      = "postgresql://johndoe:mypassword@localhost:5432/mydb?connection_limit=5"
}

查看连接池大小​

可以使用日志记录和指标来查看 Prisma Client 使用的连接数量。

使用 info 日志级别，您可以记录实例化 Prisma Client 时打开的连接池中的连接数量。

例如，考虑以下 Prisma Client 实例和调用

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient({
  log: ['info'],
})

async function main() {
  await prisma.user.findMany()
}

main()
显示CLI结果
prisma:info Starting a postgresql pool with 21 connections.

当 PrismaClient 类被实例化时，日志记录通知 stdout 已启动一个包含 21 个连接的连接池。

警告

请注意，由 log: ['info'] 生成的输出在任何版本中都可能在不通知的情况下更改。如果您在应用程序或正在构建的工具中依赖此输出，请注意这一点。

如果您需要更多关于连接池大小以及正在使用和空闲连接数量的深入信息，您可以使用指标特性（目前处于预览阶段）。

考虑以下示例

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  await Promise.all([prisma.user.findMany(), prisma.post.findMany()])

  const metrics = await prisma.$metrics.json()
  console.dir(metrics, { depth: Infinity })
}

main()
显示CLI结果
{
  "counters": [
    // ...
    {
      "key": "prisma_pool_connections_open",
      "labels": {},
      "value": 2,
      "description": "Number of currently open Pool Connections"
    }
  ],
  "gauges": [
    // ...
    {
      "key": "prisma_pool_connections_busy",
      "labels": {},
      "value": 0,
      "description": "Number of currently busy Pool Connections (executing a datasource query)"
    },
    {
      "key": "prisma_pool_connections_idle",
      "labels": {},
      "value": 21,
      "description": "Number of currently unused Pool Connections (waiting for the next datasource query to run)"
    },
    {
      "key": "prisma_pool_connections_opened_total",
      "labels": {},
      "value": 2,
      "description": "Total number of Pool Connections opened"
    }
  ],
  "histograms": [
    /** ... **/
  ]
}
信息

有关指标输出中可用内容的更多详细信息，请参见关于指标部分。

连接池超时​

默认连接池超时​

默认连接池超时为 10 秒。如果查询引擎在此时间内未从数据库连接池获取到连接，它将抛出异常并继续处理队列中的下一个查询。

设置连接池超时​

您可以通过在数据库连接 URL 中显式设置 pool_timeout 参数来指定连接池超时时间。在以下示例中，连接池将在 2 秒后超时

datasource db {
  provider = "postgresql"
  url      = "postgresql://johndoe:mypassword@localhost:5432/mydb?connection_limit=5&pool_timeout=2"
}

禁用连接池超时​

通过将 pool_timeout 参数设置为 0 来禁用连接池超时

datasource db {
  provider = "postgresql"
  url      = "postgresql://johndoe:mypassword@localhost:5432/mydb?connection_limit=5&pool_timeout=0"
}

如果您希望查询必须保留在队列中，则可以选择禁用连接池超时——例如，如果您正在并行导入大量记录，并确信队列在作业完成前不会耗尽所有可用 RAM。

MongoDB​

MongoDB 连接器不使用 Prisma ORM 连接池。连接池由 MongoDB 驱动程序在内部管理，并通过连接字符串参数进行配置。

外部连接池​

您不能将 connection_limit 增加到超出底层数据库支持的范围。这在无服务器环境中尤为挑战，因为每个函数都管理着一个 PrismaClient 实例及其自己的连接池。

考虑引入PgBouncer 等外部连接池工具，以防止您的应用程序或函数耗尽数据库连接限制。

手动数据库连接处理​

使用 Prisma ORM 时，数据库连接在引擎层面处理。这意味着它们不会暴露给开发者，并且无法手动访问。