用 Prisma Management API 从零创建…

当需要新建一个 Prisma Postgres 数据库、拿到直连字符串并把本地项目配置好时使用。

适用场景

解决思路

1. 按顺序执行以下步骤，每一步都包含要发起的 API 调用以及如何处理响应。
2. 第 1 步：认证。按顺序尝试以下方式获取 service token：1a. 检查用户提示中是否直接带了 service token（例如 "Set up Prisma Postgres with token eyJ..."），若有则原样使用——不要截断、重新编码或经由文件往返；把它存进 shell 变量供后续调用。1b. 检查环境变量或 .env 文件中的 PRISMA_SERVICE_TOKEN。1c. 若都没有，让用户去 Prisma Console → Workspace Settings → Service Tokens 创建 service token 并粘贴过来；详见 references/auth.md。拿到 token 后存入 shell 变量 PRISMA_SERVICE_TOKEN，用于后续所有 API 调用。
3. 第 2 步：列出可用区域。执行 curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" https://api.prisma.io/v1/regions/postgres，响应是包含 id、name、status 的区域数组，只展示 status 为 available 的区域，并以交互式菜单呈现让用户选择，而不是让用户手动输入 region ID；完整响应结构见 references/endpoints.md。
4. 第 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 连接字符串）。必须使用 direct 连接字符串（endpoints.direct.connectionString），不要用 pooled 或 accelerate 端点——那些是给旧版 Accelerate 用的，新项目不需要。若响应状态为 provisioning，等几秒后轮询 GET /v1/databases/<database-id> 直到 status 为 ready。若因数据库数量上限创建失败，列出用户已有项目并以交互式菜单呈现供删除，用户选定后删除并重试；完整请求/响应结构见 references/endpoints.md。
5. 第 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 提取直连字符串。
6. 第 5 步：配置本地项目。1) 安装依赖：npm install prisma @prisma/client @prisma/adapter-pg pg dotenv（五个包都必需：prisma 用于迁移/schema push/生成客户端，@prisma/client 是生成的查询客户端，@prisma/adapter-pg 是 Prisma 7 直连 PostgreSQL 的驱动适配器，pg 是适配器使用的 Node.js PostgreSQL 驱动，dotenv 为 prisma.config.ts 加载 .env 变量）。2) 把直连字符串写入 .env，若文件已存在则追加，不要覆盖已有条目：DATABASE_URL="<direct-connection-string>"。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 的 provider 为 postgresql，且 datasource 块中不要有 url 或 directUrl（Prisma 7 在 prisma.config.ts 而非 schema 中管理连接 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 的 provider 必须是 "postgresql"（不是 "prismaPostgres"）；必须在 prisma.config.ts 中 import 'dotenv/config' 以加载 .env 变量。
7. 第 6 步：定义 schema 并推送。若 schema 已有模型，直接跳到推送；否则以交互式菜单呈现以下选项：1) "我自己手动定义 schema"——告诉用户编辑 prisma/schema.prisma，完成后回来，等待用户再继续。2) "给我一个起步 schema"——向 prisma/schema.prisma 添加 Blog 起步 schema（User、Post、Comment 及关联），展示给用户并询问是否要在推送前调整。3) "我来描述需求"——让用户用自然语言描述数据模型（例如 "我在做一个带项目、任务和团队成员的任务管理器"），据此生成 schema，展示并确认后再推送。schema 有模型且用户就绪后，执行 npx prisma migrate dev --name init 创建迁移并生成客户端（一步完成，迁移文件生成在 prisma/migrations/，迁移历史对 CI/CD 流程 prisma migrate deploy 和生产部署至关重要）。仅当用户明确要求纯原型模式（无迁移历史）时才用 npx prisma db push，此时随后要执行 npx prisma generate。
8. 第 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 适配器包装；向 PrismaClient 构造函数传 { adapter }；不要用 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。
9. 错误处理（完整错误参考见 references/api-basics.md）：401 authentication-failed——service token 无效或过期，让用户去 Console → Workspace Settings → Service Tokens 新建一个；404 resource-not-found——检查资源 ID 是否带正确前缀（proj_、db_、con_）；422 validation-error——对照端点 schema 检查请求体，常见问题是缺 name、region 无效；429 rate-limit-exceeded——退避几秒后重试。
10. 向用户呈现选择（区域选择、删除项目等）时，使用所在平台的交互式选择机制（例如 Claude Code 的 ask 工具、其他 agent 的结构化提示），不要打印静态表格让用户输入值——呈现可选项让用户以最小成本挑选。

适用边界 · 注意事项

• 为 CI/CD 预览数据库做设置时——应使用 prisma-postgres-cicd。
• 要在应用内构建多租户数据库供给时——应使用 prisma-postgres-integrator。
• 数据库已存在且已连接时（schema/迁移任务属于标准 Prisma CLI 范畴）。