Communitygithub.com

Prisma Composer コアコンセプト

Prisma Composer (`@prisma/composer`) を使用したアプリのデプロイや管理(サービスとモジュールの配線、ローカル実行、テスト、環境の立ち上げ/破棄)を行う際に使用します。「prisma composer」、「@prisma/composer」、「prisma app」、`prisma deploy`、`prisma dev`、`compute()`、`module()`、`contract()`、`service.load()`、`mockService`、`bootstrapService` がトリガーとなります。

Prisma Composer コアコンセプト とは?

このスキルは、Prisma Composer フレームワーク上で構築されたアプリケーション(Prisma App)を管理するための、包括的かつ概念的なガイドです。宣言型の構成モデル、サービス、リソース、モジュールといったコアコンセプトを説明し、それらがどのように型安全なポートを介して配線されるかを示します。このスキールドには、サービスノードのみがアプリケーションコードと環境との唯一のインターフェースであること、そして依存関係の注入と入力処理のための2つの明確なチャネルについて詳細が含まれています。また、サービス間通信のためのコントラクトとRPCの仕組み(自動サービスキー、べき等性、リトライを含む)、ビルドプロセスの所有権に関する注意事項、データベースとマイグレーションの取り扱いについても説明しています。環境設定の変更は推奨されておらず、このスキルのルールに従うことが必須です。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Adrian7373/semantic-video-pipeline/tree/HEAD/packages/database/.agents/skills/prisma-composer-core-concepts

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Prisma Composer コアコンセプト は何をしますか?

Prisma App は、TypeScript で構成された型付き宣言のツリーであり、prisma CLI に渡されます。CLI には 2 つの Composer コマンド(prisma deploy と prisma dev)があります。ティアダウンとログはコマンドではなく、スクリプトから呼び出される @prisma/composer/control の destroy および log 操作です。 このファイルでは、構造、階層、関係性、ワークフローについて説明します。これらはコードや CLI のヘルプ出力からは観測できない概念です。これは CLI リファレンスではありません。各コマンドのフラグは、推測するのではなく prisma <command> --help で確認してください。Prisma プラットフォームは急速に進化しているため、このファイルは安定した概念的な核として扱い、最新の完全なドキュメントは https://www.prisma.io/docs を参照してください。動作するコードについては、prisma/composer リポジトリの examples/ を参照してください。

2 つの原則がすべてを支配し、これらは必須です(docs/design/01-principles/)。

  1. コードが環境を読み取ることはありません。 依存関係、設定、資格情報、ポートはすべて、型指定されたサービスノードを介して提供されます。process.env が答えになることはありません。
  2. Composer がコードをバンドルしたり変換したりすることはありません。 独自のバンドラーでビルドします。フレームワークは、決定論的な手順でビルド出力をアセンブルし、設定されたデプロイターゲットに渡します。

宣言はデータである

作成するすべてのものは宣言です。つまり、アプリの一部を記述するプレーンデータであり、インポートしても何も実行しません。3 種類のノードがあります。

種類宣言方法目的
サービスcompute()コードの実行単位。アトミックであり、Composer はそのポートのみを認識します
リソースrawPostgres()、bucket()ステートフルな管理対象依存関係
モジュールmodule()グループ化の境界。独自のコードは実行せず、型指定されたポートを公開します

ノードはポートを介して接続します。deps はノードが必要とするものを宣言し、expose はノードが提供するものを宣言します。配線はモジュールのビルダー内で provision() を介して行われ、CLI に渡されるルートモジュールがアプリです。

// module.ts
import { module } from '@prisma/composer';

export default module('store', ({ provision }) => {
  const catalog = provision(catalogModule);
  provision(storefrontService, { deps: { catalog: catalog.rpc } });
});

ポートは型付けされているため、コンパイラがすべての配線を検証します。間違ったプロデューサーに配線された依存関係、欠落している RPC ハンドラ、間違った形状のリテラル入力値。これらはすべて、デプロイ時ではなく tsc で失敗します。環境にバインドされた入力は例外です。これらの値はデプロイ時にのみ存在するため、シークレットバインディングの不一致やプラットフォーム変数の欠落は、代わりにデプロイ初期の拒否として表面化します(以下の「2 つのチャネル」を参照)。タイプチェックし、次にビルドし、その後デプロイします。配線が正しいかどうかを確認するためにクラウドを使用しないでください。

Composer 自体はターゲットに依存しません。@prisma/composer はオーサリング、テスト、CLI を提供し、特定のプラットフォームには結合されていません。デプロイターゲットはデプロイ設定に登録された拡張機能であり、@prisma/composer-prisma-cloud が Prisma Cloud ターゲットであり、このスキルのデプロイセクションで想定されるものです。そのルートエクスポートは compute、rawPostgres、bucket、envSecret、envParam です。ORM の語彙(postgres、dataContract)は /orm サブパスの下にあり、共有の /cron、/storage、/streams、/auth、/email モジュールと並んで存在します。これらは、基本的な Prisma Cloud アプリが必要とする 2 つの Composer パッケージのみであり、何も自動的にインストールしません。新しいプロジェクトはどちらも持っていない状態から始まるため、最初に両方を依存関係として追加します。拡張機能は、これらのパッケージと一緒に独自の prisma-composer-* パッケージを追加します。機能を自分で実装する前に、既存のモジュールを構成することを検討してください。配線は数行で済みます。

エントリグラフ(module.ts から到達可能なすべてのもの)内では、明示的な .ts 拡張子(./service.ts、tsconfig で allowImportingTsExtensions を設定)を使用して相対インポートを記述します。この形式はどこでも解決されます。prisma deploy と prisma dev は ./service.js や拡張子なしの ./service も .ts ソースにマッピングしますが、他のツールはそうでない場合があります。

サービスノードが唯一の入り口です

ランタイムコードは、インポートするサービス宣言からすべてを受け取ります。

  1. service.load(): 依存関係(型指定された RPC クライアント、データベースバインディング)。
  2. service.input(): スキーマ検証済みの 1 つのオブジェクトとしての入力全体。その中の資格情報は、秘匿化された SecretString ボックスです。
  3. service.port(): バインドする予約ポート(デフォルトは 3000)。

サービス宣言は純粋なデータです。サーバーエントリはビルドが生成し、プラットフォームが起動するものです。

// service.ts
export default compute({
  name: 'auth',
  deps: { db: rawPostgres() },
  build: node({ module: import.meta.url, entry: '../dist/server.mjs' }),
  expose: { rpc: authContract },
});

// server.ts
const { db } = service.load(); // { url }: 独自のクライアントを構築します
const handler = serve(service, {
  rpc: { verify: async ({ token }) => ({ ok: token.length > 0 }) },
});
Bun.serve({ port: service.port(), hostname: '0.0.0.0', fetch: handler });

コンシューマーは deps: { auth: rpc(authContract) } を宣言し、load() から型指定されたクライアントを取得します。

2 つのチャネル: 依存関係と入力

値の種類宣言提供読み取り
別のノードによって生成されるdeps: { db: rawPostgres() }provision() で配線load()
その他(設定または資格情報)input スキーマの 1 つのフィールドprovision() でバインド: リテラル、envParam()、または envSecret()input()

サービスは、プレーンな値と資格情報をすべてまとめて、1 つの Standard Schema(ハウス選択は arktype)として、その受信設定全体を宣言します。資格情報は @prisma/composer/arktype の secretString() として型指定されたフィールドです。条件付きの正当性(「請求がオンでない限り stripe キーは不要」)は、通常のスキーマユニオンです。provision() でのバインディングはスキーマの形状を反映します。envSecret('NAME') はプラットフォーム変数に名前を付け、値を保持することはありません。

問題を引き起こすルール:

  1. 秘密性は検証によって強制されます。 スキーマが SecretString を期待している場所にリテラルがバインドされるとデプロイは失敗します。envSecret がプレーンな文字列フィールドにバインドされても同様に失敗します。
  2. envParam の値は生の文字列として到着します。文字列フィールドにバインドします。ステージのプラットフォーム変数がストアです。デプロイを行うシェルは、欠落している名前のみをシードします(両方に欠落している場合、デプロイは早期に失敗し、変数に名前を付けます)。プラットフォームの値を変更するには、再デプロイが必要です。
  3. 欠落はスキーマの判断です。 環境にバインドされたフィールドで、その変数が設定されていないか空の場合、キーが省略された として解決されます。これは、スキーマがそれを許可している場合(オプションフィールド、ユニオンアーム)にのみ有効です。デプロイレポートは、シリアル化された入力ドキュメント(シークレットは {"$secret":"VAR"} ポインタとして扱われます)と、欠落として解決されたすべてのキーを出力します。
  4. 予約済みの port はスキーマの外側にあります。 service.port() を介して読み取り、決して process.env ではありません。フレームワークは、Next.js スタンドアロン用に PORT もエクスポートします。これは Next.js 自身がバインドします。
  5. モジュールは、プラットフォーム名を知らなくても、シークレットの必要性を転送できます。 モジュール境界で secrets: { signingKey: secret() } を宣言し、転送された参照をバインディングリーフとして渡します。親が実際のソースをバインドします。
  6. input.apiKey.expose() がシークレットの値にアクセスする唯一の方法です。ボックスは他のすべての場所(ログ、JSON、エラー)で秘匿化されます。

コントラクトと RPC

コントラクトは、サービスが通信するための型指定されたインターフェースです。これを所有するサービスと共に存在し、任意の Standard Schema バリデーターによって型指定され、プロバイダー(serve()、コンパイル時にコントラクトのメソッドを網羅的にカバー)とコンシューマー(rpc(contract))の両方が同じ値を参照します。呼び出しは HTTP 上の RPC として送信されます。2 つの動作が自動的にプロビジョニングされるため、再実装してはなりません。

  1. サービスキー。 デプロイ時に、Composer はコンシューマーとプロバイダーのバインディングごとに、個別の推測不可能なキーを発行します。serve() は、ハンドラが実行される前に、それ以外のものに対して 401 を返します。コード内でこれを宣言するものは何もありません。結果: 独自のサービス間認証を構築せず、デプロイされた /rpc/<method> を curl して動作を確認しないでください。配線されていない呼び出し元は常に 401 を受け取ります。これは壊れたデプロイのように見えますが、そうではありません。コンシューマーを介して、またはローカルでデバッグしてください。ローカルでは何も強制されません。キーはバインディングごと(1 つが漏洩しても別のコンシューマーになりすますことはできません)、サービススコープ(有効なキーはすべてのメソッドに到達します。ゲートを個別に設定するにはサービスを分割します)、バインディングを削除するかスタックを破棄して再デプロイすることによってのみローテーションされ、手動で編集しないデプロイ所有の COMPOSER_* 変数に保存されます。
  2. 冪等性とリトライ。 生成されたクライアント呼び出しはすべて Idempotency-Key を保持します。ドロップされた呼び出しはバックオフ付きでリトライされ、serve() はキーごとに 1 つの呼び出しを実行し、遅延したリトライに対して完了した応答を再生します。したがって、すべてのメソッドは安全にリトライ可能であり、コントラクトはそれについて何も宣言しません(「これは冪等ですか?」フラグはありません。独自に発明しないでください)。ハンドラはオプションの 3 番目の引数 (input, deps, ctx) を受け取り、単一インスタンスのメモリを超えて厳密に 1 回の実行が必要な場合に ctx.idempotencyKey (string | undefined) を読み取ることができます。ほとんどの場合は必要ありません。ローカルおよびテストでは何もプロビジョニングされないため、serve() はすべての呼び出しを通過させます。テスト入力にキーを指定しないでください。

ビルドはあなたのものです

あなたがビルドし、フレームワークがアセンブルします。プレーンなサーバープロセスの場合、entry は単一の自己完結型 ESM ファイルを指す必要があります。ランタイムの組み込み (bun、bun:*、node:*) を除くすべてがインライン化されます。デプロイはその 1 つのファイルをコピーし、node_modules を出荷しません。そのため、インライン化されずに残ったものは、デプロイ時ではなく起動時に失敗します。問題を引き起こすルール:

  1. 1 つのパッケージ内の 2 つのサービスは、2 つの別々のビルドを意味します。エントリごとに 1 つです。単一のマルチエントリビルドは、共有コードをどちらの出力にも含まれないチャンクに分割します。
  2. ディレクトリビルドは dir + entry を使用します(dir はサービスモジュールからの相対パス、entry は dir 内のファイル。../ はエラーです)。ツリーはそのままコピーされるため、サーバーは作業ディレクトリではなく import.meta.url に対して兄弟を解決する必要があります。ツリーにシンボリックリンクを含めてはなりません。パッケージャーがそれらを拒否し、リンクに名前を付け、アセンブリは失敗します。
  3. Next.js: output: 'standalone' を指定した next build がビルド全体です。nextjs({ module, appDir }) はアプリのルートに名前を付けます。load() を呼び出すページまたはアクションには export const dynamic = 'force-dynamic' が必要です。これは、ランタイム環境がビルド時に存在せず、Next がプリレンダリングされたルートのランタイム環境を無視するためです。
  4. deploy または dev の前に必ずビルドしてください。 どちらも自動的にビルドしません。

デプロイ設定は prisma.config.ts の composer セクションであり、それ以外はありません。拡張機能(prismaCloud()、nodeBuild()、アプリに Next.js サービスがある場合は nextjsBuild())とデプロイ状態バックエンド(prismaState())を登録します。

// prisma.config.ts
import { defineConfig as composer } from '@prisma/composer/config';
import { nodeBuild } from '@prisma/composer/node/control';
import { prismaCloud, prismaState } from '@prisma/composer-prisma-cloud/control';
import { definePrismaConfig } from 'prisma/config';

export default definePrismaConfig({
  composer: composer({ extensions: [prismaCloud(), nodeBuild()], state: prismaState() }),
});

コマンドは、実行されるディレクトリから prisma.config.ts を見つけ、リポジトリルートまで遡ります。composer を宣言する最も近いファイルが優先され、そのセクション全体が使用され、キーごとにマージされることはありません。許可されるのは extensions と state のみであり、その他のキーはエラーになります。アプリコードはこのファイルをインポートしません。

別の prisma-composer.config.ts は読み取られなくなりました。古いセットアップは、静かに無視されるのではなく、拒否されます。ロードされた prisma.config.ts が composer セクションを宣言していない場合は CONFIG.SECTION_MISSING、セクションにまだ configPath がある場合は CONFIG.FIELD_RETIRED、宣言している prisma.config.ts の隣に prisma-composer.config.* がある場合は CONFIG.FILE_RETIRED。これら 3 つはすべて CLI の CLI.CONFIG_SECTION_INVALID の下にあります。3 つすべての修正方法は、古いファイルの extensions と state をセクションに移動し、古いファイルを削除することです。@prisma/composer-cli/family は ComposerSection をエクスポートしなくなりました。セクションの型は @prisma/composer/config の PrismaAppConfig です。

データベースとマイグレーション

2 種類の Postgres 依存関係があります。

  1. rawPostgres(): バインディングは { url } であり、アプリが独自のクライアントを所有します。
  2. postgres(...): Prisma-ORM 型のデータベース。バインディングは { url, client } (ADR-0040) です。生の接続 URL に加え、データコントラクトから Composer が構築する型指定されたクライアントで、最初のアクセス時に遅延して初期化されるため、クエリは binding.client を介して行われ、コンパイル時にチェックされます。postgres と dataContract はどちらも、パッケージルートではなく @prisma/composer-prisma-cloud/orm からインポートします。dataContract でラップされた 1 つの値(contract.prisma から prisma contract emit によって出力される)は、依存関係側(deps: { db: postgres(catalogData) })とリソース側の両方から参照されます。リソース側は prisma.config.ts のパスも指定するため、デプロイのマイグレーションステップは出力された contract.json を再読み込みして migrations/ を見つけることができます。

デプロイは再生のみです: コミットされた migrations/ の下のマイグレーションを適用し、それ自体でスキーマを作成することはありません。新しいデータベースの最初のスキーマを含むすべてのスキーマ変更は、1 つのループに従います。

  1. contract.prisma を編集します。
  2. prisma contract emit が contract.json + contract.d.ts を再生成します。
  3. prisma migration plan --name <slug> がマイグレーションを作成します(空のグラフでは、これがベースラインを作成します)。
  4. 変更を含む migrations/ をコミットし、デプロイします。新しいデータベースは、空の状態からパス全体を再生します。

データベースを使用するすべてのサービスは、そのマイグレーションが完了した後にのみデプロイされます。マイグレーションに失敗すると、新しいコードは出荷されません。新しいデプロイがライブになるまで、古いコードは新しいスキーマに対して機能し続けるため、各マイグレーションは置き換えるコードと互換性があるように保ってください。

作成されたパスがターゲットコントラクトに到達しない場合、デプロイ(および古いローカルデータベースに対する dev)は MIGRATION_PATH_NO で拒否されます。

…

[以下省略]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル