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. ユーザーのプロンプトにトークンがある場合

ユーザーの初期メッセージにサービストークンが含まれているかを確認します (例: "Set up Prisma Postgres with token eyJ...")。含まれている場合は、提供されたとおりに正確に使用してください — 切り詰めたり、再エンコードしたり、ファイル経由で往復させたりしないでください。後続の呼び出し用にシェル変数に保存します。

1b. 環境にトークンがある場合

環境変数またはファイル内の PRISMA_SERVICE_TOKEN を確認してください。

1c. ユーザーに作成するよう依頼する

トークンが利用できない場合、ユーザーに以下のように指示してください：

Prisma Console → Workspace Settings → Service Tokens でサービストークンを作成してください。 トークンをコピーしてここに貼り付けてください。

詳細は references/auth.md を参照してください。

トークンを取得したら、シェル変数 (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

5 つのパッケージすべてが必須です：

• prisma — マイグレーション、スキーマプッシュ、クライアント生成用の CLI
• @prisma/client — 生成されたクエリクライアント
• @prisma/adapter-pg — 直接 PostgreSQL 接続用の Prisma 7 ドライバアダプター
• 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 に postgresql プロバイダーがあり、datasource ブロックに url または directUrl がないことを確認してください (Prisma 7 は接続 URL を prisma.config.ts で管理し、スキーマでは管理しません)：

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" ではない) である必要があります
• .env 変数を読み込むために、prisma.config.ts で dotenv/config をインポートする必要があります

ステップ 6: スキーマを定義してプッシュ

スキーマに既にモデルがある場合は、プッシュへスキップしてください。そうでない場合は、以下のオプションをインタラクティブメニューとして提示してください：

1. "I'll define my schema manually" (スキーマを手動で定義します) — ユーザーに prisma/schema.prisma を編集してから戻るよう指示してください。その前に待機してください。
2. "Give me a starter schema" (スターター スキーマをください) — ブログ スターター スキーマ (ユーザー、投稿、コメント、リレーション付き) を prisma/schema.prisma に追加してください。ユーザーに追加されたものを表示し、プッシュ前に調整したいかどうかを確認してください。
3. "I'll describe what I need" (必要なものを説明します) — ユーザーに自然言語でデータモデルを説明するよう依頼してください (例: "I'm building a task manager with projects, tasks, and team members")。説明からスキーマを生成し、表示して、プッシュ前に確認を求めてください。

スキーマにモデルがあり、ユーザーが準備完了したら、マイグレーションを作成してクライアントを生成してください：

npx prisma migrate dev --name init

これにより、マイグレーション ファイルが prisma/migrations/ に作成され、クライアントが 1 ステップで生成されます。マイグレーション履歴は CI/CD ワークフロー (prisma migrate deploy) と本番環境へのデプロイに不可欠です。

ユーザーが明示的にプロトタイピング専用モード (マイグレーション履歴なし) をリクエストした場合のみ npx prisma db push を使用してください。その場合は npx prisma generate で続けてください。

ステップ 7: 接続を確認

クライアント生成後、すべてが end-to-end で機能することを確認するための簡単な検証スクリプトを作成して実行してください。これは重要です — このステップをスキップしないでください。

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 を参照してください。

エラー処理

完全なエラー リファレンスは references/api-basics.md を参照してください。主要な自己修正パターン：

HTTP ステータス	エラーコード	アクション
401	authentication-failed	サービストークンが無効または期限切れです。ユーザーに Console → Workspace Settings → Service Tokens で新しいトークンを作成するよう依頼してください。
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 クライアント インスタンス化と使用パターン