Skip to main content

引擎

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

¥From a technical perspective, Prisma Client consists of three major components:

  • JavaScript 客户端库

    ¥JavaScript client library

  • TypeScript 类型定义

    ¥TypeScript type definitions

  • 一个查询引擎

    ¥A query engine

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

¥All of these components are located in the generated .prisma/client folder after you ran prisma generate.

本页介绍了有关查询引擎的相关技术细节。

¥This page covers relevant technical details about the query engine.

注意

从 v6.7.0 开始，Prisma ORM 具有 queryCompiler 预览功能。

¥As of v6.7.0, Prisma ORM has the queryCompiler Preview feature.

启用后，你的 Prisma 客户端将生成 无需基于 Rust 的查询引擎二进制文件：

¥When enabled, your Prisma Client will be generated without a Rust-based query engine binary:

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

请注意，驱动适配器 预览功能与 queryCompiler 功能同时启用。

¥Note that the driver adapters Preview feature is required alongside queryCompiler.

你可以在我们的博客上 了解更多 告知我们这项更改。

¥You can learn more about the change on our blog.

Prisma 引擎​

¥Prisma 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.

例如，Prisma 客户端连接到 查询引擎 以读取和写入数据库中的数据：

¥As an example, 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

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

¥By default, 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.

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

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

warning

  • PRISMA_MIGRATION_ENGINE_BINARY 变量在 5.0.0 中已弃用。

    ¥PRISMA_MIGRATION_ENGINE_BINARY variable is deprecated in 5.0.0.

  • 自省引擎由 4.9.0 的迁移引擎提供服务。因此，不会使用 PRISMA_INTROSPECTION_ENGINE 环境变量。

    ¥The Introspection Engine is served by the Migration 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.

PRISMA_QUERY_ENGINE_BINARY=custom/my-query-engine-unix

注意：在 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):

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

测试你的环境变量​

¥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:

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)

托管引擎​

¥Hosting engines

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

每个操作系统的查询引擎文件都不同。它被命名为 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

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

¥By default, Prisma Client loads the query engine as a Node-API library. 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":

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

    ¥$connect() is invoked on Prisma Client

  2. 查询引擎已启动

    ¥The query engine is started

  3. 查询引擎建立与数据库的连接并创建连接池

    ¥The query engine establishes connections to the database and creates connection pool

  4. Prisma 客户端现已准备好向数据库发送查询

    ¥Prisma Client is now ready to send queries to the database

  5. Prisma 客户端向查询引擎发送 findMany() 查询

    ¥Prisma Client sends a findMany() query to the query engine

  6. 查询引擎将查询翻译成 SQL 并发送给数据库

    ¥The query engine translates the query into SQL and sends it to the database

  7. 查询引擎接收数据库的 SQL 响应

    ¥The query engine receives the SQL response from the database

  8. 查询引擎将结果作为普通的旧 JavaScript 对象返回到 Prisma 客户端

    ¥The query engine returns the result as plain old JavaScript objects to Prisma Client

  9. 在 Prisma 客户端上调用 $disconnect()

    ¥$disconnect() is invoked on Prisma Client

  10. 查询引擎关闭数据库连接

    ¥The query engine closes the database connections

  11. 查询引擎已停止

    ¥The query engine is stopped

Typical flow of the query engine at run time

查询引擎的职责​

¥Responsibilities of the query engine

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

¥The 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

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

¥You can access the logs of the 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 客户端的查询引擎类型​

¥Defining the query engine type for Prisma Client

如上所述 默认查询引擎是加载到 Prisma 客户端中的 Node-API 库，但还有一种替代实现，作为在其自己的进程中运行的可执行二进制文件。你可以通过向 Prisma 客户端 generator 提供 engineType 属性来配置查询引擎类型：

¥As described above the default query engine is a Node-API library that is loaded into Prisma Client, but there is also an alternative implementation as an executable binary that runs in its own process. You can configure the query engine type by providing the engineType property to the Prisma Client generator:

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

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

¥Valid values for engineType are binary and library. You can also use the environment variable PRISMA_CLIENT_ENGINE_TYPE instead.

info

  • 在 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 CLI 的查询引擎类型​

¥Defining the query engine type for Prisma CLI

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

¥Prisma CLI also uses its own query engine for its own needs. You can configure it to use the binary version of the query engine by defining the environment variable PRISMA_CLI_QUERY_ENGINE_TYPE=binary.