引擎

Prisma ORM v7 默认不使用 Rust 二进制文件

从 Prisma ORM v7 开始，Prisma ORM 默认不使用 Rust 引擎。这意味着：

¥As of Prisma ORM v7, Prisma ORM runs without Rust engines by default. This means:

生成的代码中不包含基于 Rust 二进制文件的查询引擎二进制文件。

¥No Rust binary-based query engine binary is included in your generated code
使用基于 TypeScript 的查询编译器将查询编译为 SQL

¥Queries are compiled to SQL using a TypeScript-based query compiler
数据库连接需要驱动适配器

¥Driver adapters are required for database connectivity
生成的代码更小，更易于在不同的 JavaScript 环境中移植。

¥The generated code is smaller and more portable across different JavaScript environments

此页面记录了传统的基于 Rust 的引擎架构。对于现代的无 Rust 方法（v7 中的默认方法），请参阅不带 Rust 引擎的 Prisma ORM。

¥This page documents the legacy Rust-based engine architecture. For the modern Rust-free approach (default in v7), see Prisma ORM without Rust engines.

Prisma ORM v7 中的默认生成器

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

¥The prisma-client generator is now the default in Prisma ORM v7. It generates TypeScript code into a custom directory you specify (via the output field).

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

¥Learn more about the prisma-client generator.

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

¥From a technical perspective, when using Rust-based engines (legacy approach), Prisma Client consists of three major components:

JavaScript 客户端库

¥JavaScript client library
TypeScript 类型定义

¥TypeScript type definitions
查询引擎（基于 Rust）

¥A query engine (Rust-based)

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

¥All of these components are located in the generated output folder after you run prisma generate.

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

¥This page covers relevant technical details about the Rust-based query engine architecture, which is now optional and primarily used for:

旧版 prisma-client-js 生成器用户

¥Legacy prisma-client-js generator users
使用 prisma-client 生成器显式设置 engineType = "library" 或 engineType = "binary" 的用户

¥Users who explicitly set engineType = "library" or engineType = "binary" with the prisma-client generator

Prisma 引擎

¥Prisma engines

警告

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

¥This section describes the legacy Rust-based engine architecture. In Prisma ORM v7, the default architecture uses a TypeScript-based query compiler without Rust engines.

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

¥At the core of each module, there typically is a Prisma engine that implements the core set of functionality. Engines are implemented in Rust and expose a low-level API that is used by the higher-level interfaces.

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

¥A Prisma engine is the direct interface to the database, any higher-level interfaces always communicate with the database through the engine-layer.

例如，当使用基于 Rust 的引擎时，Prisma Client 会连接到查询引擎以读取和写入数据库中的数据：

¥As an example, when using Rust-based engines, Prisma Client connects to the query engine in order to read and write data in a database:

Prisma engine

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

¥Using custom engine libraries or binaries

警告

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

¥This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries.

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

¥When using Rust-based engines, all engine files are automatically downloaded into the node_modules/@prisma/engines folder when you install or update prisma, the Prisma CLI package. The query engine is also copied to the generated Prisma Client when you call prisma generate.

如果出现以下情况，你可能需要使用自定义库或二进制文件文件：

¥You might want to use a custom library or binary file if:

无法自动下载引擎文件。

¥Automated download of engine files is not possible.
你出于测试目的或未正式支持的操作系统创建了自己的引擎库或二进制文件。

¥You have created your own engine library or binary for testing purposes, or for an OS that is not officially supported.

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

¥Use the following environment variables to specify custom locations for your Rust engine binaries:

PRISMA_QUERY_ENGINE_LIBRARY（查询引擎，库）— Prisma ORM v7 不支持

¥PRISMA_QUERY_ENGINE_LIBRARY (Query engine, library) — Not supported in Prisma ORM v7
PRISMA_QUERY_ENGINE_BINARY（查询引擎，二进制）— Prisma ORM v7 不支持

¥PRISMA_QUERY_ENGINE_BINARY (Query engine, binary) — Not supported in Prisma ORM v7
PRISMA_SCHEMA_ENGINE_BINARY（模式引擎）

¥PRISMA_SCHEMA_ENGINE_BINARY (Schema engine)
PRISMA_MIGRATION_ENGINE_BINARY（迁移引擎）

¥PRISMA_MIGRATION_ENGINE_BINARY (Migration engine)
PRISMA_INTROSPECTION_ENGINE_BINARY（自省引擎）— Prisma ORM v7 不支持

¥PRISMA_INTROSPECTION_ENGINE_BINARY (Introspection engine) — Not supported in Prisma ORM v7

警告

Prisma ORM v7 变更：

¥Prisma ORM v7 changes:

Prisma ORM v7 不支持 PRISMA_QUERY_ENGINE_LIBRARY 和 PRISMA_QUERY_ENGINE_BINARY。

¥PRISMA_QUERY_ENGINE_LIBRARY and PRISMA_QUERY_ENGINE_BINARY are not supported in Prisma ORM v7.
Prisma ORM v7 不支持 PRISMA_INTROSPECTION_ENGINE_BINARY。

¥PRISMA_INTROSPECTION_ENGINE_BINARY is not supported in Prisma ORM v7.

更早的弃用项：

¥Earlier deprecations:

由于迁移引擎已更名为模式引擎，因此 5.0.0 中已弃用 PRISMA_MIGRATION_ENGINE_BINARY 变量。

¥PRISMA_MIGRATION_ENGINE_BINARY variable is deprecated in 5.0.0 because the Migration engine was renamed to Schema Engine.
自省引擎由 4.9.0 中的 Schema Engine 提供服务。因此，不会使用 PRISMA_INTROSPECTION_ENGINE 环境变量。

¥The Introspection Engine is served by the Schema Engine from 4.9.0. Therefore, the PRISMA_INTROSPECTION_ENGINE environment variable will not be used.
PRISMA_FMT_BINARY 变量用于 4.2.0 或更低版本。

¥The PRISMA_FMT_BINARY variable is used in versions 4.2.0 or lower.

设置环境变量

¥Setting the environment variable

你可以在计算机上或在 .env 文件中全局定义环境变量。

¥You can define environment variables globally on your machine or in the .env file.

a) `.env` 文件

¥a) The .env file

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

¥Add the environment variable to the .env file.

Linux, Unix, macOS

Windows

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

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

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

¥Note: It is possible to use an .env file in a location outside the prisma folder.

b) 全局环境变量

¥b) Global environment variable

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

¥Run the following command to set the environment variable globally (in this example, PRISMA_QUERY_ENGINE_BINARY):

Linux, Unix, macOS

Windows

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

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

测试你的环境变量

¥Test your environment variable

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

¥Run the following command to output the paths to all binaries:

npx prisma -v

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

¥The output shows that the query engine path comes from the PRISMA_QUERY_ENGINE_BINARY environment variable:

Linux, Unix, macOS

Windows

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)

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)

托管引擎

¥Hosting engines

警告

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

¥This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries.

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

¥The PRISMA_ENGINES_MIRROR environment variable allows you to host engine files via a private server, AWS bucket or other cloud storage. This can be useful if you have a custom OS that requires custom-built engines.

PRISMA_ENGINES_MIRROR=https://my-aws-bucket

查询引擎文件

¥The query engine file

警告

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

¥This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries.

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

¥The query engine file is different for each operating system. It is named query-engine-PLATFORM or libquery_engine-PLATFORM where PLATFORM corresponds to the name of a compile target. Query engine file extensions depend on the platform as well. As an example, if the query engine must run on a Darwin operating system such as macOS Intel, it is called libquery_engine-darwin.dylib.node or query-engine-darwin. You can find an overview of all supported platforms here.

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

¥The query engine file is downloaded into the runtime directory of the generated Prisma Client when prisma generate is called.

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

¥Note that the query engine is implemented in Rust. The source code is located in the prisma-engines repository.

运行时的查询引擎

¥The query engine at runtime

警告

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

¥This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries.

使用基于 Rust 的引擎时，Prisma Client 默认将查询引擎加载为节点 API 库。你也可以选择配置 Prisma 以使用编译为可执行二进制文件的查询引擎，它作为 sidecar 进程与你的应用一起运行。建议使用 Node-API 库方法，因为它减少了 Prisma 客户端和查询引擎之间的通信开销。

¥When using Rust-based engines, Prisma Client loads the query engine as a Node-API library by default. You can alternatively configure Prisma to use the query engine compiled as an executable binary, which is run as a sidecar process alongside your application. The Node-API library approach is recommended since it reduces the communication overhead between Prisma Client and the query engine.

Diagram showing the query engine and Node.js at runtime

当调用第一个 Prisma 客户端查询或在 PrismaClient 实例上调用 $connect() 方法时，查询引擎将启动。查询引擎启动后，它会创建连接池并管理与数据库的物理连接。从那时起，Prisma 客户端就准备好将 queries 发送到数据库（例如 findUnique()、findMany、create，...）。

¥The query engine is started when the first Prisma Client query is invoked or when the $connect() method is called on your PrismaClient instance. Once the query engine is started, it creates a connection pool and manages the physical connections to the database. From that point onwards, Prisma Client is ready to send queries to the database (e.g. findUnique(), findMany, create, ...).

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

¥The query engine is stopped and the database connections are closed when $disconnect() is invoked.

下图描绘了 "典型流量"：

¥The following diagram depicts a "typical flow":

在 Prisma 客户端上调用 $connect()

¥$connect() is invoked on Prisma Client
查询引擎已启动

¥The query engine is started
查询引擎建立与数据库的连接并创建连接池

¥The query engine establishes connections to the database and creates connection pool
Prisma 客户端现已准备好向数据库发送查询

¥Prisma Client is now ready to send queries to the database
Prisma 客户端向查询引擎发送 findMany() 查询

¥Prisma Client sends a findMany() query to the query engine
查询引擎将查询翻译成 SQL 并发送给数据库

¥The query engine translates the query into SQL and sends it to the database
查询引擎接收数据库的 SQL 响应

¥The query engine receives the SQL response from the database
查询引擎将结果作为普通的旧 JavaScript 对象返回到 Prisma 客户端

¥The query engine returns the result as plain old JavaScript objects to Prisma Client
在 Prisma 客户端上调用 $disconnect()

¥$disconnect() is invoked on Prisma Client
查询引擎关闭数据库连接

¥The query engine closes the database connections
查询引擎已停止

¥The query engine is stopped

Typical flow of the query engine at run time

查询引擎的职责

¥Responsibilities of the query engine

警告

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

¥This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries.

基于 Rust 的查询引擎在使用 Prisma Client 的应用中承担以下职责：

¥The Rust-based query engine has the following responsibilities in an application that uses Prisma Client:

管理连接池中的物理数据库连接

¥manage physical database connections in connection pool
接收来自 Prisma 客户端 Node.js 进程的传入查询

¥receive incoming queries from the Prisma Client Node.js process
生成 SQL 查询

¥generate SQL queries
向数据库发送 SQL 查询

¥send SQL queries to the database
处理来自数据库的响应并将其发送回 Prisma 客户端

¥process responses from the database and send them back to Prisma Client

调试查询引擎

¥Debugging the query engine

警告

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

¥This section applies only to Rust-based engines. Prisma ORM v7 defaults to the TypeScript-based query compiler without Rust engine binaries.

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

¥You can access the logs of the Rust-based query engine by setting the DEBUG environment variable to engine:

export DEBUG="engine"

你还可以通过在 Prisma 客户端中设置 query 日志级别来更深入地了解查询引擎生成的 SQL 查询：

¥You can also get more visibility into the SQL queries that are generated by the query engine by setting the query log level in Prisma Client:

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

了解有关调试和记录的更多信息。

¥Learn more about Debugging and Logging.

配置查询引擎

¥Configuring the query engine

警告

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

¥The configuration options in this section apply only to Rust-based engines used in Prisma ORM v6.19 and earlier. Prisma ORM v7 uses the TypeScript-based query compiler by default and does not use these Rust engine configurations.

定义 Prisma 客户端的查询引擎类型

¥Defining the query engine type for Prisma Client

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

¥When using Rust-based engines, you can choose between a Node-API library or an executable binary. Configure the query engine type by providing the engineType property to the Prisma Client generator:

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

engineType 的有效值如下：

¥Valid values for engineType are:

binary - 作为 sidecar 进程运行的可执行二进制文件（基于 Rust）

¥binary - Executable binary that runs as a sidecar process (Rust-based)
library - 已将 Node-API 库加载到 Prisma Client 中（基于 Rust，v6 及更早版本默认使用）

¥library - Node-API library loaded into Prisma Client (Rust-based, default for v6 and earlier)

警告

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

¥The environment variable PRISMA_CLIENT_ENGINE_TYPE is not supported in Prisma ORM v7 because Prisma Client now defaults to the TypeScript-based query compiler without Rust engine binaries. See Prisma ORM without Rust engines for more information.

历史背景

在 Prisma 3.x 之前，默认且唯一可用的引擎类型是 binary，因此无法配置 Prisma Client 和 Prisma CLI 使用的引擎类型。

¥Until Prisma 3.x the default and only engine type available was binary, so there was no way to configure the engine type to be used by Prisma Client and Prisma CLI.
从版本 2.20.0 到 3.x，library 引擎类型可用，并且默认由激活预览功能标志“nApi”使用或使用 PRISMA_FORCE_NAPI=true 环境变量。

¥From versions 2.20.0 to 3.x the library engine type was available and used by default by activating the preview feature flag "nApi" or using the PRISMA_FORCE_NAPI=true environment variable.
从 Prisma ORM v7 开始，默认使用基于 TypeScript 的查询编译器（不使用 Rust 二进制文件），无需设置 engineType 端口。

¥As of Prisma ORM v7, the TypeScript-based query compiler (no Rust binaries) is the default and engineType does not need to be set.

定义 Prisma CLI 的查询引擎类型

¥Defining the query engine type for Prisma CLI

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

¥When using Rust-based engines, Prisma CLI also uses its own query engine. You can configure it to use the binary version of the query engine by defining the environment variable PRISMA_CLI_QUERY_ENGINE_TYPE=binary.

警告

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

¥The environment variable PRISMA_CLI_QUERY_ENGINE_TYPE is not supported in Prisma ORM v7 because Prisma CLI now defaults to the TypeScript-based query compiler without Rust engine binaries. See Prisma ORM without Rust engines for more information.

Prisma 引擎​

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

设置环境变量​

a) .env 文件​

b) 全局环境变量​

测试你的环境变量​

托管引擎​

查询引擎文件​

运行时的查询引擎​

查询引擎的职责​

调试查询引擎​

配置查询引擎​

定义 Prisma 客户端的查询引擎类型​

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

Prisma 引擎

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

设置环境变量

a) `.env` 文件

b) 全局环境变量

测试你的环境变量

托管引擎

查询引擎文件

运行时的查询引擎

查询引擎的职责

调试查询引擎

配置查询引擎

定义 Prisma 客户端的查询引擎类型

定义 Prisma CLI 的查询引擎类型