跳至主要内容

连接池

快速摘要

本页介绍 Prisma ORM 如何使用连接池管理数据库连接，以及如何配置连接限制和超时以实现最佳性能。

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

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

本页面回答的问题
  • 如何设置 Prisma 连接池的大小？
  • 如何设置连接池超时和限制？
  • 何时应该将 PgBouncer 与 Prisma 结合使用？

关系型数据库​

从 Prisma ORM v7 开始，关系型数据源默认使用驱动适配器实例化 Prisma Client。驱动适配器依赖于您提供的 Node.js 驱动，因此连接池默认值（和配置）现在来自驱动本身。

使用下表将 Prisma ORM v6 连接 URL 参数转换为 Prisma ORM v7 驱动适配器字段及其默认值。

Prisma ORM v7 驱动适配器默认值​

下表记录了每个驱动适配器的默认连接池设置。

Prisma 超时

Prisma ORM 也有自己的可配置超时，它们与数据库驱动超时是分开的。如果您看到超时错误并且不确定它来自驱动还是来自 Prisma Client，请参阅Prisma Client 超时和事务选项文档。

PostgreSQL（使用pg驱动适配器）​

以下是pg驱动适配器的默认连接池设置

行为v6 URL 参数v6 默认值v7 pg 配置字段v7 默认值
连接池大小connection_limitnum_cpus::get_physical() * 2 + 1max10
获取超时pool_timeout10秒connectionTimeoutMillis0（无超时）
连接超时connect_timeout5秒connectionTimeoutMillis0（无超时）
空闲超时max_idle_connection_lifetime300秒idleTimeoutMillis10秒
连接生命周期max_connection_lifetime0（无超时）maxLifetimeSeconds0（无超时）
提示

有关每个可用选项的详细信息，请参阅node-postgres 连接池文档。

MySQL 或 MariaDB（使用mariadb驱动程序）​

以下是mariadb驱动适配器的默认连接池设置

行为v6 URL 参数v6 默认值v7 mariadb 配置字段v7 默认值
连接池大小connection_limitnum_cpus::get_physical() * 2 + 1connectionLimit10
获取超时pool_timeout10秒acquireTimeout10秒
连接超时connect_timeout5秒connectTimeout1秒
空闲超时max_idle_connection_lifetime300秒idleTimeout1800秒
提示

有关配置和调优指南，请参阅MariaDB Connector/Node.js 连接池选项。

SQL Server（使用mssql驱动程序）​

以下是mssql驱动适配器的默认连接池设置

行为v6 URL 参数v6 默认值v7 mssql 配置字段v7 默认值
连接池大小connection_limitnum_cpus::get_physical() * 2 + 1pool.max10
连接超时connect_timeout5秒connectionTimeout15秒
空闲超时max_idle_connection_lifetime300秒pool.idleTimeoutMillis30秒
提示

有关这些字段的详细信息，请参阅node-mssql 连接池文档。

MongoDB​

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

外部连接池​

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

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

手动数据库连接处理​

使用 Prisma ORM 时，数据库连接在引擎级别处理。这意味着它们不会暴露给开发人员，也无法手动访问它们。

Prisma ORM v6 及更早版本​

连接池的工作原理​

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

  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 模式中，使用以下datasource配置，连接池将正好有五个连接

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

查看连接池大小​

Prisma Client 使用的连接数可以使用日志和所使用的驱动适配器提供的内置 API 进行查看。

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

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

import { PrismaClient } from '../prisma/generated/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/generated/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。

打开方式
复制为 Markdown
在 Claude 中打开
在 ChatGPT 中打开
在 T3.chat 中打开
在 GitHub 中编辑
© . This site is unofficial and not affiliated with Prisma Data, Inc.