prisma-postgres-setup

Prisma Postgres 设置

过程性技能，指导您通过 Management API 预配置新的 Prisma Postgres 数据库并将其连接到本地项目。

何时使用

在以下情况下使用此技能：

• 为项目设置新的 Prisma Postgres 数据库
• 创建 Prisma Postgres 项目并本地连接
• 获取 Prisma Postgres 的连接字符串
• 通过 Management API（而非 Console UI）预配置数据库

不要在以下情况下使用此技能：

• 设置 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 工具，其他代理中的结构化提示）。不要打印静态表格并要求用户输入值 — 提供可选项，以便用户以最小努力进行选择。

工作流程

按顺序执行以下步骤。每个步骤包括要进行的 API 调用以及如何处理响应。

步骤 1：身份验证

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

1a. 用户提示中的令牌

检查用户是否在其初始消息中包含了服务令牌（例如，“使用令牌 eyJ... 设置 Prisma Postgres”）。如果是，完全按照提供的方式使用 — 不要截断、重新编码或通过文件往返。将其存储在 shell 变量中供后续调用使用。

1b. 环境中的令牌

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

1c. 要求用户创建一个

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

在 Prisma Console → 工作区设置 → 服务令牌中创建服务令牌。
复制令牌并粘贴到这里。

阅读 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": "<项目名称>",
    "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 设置，新项目不需要。

如果响应状态为 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 — Prisma 7 驱动程序适配器，用于直接 PostgreSQL 连接
• pg — Node.js PostgreSQL 驱动程序（由适配器使用）
• dotenv — 为 prisma.config.ts 加载 .env 变量

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

DATABASE_URL="<直接连接字符串>"

3. 验证 .gitignore 包含 .env。如果 .gitignore 不存在，则创建它。如果 .env 未被 gitignore，警告用户。

4. 确保 package.json 设置了 "type": "module"（Prisma 7 生成 ESM 输出）。

5. 如果 prisma/schema.prisma 不存在，运行 npx prisma init 来搭建项目。这将创建 prisma/schema.prisma 和 prisma.config.ts。

6. 确保 schema.prisma 具有 postgresql 提供程序，并且数据源块中没有 url 或 directUrl（Prisma 7 在 prisma.config.ts 中管理连接 URL，而不是在架构中）：

datasource db {
  provider = "postgresql"
}

7. 确保 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"）
• 必须在 prisma.config.ts 中导入 dotenv/config 以加载 .env 变量

步骤 6：定义架构并推送

如果架构已有模型，则跳过推送。否则，将这些选项呈现为交互式菜单：

1. “我将手动定义我的架构” — 告诉用户编辑 prisma/schema.prisma，准备好后再回来。在继续之前等待他们。
2. “给我一个入门架构” — 将 Blog 入门架构（User、Post、Comment 及其关系）添加到 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 — 在本地打开可视化数据浏览器
• Console： 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	服务令牌无效或已过期。要求用户在 Console → 工作区设置 → 服务令牌中创建一个新的。
404	resource-not-found	检查资源 ID 是否包含正确的前缀（proj_、db_、con_）。
422	validation-error	根据端点架构检查请求体。常见问题：缺少 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 客户端实例化和使用模式