引擎
从技术角度来看,Prisma Client 由三个主要组件构成
- JavaScript 客户端库
- TypeScript 类型定义
- 一个查询引擎
所有这些组件在你运行 prisma generate
后都位于生成的 .prisma/client
文件夹中。
本页涵盖了关于查询引擎的相关技术细节。
Prisma 引擎
在每个模块的核心,通常都有一个 Prisma 引擎,它实现了核心功能集。引擎使用 Rust 实现,并暴露一个底层 API,供更高级别的接口使用。
Prisma 引擎是数据库的直接接口,任何更高级别的接口始终通过引擎层与数据库通信。
例如,Prisma Client 连接到查询引擎,以便在数据库中读取和写入数据
使用自定义引擎库或二进制文件
默认情况下,当你安装或更新 Prisma CLI 包 prisma
时,所有引擎文件都会自动下载到 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
(Migration 引擎)PRISMA_INTROSPECTION_ENGINE_BINARY
(Introspection 引擎)
设置环境变量
你可以在你的机器上全局定义环境变量,或者在 .env
文件中定义。
a) .env
文件
将环境变量添加到 .env
文件。
- 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
文件。
b) 全局环境变量
运行以下命令以全局设置环境变量(在本例中为 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
测试你的环境变量
运行以下命令以输出所有二进制文件的路径
npx prisma -v
输出显示查询引擎路径来自 PRISMA_QUERY_ENGINE_BINARY
环境变量。
- 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)
托管引擎
PRISMA_ENGINES_MIRROR
环境变量允许你通过私有服务器、AWS S3 存储桶或其他云存储托管引擎文件。如果你有一个需要自定义构建引擎的自定义操作系统,这可能很有用。
PRISMA_ENGINES_MIRROR=https://my-aws-bucket
查询引擎文件
查询引擎文件对于每个操作系统都不同。它被命名为 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
仓库中。
运行时的查询引擎
默认情况下,Prisma Client 将查询引擎作为 Node-API 库 加载。你也可以配置 Prisma 使用编译为可执行二进制文件的查询引擎,它会作为你应用程序的边车进程运行。推荐使用 Node-API 库方法,因为它减少了 Prisma Client 和查询引擎之间的通信开销。
当第一个 Prisma Client 查询被调用时,或者当你的 PrismaClient
实例上调用 $connect()
方法时,查询引擎会被启动。一旦查询引擎启动,它会创建一个连接池并管理到数据库的物理连接。从那时起,Prisma Client 就可以向数据库发送查询了(例如,findUnique()
、findMany
、create
等)。
当$disconnect()
被调用时,查询引擎会被停止,数据库连接会被关闭。
以下图表描述了一个“典型流程”
- 在 Prisma Client 上调用
$connect()
- 查询引擎启动
- 查询引擎建立到数据库的连接并创建连接池
- Prisma Client 现在已准备好向数据库发送查询
- Prisma Client 向查询引擎发送
findMany()
查询 - 查询引擎将查询翻译成 SQL 并发送到数据库
- 查询引擎接收来自数据库的 SQL 响应
- 查询引擎将结果作为普通的 JavaScript 对象返回给 Prisma Client
- 在 Prisma Client 上调用
$disconnect()
- 查询引擎关闭数据库连接
- 查询引擎停止
查询引擎的职责
查询引擎在使用 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 CLI 定义查询引擎类型
Prisma CLI 也为其自身需求使用自己的查询引擎。你可以通过定义环境变量 PRISMA_CLI_QUERY_ENGINE_TYPE=binary
来配置它使用查询引擎的二进制版本。