Prisma 快速入门
官网 • 文档 • 示例 • 博客 • Discord • Twitter • YouTube
什么是 Prisma？
Prisma ORM 是下一代对象关系映射（ORM）工具，由以下组件构成：
- Prisma Client：为 Node.js 和 TypeScript 自动生成的类型安全查询构建器。
- Prisma Migrate：声明式数据建模与迁移系统。
- Prisma Studio：用于查看和编辑数据库中数据的图形用户界面（GUI）。
Prisma Client 可用于任何 Node.js 或 TypeScript 后端应用程序（包括无服务器应用程序和微服务），比如 REST API、GraphQL API、gRPC API 或其他需要数据库的应用。如果你需要与 Prisma ORM 搭配使用的数据库，可以考虑 Prisma Postgres；若你在寻找 MCP 服务器，可点击此处。
快速开始
快速入门（5 分钟）
使用 Prisma 最快的入门方式是遵循快速入门指南。你可以选择以下两种数据库之一：
- Prisma Postgres
- SQLite
使用已有数据库
如果你已有自己的数据库，可以参考以下指南：
- 将 Prisma 添加到现有项目中
- 从头开始使用 Prisma 设置新项目
Prisma ORM 的工作原理
本节将对 Prisma ORM 的工作原理及其最重要的技术组件进行高层次概述。若需更深入的介绍，请访问 Prisma 文档。
Prisma 模式
每个使用 Prisma 工具包的项目都始于一个 Prisma 模式文件。Prisma 模式允许开发者使用直观的数据建模语言定义应用程序模型并配置生成器。
// 数据源 datasource db { provider = "postgresql" } // 生成器 generator client { provider = "prisma - client" output = "../generated" } // 数据模型 model Post { id Int @id @default(autoincrement()) title String content String? published Boolean @default(false) author User? @relation(fields: [authorId], references: [id]) authorId Int? } model User { id Int @id @default(autoincrement()) email String @unique name String? posts Post[] }在此模式中，你需要配置以下三项内容：
- 数据源：指定数据库类型，从而定义模式中可使用的特性和数据类型。
- 生成器：表明你希望生成 Prisma Client。
- 数据模型：定义应用程序模型。
prisma.config.ts
数据库连接细节通过 `prisma.config.ts` 定义。
import { defineConfig } from 'prisma/config' export default defineConfig({ datasource: { url: 'postgres://...', }, })如果你将数据库连接字符串存储在 `process.env` 中，可以使用 `env` 函数以类型安全的方式访问它，并在运行时缺少该字符串时抛出错误：
import { defineConfig, env } from 'prisma/config' export default defineConfig({ datasource: { url: env('DATABASE_URL'), }, })Prisma ORM 不会自动加载 `.env` 文件。如果你想从 `.env` 文件中填充环境变量，可以考虑使用 `dotenv` 或 `@dotenvx/dotenvx` 等包。这种情况下，配置文件可能如下所示：
import 'dotenv/config' import { defineConfig, env } from 'prisma/config' export default defineConfig({ datasource: { url: env('DATABASE_URL'), }, })若不使用 Docker 且无需任何配置即可启动本地 PostgreSQL 开发服务器，可运行 `prisma dev`：
npx prisma dev或者，在云端快速启动一个即时 Prisma Postgres® 数据库：
npx create - db --interactivePrisma 数据模型
本节重点介绍数据模型。你可以在相应的文档页面了解更多关于数据源和生成器的信息。
Prisma 模型的功能
数据模型是模型的集合。一个模型有两个主要功能：
- 表示底层数据库中的表。
- 为 Prisma Client API 中的查询提供基础。
获取数据模型
将数据模型“引入” Prisma 模式主要有两种工作流程：
- 通过对数据库进行内省来生成数据模型。
- 手动编写数据模型，并使用 Prisma Migrate 将其映射到数据库。
一旦定义了数据模型，就可以生成 Prisma Client，它将为定义的模型提供 CRUD 及更多查询功能。如果你使用 TypeScript，所有查询都将具有完整的类型安全性（即使只检索模型字段的子集）。
使用 Prisma Client 访问数据库
步骤 1：安装 Prisma
首先，将 Prisma CLI 作为开发依赖项安装，并安装 Prisma Client：
npm install prisma --save - dev npm install @prisma/client步骤 2：设置 Prisma 模式
确保你的 Prisma 模式包含一个指定输出路径的生成器块：
generator client { provider = "prisma - client" output = "../generated" } datasource db { provider = "postgresql" // mysql, sqlite, sqlserver, mongodb or cockroachdb }步骤 3：配置 Prisma
使用 `prisma.config.ts` 文件配置 Prisma CLI。该文件用于配置 Prisma CLI 的子命令，如 `migrate` 和 `studio`。在项目根目录下创建 `prisma.config.ts` 文件：
import { defineConfig, env } from 'prisma/config' type Env = { DATABASE_URL: string } export default defineConfig({ schema: 'prisma/schema.prisma', migrations: { path: 'prisma/migrations', }, datasource: { url: env('DATABASE_URL'), }, })注意：使用 `prisma.config.ts` 时，不会自动加载 `.env` 文件中的环境变量。你可以在配置文件顶部导入 `dotenv/config` 来使用 `dotenv`。对于 Bun，会自动加载 `.env` 文件。了解更多关于 Prisma 配置和所有可用配置选项的信息。
步骤 4：生成 Prisma Client
使用以下命令生成 Prisma Client：
npx prisma generate此命令会读取你的 Prisma 模式，并在生成器配置中指定的输出路径生成 Prisma Client 代码。更改数据模型后，需要手动重新生成 Prisma Client 以确保生成的代码得到更新：
npx prisma generate有关“生成 Prisma Client”的更多信息，请参考文档。
步骤 5：使用 Prisma Client 向数据库发送查询
生成 Prisma Client 后，你可以在代码中导入它并向数据库发送查询。
导入并实例化 Prisma Client
你可以从生成器配置中指定的输出路径导入并实例化 Prisma Client。实例化客户端时，需要向其构造函数提供一个驱动适配器。例如，使用 PostgreSQL 并搭配驱动适配器时：
import { PrismaClient } from './generated/client' import { PrismaPg } from '@prisma/adapter - pg' const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL }) const prisma = new PrismaClient({ adapter })为了加载环境变量，你可以通过导入 `dotenv/config` 使用 `dotenv`，也可以使用 `tsx --env - file=.env`、`node --env - file=.env` 或 Bun（它会自动加载 `.env` 文件）。
现在，你可以通过生成的 Prisma Client API 开始发送查询，以下是一些示例查询。请注意，所有 Prisma Client 查询都返回普通的 JavaScript 对象。在 Prisma Client 文档中了解更多可用操作，或观看这个演示视频（2 分钟）。
- 从数据库中检索所有 `User` 记录：
const allUsers = await prisma.user.findMany()- 在每个返回的 `User` 对象中包含 `posts` 关系：
const allUsers = await prisma.user.findMany({ include: { posts: true, }, })- 过滤所有包含“prisma”的 `Post` 记录：
const filteredPosts = await prisma.post.findMany({ where: { OR: [ { title: { contains: 'prisma' } }, { content: { contains: 'prisma' } }, ], }, })- 在同一查询中创建一个新的 `User` 和一个新的 `Post` 记录：
const user = await prisma.user.create({ data: { name: 'Alice', email: 'alice@prisma.io', posts: { create: { title: 'Join us for Prisma Day 2021', }, }, }, })- 更新现有的 `Post` 记录：
const post = await prisma.post.update({ where: { id: 42, }, data: { published: true, }, })在 TypeScript 中使用
请注意，在使用 TypeScript 时，此查询的结果将进行静态类型检查，这样你就不会意外访问不存在的属性（任何拼写错误都会在编译时被捕获）。在文档的“生成类型的高级用法”页面了解更多关于利用 Prisma Client 生成类型的信息。
社区
Prisma 拥有一个庞大且支持性强的应用开发者社区。你可以在 Discord 和 GitHub 上加入我们。
徽章
用 Prisma 构建了很棒的东西？🌟 使用这些徽章展示成果，非常适合放在你的 README 或网站上。
安全
如果你有安全问题需要报告，请发送邮件至 `security@prisma.io`。
支持
提问
你可以在 GitHub 上的 `prisma` 仓库中就 Prisma 相关主题提问并发起讨论。👉 [提问](链接需补充)
创建错误报告
如果你看到错误消息或遇到问题，请务必创建错误报告！你可以在文档中找到创建错误报告的最佳实践（如包含额外的调试输出）。👉 [创建错误报告](链接需补充)
提交功能请求
如果 Prisma 当前没有某个特定功能，请务必查看路线图，了解该功能是否已计划在未来实现。如果路线图上的功能链接到了一个 GitHub 问题，请务必在该问题上点 👍 并最好留下你对该功能的想法评论！👉 [提交功能请求](链接需补充)
贡献
请参考我们的贡献指南和贡献者行为准则。
测试状态
Prisma 测试状态：已安排。目前，ORM 仓库中的持续集成（CI）已禁用；测试工作流会在推送、拉取请求和手动触发工作流时运行。查看“Actions”选项卡以了解最近的运行情况。你对 Prisma ORM 有什么看法呢？
)
 agent和组件)