引擎
从技术角度看,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
(内省引擎)
设置环境变量
你可以在机器上全局定义环境变量,或在 .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
注意:可以将
.env
文件放置在prisma
文件夹之外的位置。
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 bucket 或其他云存储托管引擎文件。这在你拥有需要自定义构建引擎的自定义操作系统时会很有用。
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
将其配置为使用查询引擎的二进制版本。