引擎

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

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

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

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

注意

截至 v6.7.0，Prisma ORM 引入了 queryCompiler 预览特性。

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

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

请注意，驱动适配器预览特性需要与 queryCompiler 一同启用。

您可以在我们的博客上了解更多关于此变更的信息。

Prisma 引擎

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

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

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

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

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

• 无法自动下载引擎文件。
• 您出于测试目的，或针对非官方支持的操作系统，创建了您自己的引擎库或二进制文件。

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

• PRISMA_QUERY_ENGINE_LIBRARY (查询引擎，库)
• PRISMA_QUERY_ENGINE_BINARY (查询引擎，二进制)
• PRISMA_SCHEMA_ENGINE_BINARY (Schema 引擎)
• PRISMA_MIGRATION_ENGINE_BINARY (迁移引擎)
• PRISMA_INTROSPECTION_ENGINE_BINARY (内省引擎)

警告

• PRISMA_MIGRATION_ENGINE_BINARY 变量在 5.0.0 中已弃用。
• 从 4.9.0 版本起，内省引擎由迁移引擎提供。因此，PRISMA_INTROSPECTION_ENGINE 环境变量将不再使用。
• PRISMA_FMT_BINARY 变量用于 4.2.0 或更低的版本。

设置环境变量

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

a) .env 文件

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

Linux, Unix, macOS

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

Windows

PRISMA_QUERY_ENGINE_BINARY=c:\custom\path\my-query-engine-binary.exe

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

b) 全局环境变量

运行以下命令以全局设置环境变量（例如，PRISMA_QUERY_ENGINE_BINARY）

Linux, Unix, macOS

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

Windows

set PRISMA_QUERY_ENGINE_BINARY=c:\custom\my-query-engine-windows.exe

测试您的环境变量

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

npx prisma -v

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

Linux, Unix, macOS

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)

Windows

Current platform     : windows
Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\custom\my-query-engine-windows.exe)
Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\engines\migration-engine-windows.exe)
Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\engines\introspection-engine-windows.exe)

托管引擎

PRISMA_ENGINES_MIRROR 环境变量允许您通过私有服务器、AWS S3 桶或其他云存储来托管引擎文件。如果您有需要定制构建引擎的自定义操作系统，这会很有用。

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 库。您也可以选择将查询引擎配置为可执行二进制文件，该文件将作为您应用程序的 Sidecar 进程运行。推荐使用 Node-API 库方法，因为它减少了 Prisma Client 与查询引擎之间的通信开销。

当调用第一个 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. 查询引擎停止

查询引擎的职责

在使用 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 来将其配置为使用二进制版本的查询引擎。