Wasp 中 Prisma Schema 文件（schema.prisma）完整指南：数据模型定义、Wasp 专属约束与 enum 实践

Wasp 中 Prisma Schema 文件schema.prisma完整指南数据模型定义、Wasp 专属约束与 enum 实践【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/waspWasp 基于 Prisma ORM 提供数据库能力开发者通过项目根目录下的schema.prisma文件以声明式语言定义应用数据模型。本指南围绕 Wasp 与 Prisma 的协作方式展开讲解datasource、generator、model、enum等核心配置块在 Wasp 中的使用规则、与main.wasp/main.wasp.ts中 Entities 的映射关系以及如何启用 Prisma 预览特性如 PostgreSQL 扩展。读完本文你将掌握在 Wasp 项目中正确编写、迁移和消费数据模型并在服务端与客户端代码中安全使用 Prisma enum 的完整方法。什么是schema.prismaWasp 数据模型的总入口Wasp 使用 Prisma 与数据库交互。Prisma 定位为下一代 Node.js 和 TypeScript ORM为数据库访问提供类型安全 API。在 Wasp 项目中你用 Prisma 的模式定义语言Prisma Schema Language在一个schema.prisma文件中声明应用的数据模型Wasp 读取该文件并据此生成与数据库交互所需的一切代码。在 Wasp 项目中schema.prisma位于项目根目录与main.wasp0.16 版及更早或main.wasp.tsTS Spec 版本平级. ├── main.wasp ... ├── schema.prisma ├── src ├── tsconfig.json └── vite.config.ts位置说明本文基于仓库中 web/versioned_docs/version-0.16/data-model/prisma-file.md对应使用main.wasp的 0.16 版本新版文档 web/docs/data-model/prisma-file.md 展示了基于 TS Specmain.wasp.ts的同类内容两者在 Prisma 文件规则上保持一致。当前文档versioned_docs/version-0.16 及更早版本使用main.wasp语法而 web/docs/data-model/entities.md 已更新为main.wasp.ts语法。Wasp 文件与 Prisma Schema 文件如何协同工作一个完整的示例schema.prisma下面是一个同时定义数据库选项和两个模型User与Task含一对多关系的schema.prisma示例datasource db { provider postgresql url env(DATABASE_URL) } generator client { provider prisma-client-js } model User { id Int id default(autoincrement()) tasks Task[] } model Task { id Int id default(autoincrement()) description String isDone Boolean default(false) user User relation(fields: [userId], references: [id]) userId Int }Wasp 读取这个文件并提取数据库模型与数据库配置信息datasource块定义你要使用的数据库类型此处为 PostgreSQL及其他选项generator块定义如何生成可在应用中用于访问数据库的 Prisma Client 代码每个model块对应一张数据库表字段即表的列relation与外键字段共同表达模型间的关联。下图展示了schema.prisma左侧蓝色区域含datasource、generators、models与main.wasp橙色区域及项目其他 JS/TS 文件之间的协作关系Prisma 模型被提取为 Wasp Entities进而被main.wasp中的 operations、apis 等功能引用最终与业务逻辑文件结合生成完整应用。从 Prisma 模型到 Wasp EntitiesPrisma 模型最终成为 Wasp Entities可被main.wasp文件引用。例如在查询、后台任务和 API 中声明对Task实体的访问app myApp { wasp: { version: {latestWaspVersion} }, title: My App, } ... // Using Wasp Entities in the Wasp file query getTasks { fn: import { getTasks } from src/queries, // highlight-next-line entities: [Task] } job myJob { executor: PgBoss, perform: { fn: import { foo } from src/workers/bar }, // highlight-next-line entities: [Task], } api fooBar { fn: import { fooBar } from src/apis, // highlight-next-line entities: [Task], httpRoute: (GET, /foo/bar/:email) }在getTasks查询的实现中Task是一个 Wasp Entity与schema.prisma中定义的Task模型一一对应myJob后台任务与fooBarAPI 中的Task同样是实体引用。基于 TS Spec 的新版语法见 web/docs/data-model/prisma-file.md则以query(getTasks, { entities: [Task] })、job(foo, { executor: PgBoss, entities: [Task] })、api(GET, /foo/bar/:email, fooBar, { entities: [Task] })的形式表达相同的实体依赖。仓库中的真实示例印证了这一协作模式。以 examples/waspello/schema.prisma 为例其中User、List、Card三个模型通过外键与反向引用构成了完整的看板数据模型datasource db { provider postgresql url env(DATABASE_URL) } generator client { provider prisma-client-js } // Entities model User { id Int id default(autoincrement()) lists List[] cards Card[] } model List { id Int id default(autoincrement()) name String pos Float // List has a single author. user User relation(fields: [userId], references: [id]) userId Int cards Card[] } model Card { id Int id default(autoincrement()) title String pos Float // Card belongs to a single list. list List relation(fields: [listId], references: [id]) listId Int // Card has a single author. author User relation(fields: [authorId], references: [id]) authorId Int }概念辨析Wasp Entity与Prisma model目前一一对应但 Entity 是 Wasp 层面的更高层抽象。当前定义 Prisma model 是创建 Entity 的唯一方式Wasp 未来可能扩展 Entity 的定义方式与能力详见 Entities 页面。Wasp 专属的 Prisma 配置规则Wasp 允许你像在任何普通 JS/TS 项目中一样使用 Prisma Schema 文件但有以下几条 Wasp 专属规则需要遵守。datasource块datasource db { provider postgresql url env(DATABASE_URL) }Wasp 会原样采用你书写的datasource但必须满足两个约束provider只能取postgresql或sqlite因为 Wasp 目前仅支持 PostgreSQL 与 SQLite 两种数据库url必须设置为env(DATABASE_URL)Wasp 才能正常与你的数据库协作。从源码看这两个取值正是 Wasp 在 PSLPrisma Schema Language层面对数据库提供者的硬编码约束waspc/src/Wasp/Psl/Db.hs 中定义了dbProviderPostgresqlStringLiteral postgresql与dbProviderSqliteStringLiteral sqlite两个字符串字面量数据库提供者也会进入编译产物仓库脚本 scripts/get-wasp-database-provider.sh 通过wasp show spec --json输出中的.dbSystem字段提取当前项目使用的数据库提供者postgresql或sqlite供部署等自动化流程使用。SQLite 用法可见教程示例 examples/tutorials/TodoApp/schema.prisma 与 examples/tutorials/TodoAppTs/schema.prisma二者均以provider sqliteurl env(DATABASE_URL)开头并在注释中注明Wasp requires that the url is set to the DATABASE_URL environment variable。对应的迁移锁文件如 examples/tutorials/TodoApp/migrations/migration_lock.toml也会记录provider sqlite。generator块generator client { provider prisma-client-js }Wasp 要求schema.prisma中必须存在一个provider prisma-client-js的generator块。若项目需要你也可以在此基础上添加额外的 generator。model块model User { id Int id default(autoincrement()) tasks Task[] } model Task { id Int id default(autoincrement()) description String isDone Boolean default(false) user User relation(fields: [userId], references: [id]) userId Int }只要代码是合法的 Prisma SchemaWasp 都会接受——你可以用任何你喜欢的方式定义模型。定义好实体后通过wasp db migrate-dev同步数据库模型并生成迁移脚本迁移脚本自动落入migrations/目录务必将该目录提交到版本控制详见 Entities 文档。enum块随着应用复杂度上升你可能希望用 Prismaenum更精确地刻画领域模型。例如Task模型原本用布尔型isDone表示完成状态现在要扩展为未开始 / 进行中 / 已完成三种状态可将字段迁移为更富表达力的枚举类型enum TaskStatus { NotStarted Doing Done } model Task { ... state TaskStatus default(NotStarted) }使用前请确认 Prisma 的 enum 与你的目标数据库兼容。只要对 Prisma 可用对 Wasp 就同样可用。在服务端代码中使用 enum需要从服务端访问 enum 的取值时可直接从prisma/client导入。结合 Wasp Entities 类型JS 中来自wasp/entitiesTS 中另加wasp/server/operations的操作类型即可写出类型安全的查询import { TaskState } from prisma/client; import { Task } from wasp/entities; export const getOpenTasks async (args, context) { return context.entities.Task.findMany({ orderBy: { id: asc }, where: { NOT: { state: TaskState.Done } }, }); };import { TaskState } from prisma/client; import { Task } from wasp/entities; import { type GetTasks } from wasp/server/operations; export const getOpenTasks: GetTasksvoid, Task[] async (args, context) { return context.entities.Task.findMany({ orderBy: { id: asc }, where: { NOT: { state: TaskState.Done } }, }); };在客户端代码中使用 enumenum 同样可以在客户端代码中访问——尽管 Prisma Client 不出现在客户端你仍可导入prisma/client以获取类型定义尤其是enum用于渲染和判断逻辑import { TaskState } from prisma/client; const TaskRow ({ task }) { return ( div input typecheckbox id{String(task.id)} checked{task.state TaskState.Done} / {task.description} /div ); };import { TaskState } from prisma/client; import { Task } from wasp/entities; const TaskRow ({ task }: { task: Task }) { return ( div input typecheckbox id{String(task.id)} checked{task.state TaskState.Done} / {task.description} /div ); };补充说明来自 Entities 文档Prisma Client 本身不可在客户端代码中使用但为了读取类型定义尤其是enum你仍可以在客户端导入prisma/client。关于///三斜杠注释的注意事项Wasp 尚未完全支持schema.prisma文件中的///注释语法。具体来说前导位置位于字段声明之前的///注释可以正常使用而尾随位置与字段声明同行、位于声明之后的///注释目前不被支持。model User { /// The unique identifier for the user. id Int id default(autoincrement()) }model User { id Int id default(autoincrement()) /// This is not supported }该限制在 0.16 文档中被描述为尚未完全支持后续版本见 web/docs/data-model/prisma-file.md则明确区分了前导与尾随两种位置前导///可用尾随///不可用。Prisma 预览特性以 PostgreSQL 扩展为例Prisma 仍处于活跃开发中部分特性尚未稳定。要在schema.prisma中启用各类预览特性需要在generator块中加入previewFeatures字段。一个实用的例子是 PostgreSQL 扩展支持postgresqlExtensions预览特性它允许你在数据库 schema 中使用pg_vector、pg_trgm等 PostgreSQL 扩展datasource db { provider postgresql url env(DATABASE_URL) extensions [pgvector(map: vector)] } generator client { provider prisma-client-js previewFeatures [postgresqlExtensions] } // ...启用后datasource块的extensions字段如pgvector(map: vector)声明要使用的扩展generator块中的previewFeatures数组登记对应预览特性名。关于预览特性与 PostgreSQL 扩展的更多细节可参考 Prisma 官方文档。仓库中的 examples/ask-the-documents/schema.prisma 正是这一写法的完整实战范例——它同时声明了extensions [pgvector(map: vector)]与previewFeatures [postgresqlExtensions]并在Document模型中使用embedding Unsupported(vector(1536))字段存储向量数据datasource db { provider postgresql url env(DATABASE_URL) extensions [pgvector(map: vector)] } generator client { provider prisma-client-js previewFeatures [postgresqlExtensions] } model User { id Int id default(autoincrement()) email String? } model Document { id String id default(uuid()) title String url String unique content String embedding Unsupported(vector(1536)) createdAt DateTime default(now()) updatedAt DateTime updatedAt }这也印证了预览特性规则只要对 Prisma 可用对 Wasp 就同样可用previewFeatures原样传递给 PrismaUnsupported(...)类型同样按 Prisma 语义处理可用于向量检索pgvector等高级场景。总结在 Wasp 项目中schema.prisma是数据模型的唯一事实来源位置与角色位于项目根目录Wasp 读取它来理解应用数据模型并生成数据库交互代码与 Wasp 的映射每个 Prismamodel即一个 Wasp Entity可在main.wasp或新版main.wasp.ts的查询、操作、后台任务、API 中通过entities: [...]声明依赖专属约束datasource.provider仅限postgresql或sqliteurl必须为env(DATABASE_URL)必须存在provider prisma-client-js的generator块model与enum遵循合法 Prisma 即合法 Wasp原则enum 使用服务端与客户端均可从prisma/client导入 enum 取值客户端导入仅用于类型/常量不可使用 Prisma Client预览特性通过generator.previewFeatures启用datasource.extensions声明扩展ask-the-documents 示例展示了 pgvector 的端到端用法三斜杠注释仅前导位置的///注释受支持尾随位置不可用。需要深入了解 Entity 与 Prisma 模型的映射关系可继续阅读 Entities 文档想查看基于 TS Spec 的最新版本写法可对照 web/docs/data-model/prisma-file.md。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考