跳到主要内容

引擎

从技术角度来看，Prisma Client 由三个主要组件构成

  • JavaScript 客户端库
  • TypeScript 类型定义
  • 一个查询引擎

在你运行 prisma generate 后，所有这些组件都位于 生成的 .prisma/client 文件夹 中。

此页面涵盖关于查询引擎的相关技术细节。

Prisma 引擎​

在每个模块的核心，通常都有一个 Prisma 引擎 实现核心功能集。引擎使用 Rust 实现，并暴露一个供更高级别接口使用的底层 API。

Prisma 引擎是数据库的直接接口，任何更高级别的接口始终通过引擎层与数据库通信。

例如，Prisma Client 连接到 查询引擎 以便在数据库中读取和写入数据

Prisma engine

使用自定义引擎库或二进制文件​

默认情况下，当你安装或更新 Prisma CLI 包 prisma 时，所有引擎文件都会自动下载到 node_modules/@prisma/engines 文件夹中。当你调用 prisma generate 时，查询引擎 也会被复制到生成的 Prisma Client 中。在以下情况下，你可能想要使用 自定义库或二进制文件：

  • 无法自动下载引擎文件。
  • 你已经创建了自己的引擎库或二进制文件用于测试目的，或者用于未正式支持的操作系统。

使用以下环境变量来指定你的二进制文件的自定义位置

警告
  • PRISMA_MIGRATION_ENGINE_BINARY 变量在 5.0.0 中已被弃用。
  • 内省引擎由迁移引擎从 4.9.0 提供服务。因此，PRISMA_INTROSPECTION_ENGINE 环境变量将不会被使用。
  • PRISMA_FMT_BINARY 变量在 4.2.0 或更低版本中使用。

设置环境变量​

你可以在你的机器上全局定义环境变量，或者在 .env 文件中定义。

a) .env 文件​

将环境变量添加到 .env 文件。

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

注意：可以在 prisma 文件夹之外的位置 使用 .env 文件。

b) 全局环境变量​

运行以下命令以全局设置环境变量（在本例中为 PRISMA_QUERY_ENGINE_BINARY）

export PRISMA_QUERY_ENGINE_BINARY=/custom/my-query-engine-unix

测试你的环境变量​

运行以下命令以输出所有二进制文件的路径

npx prisma -v

输出显示查询引擎路径来自 PRISMA_QUERY_ENGINE_BINARY 环境变量

Current platform     : darwin
Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-unix)
Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/migration-engine-unix)
Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/engines/introspection-engine-unix)

托管引擎​

PRISMA_ENGINES_MIRROR 环境变量允许你通过私有服务器、AWS 存储桶或其他云存储托管引擎文件。如果你有一个需要自定义构建引擎的自定义操作系统，这将非常有用。

PRISMA_ENGINES_MIRROR=https://my-aws-bucket

查询引擎文件​

查询引擎文件 对于每个操作系统都是不同的。它被命名为 query-engine-PLATFORM 或 libquery_engine-PLATFORM，其中 PLATFORM 对应于编译目标的名称。查询引擎文件扩展名也取决于平台。例如，如果查询引擎必须在像 macOS Intel 这样的 Darwin 操作系统上运行，它被称为 libquery_engine-darwin.dylib.node 或 query-engine-darwin。你可以在 此处 找到所有支持平台的概述。

当调用 prisma generate 时，查询引擎文件会被下载到生成的 Prisma Client 的 runtime 目录中。

注意，查询引擎是用 Rust 实现的。源代码位于 prisma-engines 仓库中。

运行时中的查询引擎​

默认情况下，Prisma Client 将查询引擎作为 Node-API 库 加载。你也可以 配置 Prisma 使用编译为可执行二进制文件的查询引擎，它会作为 sidecar 进程与你的应用程序一起运行。建议使用 Node-API 库方法，因为它减少了 Prisma Client 和查询引擎之间的通信开销。

Diagram showing the query engine and Node.js at runtime

当第一个 Prisma Client 查询被调用时，或者当在你的 PrismaClient 实例上调用 $connect() 方法时，查询引擎会启动。一旦查询引擎启动，它会创建一个 连接池 并管理与数据库的物理连接。从那时起，Prisma Client 就可以向数据库发送 查询（例如 findUnique()、findMany、create 等）。

当调用 $disconnect() 时，查询引擎会停止，数据库连接也会关闭。

以下图表描述了一个“典型流程”

  1. 在 Prisma Client 上调用 $connect()
  2. 查询引擎启动
  3. 查询引擎建立与数据库的连接并创建连接池
  4. Prisma Client 现在可以向数据库发送查询
  5. Prisma Client 向查询引擎发送 findMany() 查询
  6. 查询引擎将查询翻译成 SQL 并发送到数据库
  7. 查询引擎接收来自数据库的 SQL 响应
  8. 查询引擎将结果作为普通的 JavaScript 对象返回给 Prisma Client
  9. 在 Prisma Client 上调用 $disconnect()
  10. 查询引擎关闭数据库连接
  11. 查询引擎停止

Typical flow of the query engine at run time

查询引擎的职责​

在使用 Prisma Client 的应用程序中，查询引擎具有以下职责：

  • 管理连接池中的物理数据库连接
  • 接收来自 Prisma Client Node.js 进程的传入查询
  • 生成 SQL 查询
  • 向数据库发送 SQL 查询
  • 处理来自数据库的响应并将它们返回给 Prisma Client

调试查询引擎​

你可以通过将 DEBUG 环境变量设置为 engine 来访问查询引擎的日志。

export DEBUG="engine"

你还可以通过在 Prisma Client 中设置 query 日志级别 来更清楚地了解查询引擎生成的 SQL 查询。

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

了解更多关于 调试 和 日志记录 的信息。

配置查询引擎​

为 Prisma Client 定义查询引擎类型​

如上所述，默认的查询引擎是一个加载到 Prisma Client 中的 Node-API 库，但也有另一种实现方式，即作为在其自身进程中运行的可执行二进制文件。你可以通过向 Prisma Client generator 提供 engineType 属性来配置查询引擎类型。

generator client {
  provider   = "prisma-client-js"
  engineType = "binary"
}

engineType 的有效值是 binary 和 library。你也可以使用环境变量 PRISMA_CLIENT_ENGINE_TYPE 代替。

信息
  • 在 Prisma 3.x 之前，默认且唯一可用的引擎类型是 binary，因此无法配置 Prisma Client 和 Prisma CLI 使用的引擎类型。
  • 从 2.20.0 到 3.x 版本，library 引擎类型可用，并通过 激活预览功能标志 “nApi” 或使用 PRISMA_FORCE_NAPI=true 环境变量默认使用。

为 Prisma CLI 定义查询引擎类型​

Prisma CLI 也为其自身需求使用自己的查询引擎。你可以通过定义环境变量 PRISMA_CLI_QUERY_ENGINE_TYPE=binary 来配置它使用查询引擎的二进制版本。