快速入门
在本快速入门指南中,您将学习如何在纯 TypeScript 项目中从零开始使用 Prisma ORM 和 Prisma Postgres 数据库。它涵盖以下工作流程
- 创建 Prisma Postgres 数据库
- Schema 迁移和查询(通过 Prisma ORM)
- 连接池和缓存(通过 Prisma Accelerate)
- 实时数据库更改事件(通过 Prisma Pulse)
先决条件
要成功完成本教程,您需要
1. 在 Platform Console 中设置 Prisma Postgres 数据库
请按照以下步骤创建您的 Prisma Postgres 数据库
- 登录到并打开控制台。
- 在您选择的工作区中,单击 New project 按钮。
- 在 Name 字段中键入您的项目名称,例如 hello-ppg。
- 在 Prisma Postgres 部分,单击 Get started 按钮。
- 在 Region 下拉菜单中,选择离您当前位置最近的区域,例如 美国东部(弗吉尼亚北部)。
- 单击 Create project 按钮。
此时,您将被重定向到 Database 页面,您需要等待几秒钟,直到数据库状态从 PROVISIONING
更改为 CONNECTED
。
一旦绿色 CONNECTED
标签出现,您的数据库就可以使用了!
2. 下载示例并安装依赖项
复制控制台中显示的 try-prisma
命令,将其粘贴到您的终端并执行。
作为参考,以下是命令的样子
npx try-prisma@latest \
--template databases/prisma-postgres \
--name hello-prisma \
--install npm
一旦 try-prisma
命令终止,导航到项目目录
cd hello-prisma
3. 设置数据库连接 URL
与数据库的连接和 Pulse API 密钥通过 .env
文件中的环境变量进行配置。
首先,将现有的 .env.example
文件重命名为 .env
mv .env.example .env
然后,在 Platform 控制台中的项目环境中,在 Set up database access 部分找到您的数据库凭据,复制 DATABASE_URL
环境变量并将其粘贴到 .env
文件中。
作为参考,该文件现在应类似于这样
DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...."
PULSE_API_KEY=""
暂时不用担心 PULSE_API_KEY
环境变量,您稍后会设置它。
4. 创建数据库表(通过 schema 迁移)
接下来,您需要在数据库中创建表。您可以通过使用 Prisma CLI 的以下命令创建和执行 schema 迁移来完成此操作
npx prisma migrate dev --name init
这将把您的 Prisma schema 中定义的 User
和 Post
模型映射到您的数据库。您还可以查看已执行的 SQL 迁移,该迁移在新建的 prisma/migrations
目录中创建了表。
5. 使用 Prisma ORM 执行查询
src/queries.ts
脚本包含许多 CRUD 查询,这些查询将在您的数据库中写入和读取数据。您可以通过在终端中运行以下命令来执行它
npm run queries
脚本完成后,您可以检查终端中的日志或使用 Prisma Studio 来探索数据库中已创建的记录
npx prisma studio
6. 探索使用 Prisma Accelerate 进行缓存
src/caching.ts
脚本包含一个示例查询,该查询使用 Stale-While-Revalidate (SWR) 和 Time-To-Live (TTL) 来使用 Prisma Accelerate 缓存数据库查询。您可以按如下方式执行它
npm run caching
记下执行查询所花费的时间,例如
The query took 2009.2467149999998ms.
现在,再次运行脚本
npm run caching
您会注意到这次查询所花费的时间会短得多,例如
The query took 300.5655280000001ms.
7. 使用 Prisma Pulse 观察数据库中的实时事件
src/realtime.ts
脚本包含一个演示,用于通过 Prisma Pulse 从数据库接收实时更改 事件。
在运行它之前,您需要在控制台中启用 Prisma Postgres 的实时功能
- 重新打开您的项目.
- 在侧边栏中选择 Pulse 选项卡。
- 找到并单击 Enable Pulse 按钮。
- 在 Add Pulse to your application 部分中,单击 Generate API key 按钮。
- 复制
PULSE_API_KEY
环境变量并将其粘贴到您的.env
文件中。
作为参考,您的 .env
文件现在应类似于这样
DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=ey...."
PULSE_API_KEY="ey..."
您现在可以按如下方式启动脚本
npm run realtime
该脚本现在创建了一个 stream,它将接收数据库事件,并在 User
表上发生写入操作(即创建、更新或删除)时将其打印到控制台。
要测试 stream,您可以打开 Prisma Studio
npx prisma studio
... 并对 User
表进行更改,例如创建一个新记录。保存更改后,您应该在终端中看到类似于这样的输出
Received an event: {
action: 'create',
created: { id: 3, email: '[email protected]', name: 'Nikolas' },
id: '01JAFNSZHQRDTW773BCAA9G7FJ'
}
8. 后续步骤
在本快速入门指南中,您学习了如何在纯 TypeScript 项目中开始使用 Prisma ORM。您可以随意自行探索更多 Prisma Client API,例如,在 findMany
查询中包含过滤、排序和分页选项,或探索更多操作,如 update
和 delete
查询。
在 Prisma Studio 中探索数据
Prisma ORM 配备了一个内置 GUI,用于查看和编辑数据库中的数据。您可以使用以下命令打开它
npx prisma studio
使用 Prisma Postgres,您还可以在通过在您的项目中选择 Studio 选项卡来直接使用 Prisma Studio。
使用 Next.js 构建全栈应用程序
了解如何在全栈应用程序中使用 Prisma Postgres
探索即用型 Prisma ORM 示例
查看 GitHub 上的 prisma-examples
仓库,了解 Prisma ORM 如何与您最喜欢的库一起使用。该仓库包含 Express、NestJS、GraphQL 的示例,以及 Next.js 和 Vue.js 的全栈示例,以及更多内容。
这些示例默认使用 SQLite,但您可以按照项目 README 中的说明,通过几个简单的步骤切换到 Prisma Postgres。
加入 Prisma 社区 💚
Prisma 拥有庞大的开发者社区。在 Discord 上加入我们,或使用 GitHub Discussions 提问。