跳至主要内容

引擎

Prisma ORM v7 默认无 Rust 二进制文件

从 Prisma ORM v7 开始，Prisma ORM 默认在没有 Rust 引擎的情况下运行。这意味着：

  • 生成的代码中不包含基于 Rust 二进制文件的查询引擎二进制文件
  • 查询使用基于 TypeScript 的查询编译器编译为 SQL
  • 数据库连接需要驱动适配器
  • 生成的代码更小，并且在不同的 JavaScript 环境中更具可移植性

此页面记录了旧的基于 Rust 的引擎架构。有关现代无 Rust 方法（v7 中的默认值），请参阅不使用 Rust 引擎的 Prisma ORM。

Prisma ORM v7 中的默认生成器

prisma-client 生成器现在是 Prisma ORM v7 中的默认生成器。它将 TypeScript 代码生成到您指定的自定义目录中（通过 output 字段）。

了解有关prisma-client 生成器的更多信息。

从技术角度来看，当使用 基于 Rust 的引擎（传统方法）时，Prisma Client 由三个主要组件组成：

  • JavaScript 客户端库
  • TypeScript 类型定义
  • 查询引擎（基于 Rust）

运行 prisma generate 后，所有这些组件都位于生成的输出文件夹中。

此页面涵盖了有关 基于 Rust 的查询引擎架构 的相关技术细节，该架构现在是可选的，主要用于：

  • 传统 prisma-client-js 生成器用户
  • 明确设置 engineType = "library" 或 engineType = "binary" 的 prisma-client 生成器用户

Prisma 引擎​

警告

本节描述了 旧的基于 Rust 的引擎架构。在 Prisma ORM v7 中，默认架构使用基于 TypeScript 的查询编译器，不使用 Rust 引擎。

每个模块的核心通常是一个 Prisma 引擎，它实现了核心功能集。引擎用 Rust 实现，并公开了一个低级 API，供高级接口使用。

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

例如，当使用基于 Rust 的引擎时，Prisma Client 连接到查询引擎以在数据库中读写数据。

Prisma engine

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

警告

本节 仅适用于基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。

当使用基于 Rust 的引擎时，当您安装或更新 prisma（Prisma CLI 包）时，所有引擎文件都会自动下载到 node_modules/@prisma/engines 文件夹中。当您调用 prisma generate 时，查询引擎也会复制到生成的 Prisma Client 中。

如果您遇到以下情况，您可能希望使用 自定义库或二进制文件：

  • 无法自动下载引擎文件。
  • 您已为测试目的或不支持的操作系统创建了自己的引擎库或二进制文件。

使用以下环境变量指定 Rust 引擎二进制文件的自定义位置：

警告

Prisma ORM v7 变更

  • Prisma ORM v7 不支持 PRISMA_QUERY_ENGINE_LIBRARY 和 PRISMA_QUERY_ENGINE_BINARY。
  • Prisma ORM v7 不支持 PRISMA_INTROSPECTION_ENGINE_BINARY。

早期弃用

  • 由于迁移引擎更名为 Schema 引擎，PRISMA_MIGRATION_ENGINE_BINARY 变量在 5.0.0 中已弃用。
  • 自 4.9.0 起，内省引擎由 Schema 引擎提供。因此，将不会使用 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)

托管引擎​

警告

本节 仅适用于基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。

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

PRISMA_ENGINES_MIRROR=https://my-aws-bucket

查询引擎文件​

警告

本节 仅适用于基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。

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

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

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

运行时查询引擎​

警告

本节 仅适用于基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。

当使用基于 Rust 的引擎时，Prisma Client 默认将查询引擎作为 Node-API 库 加载。您还可以配置 Prisma 以使用编译为可执行二进制文件的查询引擎，该二进制文件作为您应用程序的伴随进程运行。建议使用 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

查询引擎的职责​

警告

本节 仅适用于基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。

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

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

调试查询引擎​

警告

本节仅适用于基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。

您可以通过将 DEBUG 环境变量设置为 engine 来访问基于 Rust 的查询引擎的日志：

export DEBUG="engine"

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

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

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

配置查询引擎​

警告

本节中的配置选项 仅适用于 Prisma ORM v6.19 及更早版本中使用的 基于 Rust 的引擎。Prisma ORM v7 默认使用基于 TypeScript 的查询编译器，不使用这些 Rust 引擎配置。

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

当使用基于 Rust 的引擎时，您可以选择 Node-API 库或可执行二进制文件。通过为 Prisma Client generator 提供 engineType 属性来配置查询引擎类型：

generator client {
  provider   = "prisma-client"
  output     = "./generated"
  engineType = "binary"
}

engineType 的有效值为：

  • binary - 作为伴随进程运行的可执行二进制文件（基于 Rust）
  • library - 加载到 Prisma Client 中的 Node-API 库（基于 Rust，v6 及更早版本的默认值）
警告

Prisma ORM v7 不支持环境变量 PRISMA_CLIENT_ENGINE_TYPE，因为 Prisma Client 现在默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。有关更多信息，请参阅不使用 Rust 引擎的 Prisma ORM。

历史背景
  • 直到 Prisma 3.x，默认且唯一可用的引擎类型是 binary，因此无法配置 Prisma Client 和 Prisma CLI 使用的引擎类型。
  • 从版本 2.20.0 到 3.x，library 引擎类型可用，并且默认通过激活预览功能标志“nApi”或使用 PRISMA_FORCE_NAPI=true 环境变量来使用。
  • 从 Prisma ORM v7 开始，基于 TypeScript 的查询编译器（无 Rust 二进制文件）是默认设置，无需设置 engineType。

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

当使用基于 Rust 的引擎时，Prisma CLI 也使用自己的查询引擎。您可以通过定义环境变量 PRISMA_CLI_QUERY_ENGINE_TYPE=binary 将其配置为使用二进制版本的查询引擎。

警告

Prisma ORM v7 不支持环境变量 PRISMA_CLI_QUERY_ENGINE_TYPE，因为 Prisma CLI 现在默认使用基于 TypeScript 的查询编译器，不使用 Rust 引擎二进制文件。有关更多信息，请参阅不使用 Rust 引擎的 Prisma ORM。

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