生成器
一个 Prisma schema 可以有一个或多个生成器,由 generator
块表示
generator client {
provider = "prisma-client-js"
output = "./generated/prisma-client-js"
}
生成器决定了当你运行 prisma generate
命令时会创建哪些资产。
Prisma Client 有两种生成器
prisma-client-js
:将 Prisma Client 生成到node_modules
中prisma-client
(抢先体验):prisma-client-js
的更新、更灵活版本,支持 ESM;它输出纯 TypeScript 代码并要求自定义output
路径
或者,你可以配置任何符合我们生成器规范的 npm 包。
prisma-client-js
prisma-client-js
是 Prisma ORM 6.X 版本及更早版本的默认生成器。它需要 @prisma/client
npm 包,并将 Prisma Client 生成到 node_modules
中。
字段参考
Prisma 的 JavaScript Client 生成器接受多个附加属性
previewFeatures
:要包含的预览功能binaryTargets
:prisma-client-js
的引擎二进制目标(例如,如果你部署到 Ubuntu 18+,则为debian-openssl-1.1.x
;如果你在本地工作,则为native
)
generator client {
provider = "prisma-client-js"
previewFeatures = ["sample-preview-feature"]
binaryTargets = ["debian-openssl-1.1.x"] // defaults to `"native"`
}
二进制目标
自 v6.7.0 起,Prisma ORM 拥有 queryCompiler
预览功能。
启用后,你的 Prisma Client 将不带基于 Rust 的查询引擎二进制文件生成。:
generator client {
provider = "prisma-client-js"
previewFeatures = ["queryCompiler", "driverAdapters"]
}
请注意,驱动适配器预览功能是 queryCompiler
必需的。
当使用 queryCompiler
预览功能时,binaryTargets
字段已过时,不再需要。
prisma-client-js
生成器使用多个引擎。引擎是用 Rust 实现的,以可执行的、平台依赖的引擎文件的形式被 Prisma Client 使用。根据你执行代码的平台,你需要正确的文件。“二进制目标”用于定义目标平台应该存在哪些文件。
正确的文件在你将应用程序部署到生产环境时尤为重要,因为生产环境通常与本地开发环境不同。
native
二进制目标
native
二进制目标是特殊的。它不映射到具体的操作系统。相反,当 binaryTargets
中指定 native
时,Prisma Client 会检测当前操作系统并自动为其指定正确的二进制目标。
例如,假设你正在运行 macOS 并指定了以下生成器
generator client {
provider = "prisma-client-js"
binaryTargets = ["native"]
}
在这种情况下,Prisma Client 会检测你的操作系统,并根据支持的操作系统列表找到正确的二进制文件。如果你使用 macOS Intel x86 (darwin
),则会选择为 darwin
编译的二进制文件。如果你使用 macOS ARM64 (darwin-arm64
),则会选择为 darwin-arm64
编译的二进制文件。
注意:
native
二进制目标是默认值。如果你希望包含用于部署到不同环境的额外二进制目标,则可以明确设置它。
prisma-client
(抢先体验)
新的 prisma-client
生成器在使用 Prisma ORM 跨不同 JavaScript 环境(例如 ESM、Bun、Deno 等)时提供了更大的控制和灵活性。
它将 Prisma Client 生成到你应用程序代码库中的自定义目录,该目录通过 generator
块上的 output
字段指定。这使你对生成的代码具有完全的可见性和控制。它还会将生成的 Prisma Client 库拆分为多个文件。
此生成器目前处于抢先体验阶段,它确保你可以完全按照自己的意愿打包应用程序代码,而无需依赖隐藏或自动行为。
以下是与 prisma-client-js
相比的主要区别
- 需要一个
output
路径;不再“神奇地”生成到node_modules
中 - 通过
moduleFormat
字段支持 ESM 和 CommonJS - 由于附加字段而更灵活
- 输出纯 TypeScript,它像你应用程序代码的其余部分一样进行打包
prisma-client
生成器将成为 Prisma ORM v7 的新默认值。
入门
按照以下步骤在你的项目中使用新的 prisma-client
生成器。
1. 在 schema.prisma
中配置 prisma-client
生成器
更新你的 generator
块
generator client {
provider = "prisma-client" // Required
output = "../src/generated/prisma" // Required path
}
output
选项是必需的,它告诉 Prisma ORM 将生成的 Prisma Client 代码放置在哪里。你可以选择任何适合你项目结构的位置。例如,如果你有以下布局
.
├── package.json
├── prisma
│ └── schema.prisma
├── src
│ └── index.ts
└── tsconfig.json
那么 ../src/generated/prisma
会将生成的代码放置在相对于 schema.prisma
的 src/generated/prisma
中。
2. 生成 Prisma Client
通过运行以下命令生成 Prisma Client
npx prisma generate
这会将 Prisma Client 的代码(包括查询引擎二进制文件)生成到指定的 output
文件夹中。
3. 将生成的目录从版本控制中排除
新生成器既包含 TypeScript 客户端代码,也包含查询引擎。将查询引擎包含在版本控制中可能会在不同机器上导致兼容性问题。为避免此问题,请将生成的目录添加到 .gitignore
中。
# Keep the generated Prisma Client + query engine out of version control
/src/generated/prisma
将来,当Prisma ORM 完全从 Rust 转换为 TypeScript 后,你可以安全地将生成的目录包含在版本控制中。
4. 在你的应用程序中使用 Prisma Client
导入 Prisma Client
生成 Prisma Client 后,从你指定的路径导入它
import { PrismaClient } from "./generated/prisma/client.js"
const prisma = new PrismaClient()
Prisma Client 现在可以在你的项目中使用。
导入生成的模型类型
如果你正在导入为模型生成的类型,可以如下操作
import { User, Post } from "./generated/prisma/models.js"
导入生成的枚举类型
如果你正在导入为枚举生成的类型,可以如下操作
import { Role } from "./generated/prisma/enums.js"
字段参考
在 generator client { ... }
块中使用以下选项。只有 output
是必需的。其他字段具有默认值或从你的环境和 tsconfig.json
中推断。
generator client {
// Required
provider = "prisma-client"
output = "../src/generated/prisma"
// Optional
runtime = "nodejs"
moduleFormat = "esm"
generatedFileExtension = "ts"
importFileExtension = "ts"
}
以下是 prisma-client
生成器的选项
选项 | 默认值 | 描述 |
---|---|---|
output (必需) | Prisma Client 生成的目录,例如 ../src/generated/prisma 。 | |
runtime | nodejs | 目标运行时环境。 支持的值 nodejs (别名 node ), deno , bun , deno-deploy , workerd (别名 cloudflare ), edge-light (别名 vercel ), react-native 。 |
moduleFormat | 从环境中推断 | 模块格式(esm 或 cjs )。确定使用 import.meta.url 还是 __dirname 。 |
generatedFileExtension | ts | 生成的 TypeScript 文件的文件扩展名(ts 、mts 、cts )。 |
importFileExtension | 从环境中推断 | 在import 语句中使用的文件扩展名。可以是 ts 、mts 、cts 、js 、mjs 、cjs ,或者为空(用于裸导入)。 |
输出拆分与类型导入
prisma-client-js
生成器曾将所有类型定义生成到一个 index.d.ts
文件中,这可能导致在大型 schema 下编辑器变慢(例如破坏自动补全)。
新的 prisma-client
生成器现在将生成的 Prisma Client 库拆分为多个文件,从而避免了单个大型输出文件的问题。
之前 (prisma-client-js
)
generated/
└── prisma
├── client.ts
├── index.ts # -> this is split into multiple files in 6.7.0
└── libquery_engine-darwin.dylib.node
之后 (prisma-client
)
generated/
└── prisma
├── client.ts
├── commonInputTypes.ts
├── enums.ts
├── internal
│ ├── class.ts
│ └── prismaNamespace.ts
├── libquery_engine-darwin.dylib.node
├── models
│ ├── Post.ts
│ └── User.ts
└── models.ts
社区生成器
如果你正在使用多文件 Prisma schema,现有的或新的生成器应该不会受到影响,除非生成器手动读取 schema。
以下是社区创建的生成器列表。
prisma-dbml-generator
:将 Prisma schema 转换为数据库标记语言 (DBML),便于进行可视化表示prisma-docs-generator
:为 Prisma Client 生成独立的 API 参考prisma-json-schema-generator
:将 Prisma schema 转换为JSON schemaprisma-json-types-generator
:为所有数据库的强类型Json
字段添加支持。它在prisma-client-js
输出中更改 json 字段以匹配你提供的类型。有助于代码生成器、智能感知等。所有这些都不会影响任何运行时代码。typegraphql-prisma
:为 Prisma 模型生成 TypeGraphQL CRUD 解析器typegraphql-prisma-nestjs
:typegraphql-prisma
的一个分支,也为 Prisma 模型生成 CRUD 解析器,但专为 NestJS 而设计prisma-typegraphql-types-gen
:从你的 prisma 类型定义中生成 TypeGraphQL 类类型和枚举,生成的输出可以编辑而不会被下次生成覆盖,并且当你编辑类型时,它能够纠正你的错误。nexus-prisma
:允许通过 GraphQL Nexus 将 Prisma 模型投射到 GraphQLprisma-nestjs-graphql
:从 Prisma Schema 生成对象类型、输入、参数等,用于@nestjs/graphql
模块prisma-appsync
:为 AWS AppSync 生成一个功能齐全的 GraphQL APIprisma-kysely
:为 Kysely(一个 TypeScript SQL 查询构建器)生成类型定义。这对于从边缘运行时对数据库执行查询,或者编写在 Prisma 中无法实现但又不想放弃类型安全的更复杂 SQL 查询很有用。prisma-generator-nestjs-dto
:生成带有关系connect
和create
选项的 DTO 和 Entity 类,用于 NestJS Resources 和 @nestjs/swagger。prisma-erd-generator
:生成实体关系图prisma-generator-plantuml-erd
:为 PlantUML 生成 ER 图的生成器。通过激活选项也可以生成 Markdown 和 Asciidoc 文档。prisma-class-generator
:从你的 Prisma Schema 生成可用于 DTO、Swagger Response、TypeGraphQL 等的类。zod-prisma
:从你的 Prisma 模型创建 Zod schema。prisma-pothos-types
:使定义基于 Prisma 的对象类型变得更容易,并有助于解决关系的 n+1 查询问题。它还集成了 Relay 插件,使节点和连接的定义变得简单高效。prisma-generator-pothos-codegen
:自动生成输入类型(用作参数),并自动生成解耦的类型安全基础文件,使得从 Prisma schema 为 Pothos 创建可自定义的对象、查询和突变变得容易。可以选择一次性从基础文件生成所有 CRUD。prisma-joi-generator
:从你的 Prisma schema 生成完整的 Joi schema。prisma-yup-generator
:从你的 Prisma schema 生成完整的 Yup schema。prisma-class-validator-generator
:从你的 Prisma schema 发出带有现成 class validator 验证的 TypeScript 模型。prisma-zod-generator
:从你的 Prisma schema 发出 Zod schema。prisma-trpc-generator
:发出完全实现的 tRPC 路由。prisma-json-server-generator
:发出一个可以与 json-server 一起运行的 JSON 文件。prisma-trpc-shield-generator
:从你的 Prisma schema 发出一个 tRPC shield。prisma-custom-models-generator
:根据 Prisma 推荐,从你的 Prisma schema 发出自定义模型。nestjs-prisma-graphql-crud-gen
:使用 NestJS 和 Prisma 从 GraphQL schema 生成 CRUD 解析器。prisma-generator-dart
:生成带有 to- 和 fromJson 方法的 Dart/Flutter 类文件。prisma-generator-graphql-typedef
:生成 GraphQL schema。prisma-markdown
:生成包含 ERD 图及其描述的 Markdown 文档。通过@namespace
注释标签支持 ERD 图的分页。prisma-models-graph
:为 schema 生成双向模型图,即使 schema 中没有定义严格关系,通过自定义 schema 注解也能工作。prisma-generator-fake-data
:为你的 Prisma 模型生成逼真的虚假数据,可用于单元/集成测试、演示等。prisma-generator-drizzle
:一个 Prisma 生成器,可以轻松生成 Drizzle schema。prisma-generator-express
:生成 Express CRUD 和 Router 生成器函数。prismabox
:从你的 Prisma 模型生成多功能typebox schema。prisma-generator-typescript-interfaces
:从你的 Prisma schema 生成零依赖的 TypeScript 接口。prisma-openapi
:从 Prisma 模型生成 OpenAPI schema。