## 什么是 Prisma？ Prisma ORM 是一个**新一代 ORM**，由以下工具组成： - [**Prisma Client**](https://www.prisma.io/docs/orm/prisma-client)：为 Node.js 和 TypeScript 自动生成的、类型安全的查询构建器 - [**Prisma Migrate**](https://www.prisma.io/docs/orm/prisma-migrate)：声明式数据建模和迁移系统 - [**Prisma Studio**](https://github.com/prisma/studio)：用于查看和编辑数据库中数据的 GUI Prisma Client 可以用于_任何_ Node.js 或 TypeScript 后端应用程序（包括 serverless 应用程序和微服务）。这可以是一个 [REST API](https://www.prisma.io/docs/concepts/overview/prisma-in-your-stack/rest)、[GraphQL API](https://www.prisma.io/docs/concepts/overview/prisma-in-your-stack/graphql)、gRPC API 或其他任何需要数据库的应用。 **如果您需要与 Prisma ORM 一起使用的数据库，请查看 [Prisma Postgres](https://www.prisma.io/docs/getting-started/prisma-orm/quickstart/prisma-postgres?utm_source=github&utm_medium=prisma-readme)；或者如果您正在寻找我们的 MCP Server，请前往[这里](https://github.com/prisma/mcp)。** ## 快速开始 ### 快速入门 (5分钟) 开始使用 Prisma 最快的方式是遵循快速入门指南。您可以选择以下两种数据库之一： - [Prisma Postgres](https://www.prisma.io/docs/getting-started/prisma-orm/quickstart/prisma-postgres) - [SQLite](https://www.prisma.io/docs/getting-started/prisma-orm/quickstart/sqlite) ### 使用您自己的数据库 如果您已经有了自己的数据库，可以按照以下指南操作： - [将 Prisma 添加到现有项目](https://www.prisma.io/docs/getting-started/prisma-orm/add-to-existing-project/postgresql) - [使用 Prisma 从零开始搭建新项目](https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-postgresql) ## Prisma ORM 的工作原理 本节提供了关于 Prisma ORM 工作原理及其最重要技术组件的概述。如需更详细的介绍，请访问 [Prisma 文档](https://www.prisma.io/docs/)。 ### Prisma schema 每个使用 Prisma 工具集中工具的项目都以一个 [Prisma schema 文件](https://www.prisma.io/docs/orm/prisma-schema)开始。Prisma schema 允许开发者使用直观的数据建模语言定义其_应用模型_并配置_生成器_。 ``` // Data source datasource db { provider = "postgresql" } // Generator generator client { provider = "prisma-client" output = "../generated" } // Data model 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[] } ``` 在这个 schema 中，您需要配置三项内容： - **Data source**：指定您的数据库类型，从而定义您可以在 schema 中使用的功能和数据类型 - **Generator**：指示您想要生成 Prisma Client - **Data model**：定义您的应用模型 ### `prisma.config.ts` 数据库连接详细信息通过 [`prisma.config.ts`](https://www.prisma.io/docs/orm/prisma-schema/prisma-config-reference) 定义。 ``` 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`](https://www.npmjs.com/package/dotenv) 或 [`@dotenvx/dotenvx`](https://www.npmjs.com/package/@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 --interactive ``` ### Prisma 数据模型 本页的重点是数据模型。您可以在各自的文档页面上了解更多关于 [Data source](https://www.prisma.io/docs/orm/prisma-schema/overview/data-sources) 和 [Generators](https://www.prisma.io/docs/orm/prisma-schema/overview/generators) 的信息。 #### Prisma 模型的功能 数据模型是 [模型](https://www.prisma.io/docs/orm/prisma-schema/data-model/models) 的集合。模型有两个主要功能： - 表示底层数据库中的一个表 - 为 Prisma Client API 中的查询提供基础 #### 获取数据模型 将数据模型“获取”到您的 Prisma schema 中有两种主要工作流程： - 通过[内省](https://www.prisma.io/docs/orm/prisma-schema/introspection)数据库生成数据模型 - 手动编写数据模型，并使用 [Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate) 将其映射到数据库 一旦定义了数据模型，您就可以[生成 Prisma Client](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client)，它将为定义的模型公开 CRUD 及更多查询。如果您使用的是 TypeScript，您将获得所有查询的完全类型安全（即使仅检索模型字段的子集时也是如此）。 ### 使用 Prisma Client 访问您的数据库 #### 第 1 步：安装 Prisma 首先，将 Prisma CLI 作为开发依赖项安装，并安装 Prisma Client： ``` npm install prisma --save-dev npm install @prisma/client ``` #### 第 2 步：设置您的 Prisma schema 确保您的 Prisma schema 包含一个指定了 `output` 路径的 `generator` 块： ``` generator client { provider = "prisma-client" output = "../generated" } datasource db { provider = "postgresql" // mysql, sqlite, sqlserver, mongodb or cockroachdb } ``` #### 第 3 步：配置 Prisma Config 使用 `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 Config](https://www.prisma.io/docs/orm/reference/prisma-config-reference) 的信息和所有可用的配置选项。 #### 第 4 步：生成 Prisma Client 使用以下命令生成 Prisma Client： ``` npx prisma generate ``` 此命令会读取您的 Prisma schema，并将 Prisma Client 代码_生成_到您的生成器配置中 `output` 路径指定的位置。 在您更改数据模型后，需要手动重新生成 Prisma Client，以确保生成的代码得到更新： ``` npx prisma generate ``` 有关[“生成 Prisma Client”](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client)的更多信息，请参阅文档。 #### 第 5 步：使用 Prisma Client 向您的数据库发送查询 一旦生成了 Prisma Client，您就可以在代码中导入它并向您的数据库发送查询。 ##### 导入并实例化 Prisma Client 您可以从生成器配置中指定的输出路径导入并实例化 Prisma Client。在实例化 Client 时，您需要向其构造函数提供一个 [driver adapter](https://www.prisma.io/docs/orm/core-concepts/supported-databases/database-drivers#how-to-use-driver-adapters)。例如，当 PostgreSQL 使用 driver adapter 时： ``` 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`（通过导入 `dotenv/config`），使用 `tsx --env-file=.env`、`node --env-file=.env`，或者使用 Bun（它会自动加载 `.env`）。 现在您可以开始通过生成的 Prisma Client API 发送查询了，以下是一些查询示例。请注意，所有 Prisma Client 查询都返回_普通旧式 JavaScript 对象_。 在 [Prisma Client 文档](https://www.prisma.io/docs/orm/prisma-client)中了解更多关于可用操作的信息，或观看此[演示视频](https://www.youtube.com/watch?v=LggrE5kJ75I&list=PLn2e1F9Rfr6k9PnR_figWOcSHgc_erDr5&index=4)（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 时，此查询的结果将被_静态类型化_，因此您不会意外访问不存在的属性（并且任何拼写错误都会在编译时被捕获）。请在文档中的[生成类型的高级用法](https://www.prisma.io/docs/orm/prisma-client/type-safety/operating-against-partial-structures-of-model-types)页面上了解更多关于利用 Prisma Client 生成类型的信息。 ## 安全 如果您有安全问题需要报告，请通过 [security@prisma.io](mailto:security@prisma.io?subject=[GitHub]%20Prisma%202%20Security%20Report%20) 联系我们。 ## 支持 ### 提出关于 Prisma 的问题 您可以在 GitHub 上的 `prisma` 代码库中提出问题并发起关于 Prisma 相关主题的[讨论](https://github.com/prisma/prisma/discussions/)。 👉 [**提出问题**](https://github.com/prisma/prisma/discussions/new) ### 创建 Prisma 的 bug 报告 如果您看到错误消息或遇到问题，请务必创建一份 bug 报告！您可以在文档中找到[创建 bug 报告的最佳实践](https://www.prisma.io/docs/guides/other/troubleshooting-orm/creating-bug-reports)（例如提供额外的调试输出）。 👉 [**创建 bug 报告**](https://pris.ly/prisma-prisma-bug-report) ### 提交功能请求 如果 Prisma 目前没有某个功能，请务必查看 [roadmap](https://www.prisma.io/docs/more/roadmap)，看看该功能是否已经计划在将来推出。 如果 roadmap 上的功能关联到了 GitHub issue，请务必在该 issue 上留下一个 👍 反应，最好还能留下您对该功能的想法和评论！ 👉 [**提交功能请求**](https://github.com/prisma/prisma/issues/new?assignees=&labels=&template=feature_request.md&title=) ## 贡献 请参阅我们的[贡献指南](https://github.com/prisma/prisma/blob/main/CONTRIBUTING.md)和[贡献者行为准则](https://github.com/prisma/prisma/blob/main/CODE_OF_CONDUCT.md)。 ## 测试状态 - Prisma 测试状态： [](https://github.com/prisma/prisma/actions/workflows/test.yml?query=branch%3Amain) 目前 ORM 代码库中已禁用定时的 CI；测试工作流会在 push、pull request 和手动执行 `workflow_dispatch` 时运行。有关最近的运行情况，请查看 [Actions 选项卡](https://github.com/prisma/prisma/actions)。

标签：GNU通用公共许可证, MITM代理, Node.js, ORM, SOC Prime, TypeScript, 后端开发, 安全插件, 开发工具, 数据库, 测试用例