Prisma Postgres 搭建指南

这是一份流程化操作指南，可指导你通过Management API预配新的Prisma Postgres数据库并将其连接到本地项目。

适用场景

请在以下场景使用本指南：

为项目搭建新的Prisma Postgres数据库
创建Prisma Postgres项目并连接到本地环境
获取Prisma Postgres的连接字符串
通过Management API（而非控制台UI）预配数据库

请勿在以下场景使用本指南：

搭建CI/CD预览数据库 —— 请使用
```
prisma-postgres-cicd
```
在应用中内置多租户数据库预配功能 —— 请使用
```
prisma-postgres-integrator
```
处理已存在且已连接的数据库（schema/迁移任务属于标准Prisma CLI功能）

前置要求

Node.js 18+
Prisma Postgres工作区（如有需要可在https://console.prisma.io 创建）
工作区服务令牌（参考
```
references/auth.md
```
）

交互体验指南

向用户展示选择项（如区域选择、项目删除等）时，请使用你所在平台的交互式选择机制（例如Claude Code中的

ask

工具，其他Agent中的结构化提示）。不要输出静态表格然后要求用户手动输入值，而是提供可选择的选项，让用户可以轻松选择。

操作流程

请按顺序执行以下步骤，每个步骤都包含对应的API调用方法和响应处理方式。

步骤1：身份验证

你需要一个服务令牌，请按顺序尝试以下获取方式：

1a. 用户提示中的令牌

检查用户初始消息中是否包含服务令牌（例如「使用令牌eyJ...搭建Prisma Postgres」）。如果有，请完全按提供的内容使用——不要截断、重新编码，也不要通过文件中转。将其存储在shell变量中供后续调用使用。

1b. 环境中的令牌

检查环境或

.env

文件中是否存在

PRISMA_SERVICE_TOKEN

。

1c. 要求用户创建令牌

如果没有可用的令牌，告知用户：

请在Prisma控制台 → 工作区设置 → 服务令牌中创建服务令牌。复制令牌并粘贴到此处。

更多服务令牌创建的详情请查看

references/auth.md

。

获取令牌后，将其存储在shell变量(

PRISMA_SERVICE_TOKEN

)中，所有后续API调用都需要使用该令牌。

步骤2：列出可用区域

获取可用的Prisma Postgres区域列表，让用户选择部署位置。

bash

curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  https://api.prisma.io/v1/regions/postgres

响应包含区域数组，字段有

id

、

name

和

status

。仅展示

status

为

available

的区域。

将区域以交互式菜单的形式展示——让用户从选项中选择，而不是手动输入区域ID。

完整响应结构请查看

references/endpoints.md

。

步骤3：创建带数据库的项目

bash

curl -s -X POST https://api.prisma.io/v1/projects \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<project-name>",
    "region": "<region-id>",
    "createDatabase": true
  }'

默认使用当前目录名称作为项目名。

响应封装在

{ "data": { ... } }

中，提取：

```
data.id
```
—— 项目ID（前缀为
```
proj_
```
）
```
data.database.id
```
—— 数据库ID（前缀为
```
db_
```
）

data.database.connections[0].endpoints.direct.connectionString

—— 直连PostgreSQL连接字符串

请使用直连连接字符串(

endpoints.direct.connectionString

)。不要使用连接池或accelerate端点——这些是旧版Accelerate设置使用的，新项目不需要。

如果响应状态为

provisioning

，等待几秒后轮询

GET /v1/databases/<database-id>

，直到

status

变为

ready

。

如果因数据库配额不足创建失败，列出用户的现有项目，以交互式菜单形式供用户选择删除。用户选择后删除对应项目并重试。

完整请求/响应结构请查看

references/endpoints.md

。

步骤4：创建命名连接（可选）

如果需要专用连接（例如每个开发者/每个环境一个连接），可创建：

bash

curl -s -X POST https://api.prisma.io/v1/databases/<database-id>/connections \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "dev" }'

从

data.endpoints.direct.connectionString

中提取直连连接字符串。

步骤5：配置本地项目

安装依赖：

bash

npm install prisma @prisma/client @prisma/adapter-pg pg dotenv

所有五个包都是必须的：

```
prisma
```
—— 用于迁移、schema推送、客户端生成的CLI
```
@prisma/client
```
—— 生成的查询客户端
```
@prisma/adapter-pg
```
—— 用于直连PostgreSQL的Prisma 7驱动适配器
```
pg
```
—— Node.js PostgreSQL驱动（供适配器使用）
```
dotenv
```
—— 为
```
prisma.config.ts
```
加载
```
.env
```
变量

将直连连接字符串写入
```
.env
```
。如果文件已存在则追加内容——不要覆盖现有条目：

DATABASE_URL="<direct-connection-string>"

确认
```
.gitignore
```
包含
```
.env
```
。如果
```
.gitignore
```
不存在则创建。如果
```
.env
```
没有被git忽略，要警告用户。
确认
```
package.json
```
中设置了
```
"type": "module"
```
（Prisma 7生成ESM输出）。

如果

prisma/schema.prisma

不存在，运行

npx prisma init

生成项目框架。这会同时创建

prisma/schema.prisma

和

prisma.config.ts

。

确认
```
schema.prisma
```
使用
```
postgresql
```
provider，且数据源块中没有
```
url
```
或
```
directUrl
```
（Prisma 7在
```
prisma.config.ts
```
中管理连接URL，而不是在schema中）：

prisma

datasource db {
  provider = "postgresql"
}

确认
```
prisma.config.ts
```
从环境中加载连接URL：

typescript

import path from 'node:path'
import { defineConfig } from 'prisma/config'
import 'dotenv/config'

export default defineConfig({
  earlyAccess: true,
  schema: path.join(import.meta.dirname, 'prisma', 'schema.prisma'),
  datasource: {
    url: process.env.DATABASE_URL!,
  },
})

Prisma 7重要注意事项：

连接URL存放在
```
prisma.config.ts
```
中，永远不要放在
```
schema.prisma
```
里

schema.prisma

中的provider必须是

"postgresql"

（不是

"prismaPostgres"

）

必须在
```
prisma.config.ts
```
中导入
```
dotenv/config
```
来加载
```
.env
```
变量

步骤6：定义schema并推送

如果schema中已经有模型，跳过推送步骤。否则，将以下选项以交互式菜单形式展示：

「我要手动定义schema」 —— 告知用户编辑
```
prisma/schema.prisma
```
，准备好后再继续。等待用户操作完成后再执行下一步。
「给我一个入门schema」 —— 向
```
prisma/schema.prisma
```
中添加博客入门schema（带关联关系的User、Post、Comment模型）。向用户展示添加的内容，推送前询问是否需要调整。
「我要描述我的需求」 —— 让用户用自然语言描述他们的数据模型（例如「我要做一个任务管理器，包含项目、任务和团队成员」）。根据描述生成schema，展示给用户，推送前请求确认。

当schema中已有模型且用户确认就绪后，创建迁移并生成客户端：

bash

npx prisma migrate dev --name init

这一步会在

prisma/migrations/

中创建迁移文件，同时生成客户端。迁移历史对CI/CD工作流(

prisma migrate deploy

)和生产部署至关重要。

仅当用户明确要求仅用于原型模式（不需要迁移历史）时才使用

npx prisma db push

。这种情况下，执行完后需要接着运行

npx prisma generate

。

步骤7：验证连接

生成客户端后，创建并运行一个快速验证脚本，确认端到端流程正常运行。这一步至关重要——不要跳过。

创建名为

test-connection.ts

的文件：

typescript

import 'dotenv/config'
import pg from 'pg'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client.js'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

const result = await prisma.$queryRawUnsafe('SELECT 1 as connected')
console.log('Connected to Prisma Postgres:', result)

await prisma.$disconnect()
await pool.end()

运行：

bash

npx tsx test-connection.ts

Prisma 7客户端实例化规则：

从

./generated/prisma/client.js

导入（不是

./generated/prisma

）

使用
```
DATABASE_URL
```
连接字符串创建
```
pg.Pool
```
将其封装在
```
PrismaPg
```
适配器中
将
```
{ adapter }
```
传入
```
PrismaClient
```
构造函数
不要使用
```
datasourceUrl
```
——Prisma 7中没有这个选项
不要不带参数使用
```
new PrismaClient()
```
——会抛出异常

验证成功后，删除

test-connection.ts

。

然后分享链接供用户查看自己的数据库：

Prisma Studio（CLI）：
```
npx prisma studio
```
—— 本地打开可视化数据浏览器

控制台：

https://console.prisma.io/<workspaceId>/<projectId>/<databaseId>/dashboard

—— 去掉步骤3返回的ID前缀（

wksp_

、

proj_

、

db_

）来构建这个URL

完整的客户端实例化参考请查看

references/prisma7-client.md

。

错误处理

完整的错误参考请查看

references/api-basics.md

。关键的自动修正规则：

HTTP状态码	错误码	处理措施
401	`authentication-failed`	服务令牌无效或已过期。要求用户在控制台 → 工作区设置 → 服务令牌中创建新令牌。
404	`resource-not-found`	检查资源ID是否包含正确的前缀（ `proj_` 、 `db_` 、 `con_` ）。
422	`validation-error`	对照端点schema检查请求体。常见问题：缺少 `name` 、 `region` 无效。
429	`rate-limit-exceeded`	退避几秒后重试。

参考文件

详细的API和使用信息存放在：

references/auth.md             — 服务令牌创建和使用
references/api-basics.md       — 基础URL、封装结构、ID、错误、分页
references/endpoints.md        — 项目、数据库、连接、区域的端点详情
references/prisma7-client.md   — Prisma 7客户端实例化和使用模式

prisma-postgres-setup

NPX安装

标签

SKILL.md 内容（中文）

Prisma Postgres 搭建指南

适用场景

前置要求

交互体验指南

操作流程

步骤1：身份验证

步骤2：列出可用区域

步骤3：创建带数据库的项目

步骤4：创建命名连接（可选）

步骤5：配置本地项目

步骤6：定义schema并推送

步骤7：验证连接

错误处理

参考文件