prisma-compute

Prisma Compute

TypeScript アプリを Prisma Compute にデプロイし、その後運用します。すべてのデプロイは、Prisma Composer アプリ（module.ts のルートモジュール）と Prisma 8 CLI の prisma を経由します。

prisma 8.0.0-rc.21（@prisma/cli としても同一内容で公開）、@prisma/composer および @prisma/composer-prisma-cloud 0.28.0、@prisma/compute 0.1.0-beta.0、create-prisma 0.14.1 で検証済みです。コマンドの構成が rc.21 と一致する prisma 8.0.0-rc.23、および node() の dependencies オプション（0.29.0）を追加し、サポート対象の Node.js バージョンを絞った Composer 0.30.0 でも再確認済みです。CLI は頻繁に変わります。このスキルに記載のないフラグを使用する前に、npx prisma <group> --help を実行してください。

バージョンに対応したスキル

インストール済みのパッケージには、インストールされたバージョンに対応するエージェントスキルが含まれています。

• prisma-platform-core-concepts（prisma 内）：プロジェクト、ブランチ、サービス、バージョン、環境変数、プッシュ時のデプロイ。
• prisma-composer-core-concepts（@prisma/composer 内）：サービス、モジュール、データベース、ビルドの宣言、dev、deploy、およびティアダウン。

npx prisma skills sync を実行すると、エージェントのスキルディレクトリ（.claude/skills、.cursor/skills、.agents/skills、.devin/skills）にスキルがコピーされ、npx prisma skills list を実行すると、インストール済みのスキルが表示されます。npx prisma init も同じ処理を行い、スキルを最新に保つ postinstall フックを追加します。これらのスキルがインストールされている場合は、API の詳細に関してそれらを使用してください。このスキルでは、デプロイと運用のワークフロー、およびその注意点を扱います。

削除された機能

Composer 導入前の Compute CLI は廃止されています。そのコマンドを実行すると CLI.UNKNOWN_COMMAND で失敗し、削除されたフラグを指定すると CLI.INVALID_ARGUMENTS で失敗します。設定ファイルは読み込まれず、環境変数も無視されます。

削除された機能	代わりに使用するもの
@prisma/cli app deploy、app build、app run	独自のビルドスクリプトを実行してから、npx prisma deploy module.ts を実行します。ローカルで実行するには npx prisma dev module.ts を使用します
prisma.compute.ts、prisma.compute.json、defineComputeConfig	module.ts、compute() で宣言した各サーバーの service.ts、および prisma.config.ts の composer セクション
compute 設定を書き込む init	npx prisma init は、skills セクションのみを含む prisma.config.ts を書き込み、開発依存関係として prisma を追加し、スキルを同期するようになりました。composer セクションは自分で追加してください
compute:deploy スクリプト	npx prisma deploy module.ts、または現在の create-prisma が生成する deploy スクリプト
app deploy --branch <name>	npx prisma deploy module.ts --stage <name>
app deploy --prod、--no-promote、app promote	--stage を指定せずにデプロイすると本番環境にデプロイされます。service version promote <version-id>
app show、app open、app list-deploys、app show-deploy	service show <service>、service open <service>、service version list <service>、service version show <version-id>
app logs	service logs <service>
app rollback --to <id> --yes	service version rollback <service> --to <id> --confirm <id>
app domain ...	service domain ... --service <service>
app remove	module.ts から provision() を削除してデプロイするか、service delete <service> --confirm <service> を実行します
build logs <build-id>	GitHub Actions の実行ログまたは Console。状態と失敗したステップについては GET /v1/builds/{buildId}
database ...	postgres ...
project env remove	project env delete
auth logout --workspace <id>	auth workspace logout <id>
agent install、agent update、agent status	npx skills add prisma/skills --skill prisma-compute。パッケージスキルには npx prisma skills sync を使用します
PRISMA_PROJECT_ID、PRISMA_APP_ID、PRISMA_SERVICE_ID	--project <id-or-name>、位置引数としてのサービス名、および project link が作成する .prisma/local.json
/v1/apps REST エンドポイント	/v1/services（/v1/apps のパスは非推奨です）

prisma.compute.ts または compute:deploy スクリプトを含むリポジトリは、廃止されたフロー向けにセットアップされています。古いコマンドを実行するのではなく、Composer に移行してください（app-composer-setup.md）。

適用する場面

• Prisma Compute に新規または既存のアプリをデプロイする場合
• prisma.compute.ts、compute:deploy、または @prisma/cli app deploy を使用するプロジェクトを移行する場合
• プレビューステージ、プッシュ時のデプロイ、または CI デプロイを設定する場合
• サービスログの確認、バージョンの一覧表示、プロモーション、またはロールバックを行う場合
• Compute プロジェクトで環境変数、カスタムドメイン、Prisma Postgres データベース、またはバケットを管理する場合
• デプロイの失敗、サービスに接続できない状態、504、またはインスタンスがスリープすると停止する処理をデバッグする場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	CLI の機能	CRITICAL	cli-
2	アプリの宣言	CRITICAL	app-
3	ランタイム	CRITICAL	runtime-
4	デプロイ	HIGH	deploy-
5	運用	HIGH	ops-
6	デバッグ	HIGH	debug-
7	自動化	MEDIUM	automation-

クイックリファレンス

1. CLI の使用（重要）

• cli-prisma-8-binary - プラットフォームおよびデプロイのコマンドは、Prisma 8 CLI にのみ存在します。Prisma 6 または 7 のプロジェクトで npx prisma を実行すると、そのバージョンの ORM CLI が起動します。この CLI には auth、project、service、deploy はなく、Prisma 7 の dev は代わりにローカルデータベースを起動します。npx prisma --version を確認してください。Prisma 8 プロジェクト以外では、npx @prisma/cli@latest <command> を使用してください。
• cli-help-first - コマンドグループは auth、project（project env を含む）、postgres、bucket、branch、git、service（service version と service domain を含む）、さらに deploy、dev、init、skills、feedback です。フラグを使用する前に --help を読んでください。
• cli-json - --json を渡し、スクリプトでは --no-interactive も渡してください。error.code（NAMESPACE.SUBCODE）を基に分岐し、nextActions に従ってください。メッセージを解析してはいけません。
• cli-explicit-targets - サービス名は最初の引数として指定し、プロジェクトは --project で指定するか、ディレクトリをリンクしてください。プレビュー環境は --branch で指定します。--branch を指定しない場合、コマンドは本番ブランチを対象とします。CLI は現在の Git ブランチを読み取りません。
• cli-consent-tokens - 破壊的なコマンドには、正確な ID、名前、またはホスト名を指定した --confirm <token> が必要です。--yes では同意を与えられません。ユーザーがその操作を依頼した場合にのみ実行してください。

2. アプリの宣言（重要）

• app-composer-required - デプロイ可能なアプリには、module.ts（module(name, ...) をデフォルトエクスポート）、各サーバーの service.ts（compute({ name, deps, build }) を使用）、および prisma.config.ts の composer セクションが必要です。composer セクションには prismaCloud()、nodeBuild()（Next.js では nextjsBuild() も）、state: prismaState() を含めます。
• app-build-adapter - 単一の自己完結型バンドルには node({ module: import.meta.url, entry })、ビルド済みディレクトリには node({ module, dir, entry })、Next.js standalone には nextjs({ module, appDir }) を使用します。ビルド後もパッケージがインポートとして残る場合は、node() に dependencies: "external" を追加します。app-framework-builds.md を参照してください。
• app-region - 最初のデプロイではプロジェクトが作成され、リージョンが必要です。prismaCloud({ region: "eu-central-1" }) または PRISMA_REGION を指定してください。リージョンは後から変更できません。
• app-databases - rawPostgres()（パッケージのルート）は { url } を提供します。@prisma/composer-prisma-cloud/orm の postgres(contract) は型付きクライアントを追加し、デプロイ時にコミット済みのマイグレーションを適用します。どちらも process.env.DATABASE_URL ではなく、service.load() を通じて読み込んでください。
• app-names - プロビジョニング ID とサービス名に使用できる文字は [A-Za-z0-9] のみで、プラットフォームは3文字未満の ID を拒否します。ルートモジュール名がプロジェクト名になります。

3. ランタイム（重要）

• runtime-bind-all-interfaces - service.port()（PORT としてもエクスポートされ、デフォルトは3000）で待ち受け、0.0.0.0 にバインドしてください。ループバックで待ち受けるとアクセスできません。
• runtime-bun - サービスは Bun 上で実行されます。デフォルト（dependencies: "bundled"）では、デプロイにはビルド出力のみが含まれ、プロジェクトの node_modules は含まれません。そのため、ランタイム組み込み機能を除くすべての依存関係をビルドにインライン化する必要があります。パッケージがインポートとして残るビルド（tsc、Astro の Node アダプター）では、node() に dependencies: "external" を設定します。すると、デプロイではエントリがインポートするインストール済みパッケージがステージングされます。
• runtime-first-byte-60s - 60秒間バイトを送信しないリクエストは 504 Gateway Time-out となり、キャンセルされます。まず応答を返し、その後の処理は waitUntil またはキューから続行してください。
• runtime-sleep - アイドル状態のインスタンスはスナップショットが作成され、再開されます。タイマーや未完了の Promise は停止することがあります。@prisma/compute の waitUntil と KeepAwakeGuard は、ベストエフォートでインスタンスを起動状態に保ちますが、処理を永続化するものではありません。
• runtime-no-websockets - WebSocket サーバーはサポートされていません。

4. デプロイ（高）

• deploy-build-first - deploy と dev はビルドを実行しません。先にビルドを実行してから、npx prisma deploy module.ts を実行してください。
• deploy-dev-first - npx prisma dev module.ts は、認証情報なしでアプリ全体をローカル実行します。デプロイ前に、ローカル URL をそれぞれ確認してください。
• deploy-production-intent - --stage を指定しないデプロイ、および接続済みリポジトリのデフォルトブランチへのプッシュは、本番環境を変更します。先にユーザーの承認を得てください。プレビューには --stage <name> を使用します。
• deploy-auth - ワークステーションでは、ユーザーがブラウザーで npx prisma auth login を実行します。CI では PRISMA_SERVICE_TOKEN と PRISMA_WORKSPACE_ID を設定します。デプロイ前に npx prisma auth whoami --json の出力（envelope.result.authenticated、envelope.result.workspace）を確認してください。
• deploy-link-after - deploy はルートモジュール名（または --name）でプロジェクトを検索または作成しますが、.prisma/local.json には書き込みません。その後、service、git、または project env コマンドを実行する前に、npx prisma project link <app-name> を実行するか、--project を渡してください。
• deploy-on-push - プッシュによるデプロイには、npx prisma git connect（対話形式）と、prisma/cloud-deploy-action@v1 を実行するワークフローの両方が必要です。接続しただけでは何もデプロイされません。
• deploy-verify-url - デプロイ出力（--json の結果、または --report <path>）から各サービス URL を取得し、リクエストを送信してください。

5. 運用（高）

• ops-logs - service logs <service> は稼働中のバージョンのログを読み込みます。--version-id <id> は別のバージョンのログを読み込み、--follow はログをストリーミングします。ビルド出力は CLI ではなく、CI のログまたはコンソールにあります。
• ops-versions - service version promote <version-id> は本番環境の環境変数を使って再ビルドします。service version rollback <service> --to <id> --confirm <id> は再ビルドせずに切り戻します。
• ops-env-write-only - project env add|update|list|delete には、--role production、--role preview、または --branch <name> を指定します。値は返されず、次回のデプロイから適用されます。
• ops-domains - service domain add <hostname> --service <service> を実行し、報告された CNAME を作成してから service domain wait を実行します。本番ブランチのみが対象です。
• ops-secrets-once - postgres create、postgres connection create|rotate、および bucket key create は認証情報を一度だけ表示します。保存し、決して出力し直さないでください。

6. デバッグ（高）

• debug-error-code-first - 何かを変更する前に、--json の出力から error.code と nextActions を、または --report ファイルから failure.code を確認してください。
• debug-public-url - localhost ではなく、表示された公開 URL をテストしてください。デプロイが収束したのに応答しない場合、通常はホストへのバインド、ポート、または起動時のクラッシュが原因です。service logs を確認してください。
• debug-report-cli-bugs - 解決できない CLI のエラーは、シークレットを含めずに npx prisma feedback "<message>" で報告してください。

7. 自動化（中）

• automation-create-prisma - create-prisma は、すでに Composer アプリになっている新しい Prisma 8 プロジェクトをスキャフォールディングします。--no-deploy を渡さない場合、--json モードではデプロイが実行されます。
• automation-control-api - @prisma/composer/control は deploy、destroy、dev、log を公開します。ステージのティアダウンには destroy を使用します。このコマンドが読み取るのは PRISMA_SERVICE_TOKEN と PRISMA_WORKSPACE_ID のみです。
• automation-rest-api - https://api.prisma.io/v1/doc の /v1/services、/v1/deployments/{deploymentId}/logs、/v1/builds を使用してください。@prisma/compute-sdk を使って新しいデプロイツールを構築しないでください。

推奨ワークフロー

1. package.json（prisma 8.x が開発依存関係にあるか、@prisma/composer と @prisma/composer-prisma-cloud がインストールされているか）、module.ts、prisma.config.ts、ビルドスクリプト、および削除されたフローの残存物（prisma.compute.ts、compute:deploy）を確認します。
2. 不足しているものをインストールし、パッケージのスキルを同期します。

   npm install @prisma/composer @prisma/composer-prisma-cloud
   npm install -D prisma
   npx prisma skills sync
   

3. アプリを宣言または移植します：app-composer-setup.md と app-framework-builds.md を参照してください。
4. ビルドし、npx prisma dev module.ts を実行して、表示された各ローカル URL にリクエストします。
5. npx prisma auth whoami --json を実行します。envelope.result.authenticated が false の場合、ユーザーに npx prisma auth login の実行を依頼します。
6. npm run build && npx prisma deploy module.ts --stage <name> --json でプレビューをデプロイします。本番環境へのデプロイは、ユーザーの確認後に --stage を指定せずに行います。新しいプロジェクトにはリージョンが必要です。
7. 表示された各 URL にリクエストし、続けて npx prisma project link <app-name> と npx prisma service list --json を実行します（プレビューの場合は --branch <stage> を追加します）。
8. アプリ名、ステージ、サービス ID、URL、データベース ID を報告します。シークレットの値は絶対に報告しないでください。

避けること

• @prisma/cli app ...、build logs、database ... を実行したり、prisma.compute.ts を作成したりしないでください。
• Prisma 6 または 7 の prisma バイナリを使って、プラットフォームコマンドを実行しないでください。
• Composer サービスで process.env からポートや接続文字列を読み取らないでください。
• deploy がビルドを実行すること、rawPostgres() データベースをマイグレーションすること、または本番データをステージにコピーすることを想定しないでください。
• 破壊的なコマンドに --yes を渡さないでください。これによって同意が得られるわけではありません。
• auth login や git connect を非対話形式で実行しないでください。どちらもブラウザーを使ったユーザー操作が必要です。
• ユーザーの許可なく、接続済みリポジトリのデフォルトブランチにプッシュしないでください。本番環境にデプロイされます。

参考資料

• cli-command-map.md：検証済みの全コマンド、グローバルフラグ、JSON エンベロープ、ターゲット指定、同意トークン
• app-composer-setup.md：最小限の宣言、リージョン、データベース、設定とシークレット、prisma.compute.ts からの移植
• app-framework-builds.md：フレームワークごとのビルド出力と build: アダプター
• runtime-requirements.md：Bun、ホストとポート、初回バイトまでの 60 秒、スリープ、スリープ防止、リージョン
• deploy-cli-and-ci.md：prisma deploy、ステージ、認証情報、出力、CI、ティアダウン
• deploy-on-push.md：GitHub 接続と prisma/cloud-deploy-action ワークフロー
• ops-services-and-config.md：サービス、バージョン、ログ、ドメイン、環境変数、データベース、バケット
• debug-deploy-failures.md：症状、原因、解決方法
• automation-create-prisma.md：新しい Composer アプリのスキャフォールディング
• automation-rest-api.md：REST API のパス、コントロール API、@prisma/compute-sdk のステータス

ドキュメント：Compute、最初のアプリをデプロイする、Composer、CLI リファレンス。

フィードバック

npx prisma feedback "<message>" を実行すると、CLI のバージョン、Node.js のバージョン、OS プラットフォームとともに、匿名のフィードバックが CLI チームに送信されます。返信を希望する場合は --email <address> を追加してください。トークン、接続 URL、ユーザーデータは絶対に含めないでください。