Prisma Postgres 设置

这是一个流程型 skill，可指导你通过管理 API 预置新的 Prisma Postgres 数据库，并将其连接到本地项目。

适用场景

在以下情况下使用此 skill：

• 为项目设置新的 Prisma Postgres 数据库
• 创建 Prisma Postgres 项目并将其连接到本地
• 获取 Prisma Postgres 的连接字符串
• 通过管理 API 预置数据库（而非使用控制台 UI）

以下情况不得使用此 skill：

• 设置 CI/CD 预览数据库 — 使用 prisma-postgres-cicd
• 在应用中构建多租户数据库预置功能 — 使用 prisma-postgres-integrator
• 处理已存在且已连接的数据库（架构/迁移任务属于标准 Prisma CLI 操作）

前提条件

• Node.js 18+
• 一个 Prisma Postgres 工作区（如有需要，可访问 <https://console.prisma.io> 创建）
• 一个工作区服务令牌（请参阅 references/auth.md）

UX 指南

向用户提供选项时（选择区域、删除项目等），使用所在平台的交互式选择机制（例如 Claude Code 中的 ask 工具，或其他 agents 中的结构化 Prompt）。不要输出静态表格并要求用户输入值 — 应提供可选择的选项，让用户能够轻松完成选择。

工作流

按顺序执行以下步骤。每个步骤都包含要发起的 API 调用以及响应处理方式。

步骤 1：身份验证

你需要一个服务令牌。请按顺序尝试以下方法：

1a. 用户 Prompt 中的令牌

检查用户的初始消息中是否包含服务令牌（例如，“使用令牌 eyJ... 设置 Prisma Postgres”）。如果包含，请严格按原样使用 — 不得将其截断、重新编码或通过文件进行往返传递。将其存入 shell 变量，供后续调用使用。

1b. 环境中的令牌

检查环境或 .env 文件中是否存在 PRISMA_SERVICE_TOKEN。

1c. 要求用户创建令牌

如果没有可用令牌，请指示用户：

在 Prisma 控制台 → 工作区设置 → 服务令牌中创建服务令牌。

复制该令牌并将其粘贴到这里。

有关创建服务令牌的详细信息，请阅读 references/auth.md。

获取令牌后，将其存入 shell 变量（PRISMA_SERVICE_TOKEN），并用于后续所有 API 调用。

步骤 2：列出可用区域

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

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：创建包含数据库的项目

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：创建命名连接（可选）

如果需要专用连接（例如每位开发者或每个环境分别使用一个连接），请创建一个：

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：配置本地项目

1. 安装依赖项：

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

以下五个软件包均为必需项：

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

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

DATABASE_URL="<direct-connection-string>"

1. 验证 .gitignore 中包含 .env。如果 .gitignore 不存在，请创建该文件。如果 .env 未被 Git 忽略，请警告用户。

1. 确保 package.json 中已设置 "type": "module"（Prisma 7 会生成 ESM 格式的输出）。

1. 如果 prisma/schema.prisma 不存在，请运行 npx prisma init 为项目生成脚手架。此操作会同时创建 prisma/schema.prisma 和 prisma.config.ts。

1. 确保 schema.prisma 使用 postgresql 作为提供程序，且数据源块中不包含 url 或 directUrl（Prisma 7 在 prisma.config.ts 中管理连接 URL，而不是在模式中）：

datasource db {
  provider = "postgresql"
}

1. 确保 prisma.config.ts 从环境中加载连接 URL：

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 中的提供程序必须为 "postgresql"（而不是 "prismaPostgres"）
• 要加载 .env 变量，必须在 prisma.config.ts 中导入 dotenv/config

步骤 6：定义模式并推送

如果模式中已有模型，则跳到推送步骤。否则，以交互式菜单的形式呈现以下选项：

1. “我会手动定义模式”——告知用户编辑 prisma/schema.prisma，准备好后再回来。在继续操作前等待用户回复。
2. “给我一个入门模式”——向 prisma/schema.prisma 中添加博客入门模式（包含相互关联的用户、文章和评论）。向用户展示添加的内容，并询问是否希望在推送前进行调整。
3. “我来描述我的需求”——请用户用自然语言描述其数据模型（例如：“我正在构建一个包含项目、任务和团队成员的任务管理器”）。根据描述生成模式并展示给用户，然后在推送前请求确认。

模式包含模型且用户准备好后，创建迁移并生成客户端：

npx prisma migrate dev --name init

此操作会在 prisma/migrations/ 中创建迁移文件，并在同一步骤中生成客户端。迁移历史对于 CI/CD 工作流（prisma migrate deploy）和生产部署至关重要。

仅当用户明确要求仅用于原型设计的模式（无迁移历史）时，才使用 npx prisma db push。在这种情况下，随后运行 npx prisma generate。

步骤 7：验证连接

生成客户端后，创建并运行一个快速验证脚本，确认所有功能均可端到端正常运行。此步骤至关重要——不得跳过。

创建名为 test-connection.ts 的文件：

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()

运行该脚本：

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 | 根据端点模式检查请求正文。常见问题包括：缺少 name、region 无效。 | | 429 | rate-limit-exceeded | 退避几秒后再重试。 |

参考文件

详细的 API 和使用信息位于：

references/auth.md             — Service token creation and usage
references/api-basics.md       — Base URL, envelope, IDs, errors, pagination
references/endpoints.md        — Endpoint details for projects, databases, connections, regions
references/prisma7-client.md   — Prisma 7 client instantiation and usage patterns