Prisma Postgres

面向交互式与程序化工作流的 Prisma Postgres 创建、管理和集成指导。

何时应用

在以下情况下参考此 skill：

• 从 Prisma Console 设置 Prisma Postgres
• 使用 create-db 预配即时临时数据库
• 使用 prisma postgres link 链接现有本地项目
• 通过 Management API 管理 Prisma Postgres 资源
• 在 TypeScript/JavaScript 中使用 @prisma/management-api-sdk
• 处理认领 URL、连接字符串、区域和认证流程

按优先级划分的规则类别

| 优先级 | 类别 | 影响 | 前缀 | |----------|----------|--------|--------| | 1 | CLI 预配 | 严重 | create-db-cli | | 2 | Management API | 严重 | management-api | | 3 | Management API SDK | 高 | management-api-sdk | | 4 | Console 与连接 | 高 | console-and-connections |

快速参考

• create-db-cli - 即时数据库和当前 CLI 标志（--ttl、--copy、--quiet、--open）
• management-api - 服务令牌和 OAuth API 工作流
• management-api-sdk - 带令牌存储的类型化 SDK 用法
• console-and-connections - Console 操作、prisma postgres link、直接 TCP 连接以及 serverless-driver 选择

核心工作流

1. Console 优先工作流

使用 Prisma Console 进行手动设置和操作：

• 打开 https://console.prisma.io
• 创建/选择工作区和项目
• 使用项目侧边栏中的 Studio 查看/编辑数据
• 从项目 UI 获取直接连接详情

2. 使用 create-db 快速预配

当你需要立即获得数据库时，使用 create-db：

npx create-db@latest

别名：

npx create-pg@latest
npx create-postgres@latest

对于应用集成，你还可以使用 create-db npm 包中的程序化 API（create() / regions()）。

临时数据库会在约 24 小时后自动删除，除非已被认领。

2b. 使用 Platform CLI 管理持久数据库

对于属于某个 Project 的数据库（不是临时的 create-db 数据库），使用 @prisma/cli：

npx -y @prisma/cli@latest database create --help
npx -y @prisma/cli@latest database list --json
npx -y @prisma/cli@latest database connection create db_123
npx -y @prisma/cli@latest database usage db_123
npx -y @prisma/cli@latest database backup list db_123

database create 和 database connection create 会打印一次性连接 URL；必须立即存储。破坏性命令（remove、restore）必须使用精确的 --confirm <id>。

对于自动化，请优先使用 --json --no-interactive，在变更前解析 ID，并验证已安装命令的 help，因为此 CLI 处于 beta 阶段。

3. 链接现有本地项目

当数据库已存在，并且你想把本地项目连接到它时，使用 prisma postgres link：

prisma postgres link

对于 CI 或其他非交互环境：

prisma postgres link --api-key "<your-api-key>" --database "db_..."

此流程会使用 DATABASE_URL 更新本地 .env，然后你可以运行 prisma generate 和 prisma migrate dev。

4. 使用 Management API 进行程序化预配

使用以下 API 端点：

https://api.prisma.io/v1

使用以下方式探索 schema 和端点：

• OpenAPI 文档：https://api.prisma.io/v1/doc
• Swagger Editor：https://api.prisma.io/v1/swagger-editor

认证选项：

• 服务令牌（工作区服务器到服务器）
• OAuth 2.0（代表用户执行操作）

5. 使用 Management API SDK 进行类型安全集成

安装并使用：

npm install @prisma/management-api-sdk

对于现有令牌，使用 createManagementApiClient；对于 OAuth + 令牌刷新，使用 createManagementApiSdk。

该 SDK 暴露了类型化的工作区服务令牌列表、创建和撤销路由。新创建的令牌值仅返回一次。应以已安装的 SDK 类型或 OpenAPI 文档为准，确定确切的 beta 端点形状。

规则文件

详细指导位于：

references/console-and-connections.md
references/create-db-cli.md
references/management-api.md
references/management-api-sdk.md

如何使用

从 references/create-db-cli.md 开始进行快速设置，然后当你需要程序化预配时，切换到 references/management-api.md 或 references/management-api-sdk.md。