prisma-next-quickstart

Name: prisma-next-quickstart
Author: prisma

github.com/prismaデータ・データベース4112.0k 回インストール9 週間前に更新

リポジトリ

prisma-next-quickstart について

初めて使う人、新規プロジェクト、既存データベース向けの Prisma Next 導入スキルです。最初のデータベース接続と型付きの作成・読み取りを案内し、新規構築と既存 DB からの導入を分けて説明します。

主な機能

01初回利用時のプロジェクト案内
02新規プロジェクトのセットアップ
03既存データベース導入の手順
04型付き作成・読み取り例
05契約とランタイムの配置案内

活用シーン

01Prisma Next の新規プロジェクト開始
02既存プロジェクトの把握
03既存データベースへの Prisma Next 導入

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/prisma/prisma-next --skill prisma-next-quickstart

インストール後、Claude Code で/prisma-next-quickstartを入力して読み込まれたか確認します。

詳細

Prisma Next — クイックスタート（導入）

データコントラクトを編集すれば、あとは Prisma が処理します。

このスキルでは、ユーザーが Prisma Next で初めて動作するクエリを実行できるよう、ゼロ（またはほぼゼロ）の状態から案内します。3つの方法がありますが、いずれも最初の一連の流れである 接続 → 書き込み → 読み取り に合流します。スキーマの編集は最初の一連の流れの後で行い、前ではありません。

初回利用時の案内 — ユーザーが初めて Prisma Next プロジェクトに来た場合（npx createprisma のようなスキャフォールドツールで作成された、チームメイトのリポジトリをクローンした、または自分で prisma-next init を実行し、次に何をすればよいか知りたい場合）で、「Prisma Next で何ができますか？」「どこから始めればよいですか？」「次は何をすればよいですか？」と尋ねています。目標は、データコントラクトを起点に、データベースへの接続、1行の往復処理まで案内し、その後は必要に応じてコマンドが自然に見つかるようにすることです。
グリーンフィールド — 新しいプロジェクトで、新しいデータベースを使います。ユーザーが自分で prisma-next init を実行します。init はサンプルモデルを含むスターターコントラクトを作成するため、データベースの初期化後、すぐに初回利用時の案内の流れに合流します。
ブラウンフィールド（DB） — 既存のデータベースがあり、コントラクトはまだありません。contract infer でデータベースからコントラクトを推論し、db sign でマーカーに署名してから、既存のテーブルのいずれかに対してクエリを記述します。

このスキルでは、別の ORM（Drizzle、Prisma 6/7、Sequelize、TypeORM、Kysely、Knex、生のドライバー）からの移行は扱いません。これらには個別にインストールできるスキルが用意されています。

使用するタイミング

ユーザーが「Prisma Next で何ができますか？」「Prisma で次に何ができますか？」「どこから始めればよいですか？」「最初に何をすればよいですか？」と尋ねており、PN プロジェクトがすでにディスク上に存在する場合。以下の初回利用時の案内の方法を使います。
ユーザーが createprisma（または同等のスキャフォールドツール）を実行した直後で、次に何をすればよいか尋ねている場合。初回利用時の案内の方法を使います。
ユーザーが新しいプロジェクトを始め、Prisma Next を使いたい場合。グリーンフィールドの方法を使います。
ユーザーに既存のデータベース（PN コントラクトなし）があり、PN を導入したい場合。**ブラウンフィールド（DB）**の方法を使います。
ユーザーが「prisma-next init」「PN を使い始める」「PN をセットアップする」「プロジェクトをスキャフォールドするには」と入力した場合。グリーンフィールドの方法を使います。
ユーザーが「既存の Postgres/Mongo があります。PN の使い方を始めるにはどうすればよいですか？」と言っている場合。**ブラウンフィールド（DB）**の方法を使います。

使用しないタイミング

ユーザーがすでに PN プロジェクトを持っており、モデルを追加したい場合 → prisma-next-contract。
特定の ORM から移行したい場合 → @prisma-next/migrate-from-<orm>-skill をインストールします（別スキル）。
すでにコントラクトがあるプロジェクトで db.ts を設定したい場合 → prisma-next-runtime。
Prisma Next をビルドツール（Vite プラグイン、Next.js など）と統合したい場合 → prisma-next-build。

主な概念

コントラクト：データモデルです。contract.prisma（PSL、標準的な記述方法）またはcontract.ts（TypeScriptビルダー）として作成します。フレームワークがこれを読み込み、2つの成果物、contract.json（ランタイムIR）とcontract.d.ts（型）を生成します。
ターゲット：接続先のストアです。現在はpostgresまたはmongodbです。initの実行時に選択し、スキャフォールドがインポートする@prisma-next/<target>ファサードに組み込まれます。
作成モード：コントラクトの記述方法です。psl（Prisma Schema Language、デフォルト）またはtypescript（プログラムによるビルダー）を選択します。typescriptは、必要に応じてViteプラグインと組み合わせると、vite dev中に自動生成できます（prisma-next-buildを参照）。
ファサードパッケージ。スキャフォールドは、ターゲットごとにファサードを1つだけインストールします。@prisma-next/postgres（または@prisma-next/mongo）です。ユーザーコードでは、ファサードのサブパス（@prisma-next/postgres/config、@prisma-next/postgres/runtime、@prisma-next/postgres/contract-builder）からインポートします。ファミリー／ターゲット／アダプター／ドライバーの配線はファサードに組み込まれています。ファサードを迂回しないでください。全一覧はprisma-next-contractを参照してください。
db.ts：ランタイムのエントリーポイントです。コントラクトのソースと同じ場所のsrc/prisma/db.tsに配置します。コントラクトの成果物をインポートし、アプリの他の部分で使用するdb値をエクスポートします。
マーカー：データベース内のpn_meta_marker行で、コントラクトのハッシュを記録します。これにより、PNはコントラクトと稼働中のDBの差異を検出できます。db init（新規構築／初回導入向け）またはdb sign（既存環境向け）で作成します。

標準的なディスク上の構成

Prisma Nextを利用するすべてのアプリケーションで、同じ構成を使用します。

<app-root>/
├── prisma-next.config.ts             ← project config at repo root
├── src/
│   └── prisma/
│       ├── contract.prisma           ← (or contract.ts) — schema source you author
│       ├── contract.json             ← emitted by `contract emit` — do not edit
│       ├── contract.d.ts             ← emitted by `contract emit` — do not edit
│       └── db.ts                     ← runtime entry; the rest of `src/` imports from here
└── migrations/
    ├── snapshots/                    ← content-addressed contract store, shared across spaces
    │   └── <hex>/
    │       ├── contract.json
    │       └── contract.d.ts
    └── app/                          ← created on first `migration plan` / `db init`
        ├── refs/head.json
        └── <timestamp>_<slug>/
            ├── migration.json
            ├── ops.json
            └── migration.ts

次の3点を把握しておいてください。

src/prisma/はコントラクトの配置場所です — ソース、生成された成果物、db.tsをすべて同じ場所にまとめます。src/の他のファイルからは、ファイルの階層に応じて./prisma/dbまたは../prisma/dbをインポートします。
migrations/app/ — app/の部分は、利用するアプリケーションのスペースIDです。依存する拡張機能はmigrations/の下に兄弟ディレクトリ（拡張機能のコントラクトスペースごとに1つ）を持ちますが、そこには書き込みません。マイグレーションの対象となるのはapp/サブツリーのみです。
prisma-next.config.tsはリポジトリのルートに配置します。src/の下ではありません。すべてのコマンドは、設定ファイルのディレクトリを基準にパスを解決します。

拡張機能パッケージや集約ルート型モノレポパッケージを開発するコントリビューターには、異なる構成を使用します — src/contract.{prisma,ts}（prisma/サブディレクトリなし）とmigrations/<timestamp>_<slug>/（app/部分なし）です。この違いは意図的なものです。どちらのパスを使用するかはprisma-next-contractを参照してください。

注意 — 現在、prisma-next initは誤った構成をスキャフォールドします。 リポジトリのルートにprisma/contract.{prisma,ts}とprisma/db.tsを書き込み、src/prisma/の下には作成しません。TML-2532で追跡されています。修正が反映されるまでは、initに--schema-path src/prisma/contract.prismaを渡すか、initの後にスキャフォールドされたprisma/ディレクトリをsrc/prisma/に移動し、prisma-next.config.tsのcontractパスをそれに合わせて更新してください。上記の標準構成はデモ例で使用されており、フレームワークの他の部分が想定している構成です。

最初の一歩 — 接続し、書き込み、読み取る

このスキルの3つの経路は、すべてここに合流します。プロジェクトのひな形が作成され、データベースに接続できたら、最初に行うことは常に同じです。コントラクトですでに宣言されているモデルを使って、接続し、行を書き込み、読み戻します。この最初の一歩ではコントラクトのソースには手を加えず、往復処理が動作してから拡張してください。

スニペットはsrc/直下の新しいファイル（例：src/first-arc.ts）に記述し、相対インポートが1階層で解決されるようにしてください。

// src/first-arc.ts
import 'dotenv/config';
import { db } from './prisma/db';

// Write a row against the starter model. Adapt the field names to whatever
// model your contract source actually declares — read it first.
await db.orm.User.create({ email: '[email protected]' });

// Read it back.
const users = await db.orm.User.select('id', 'email').all();
console.log(users);

[{ id: 1, email: '[email protected]' }]と出力されれば、プロジェクトはエンドツーエンドで接続されており、ユーザーは*「プロジェクトがある」から「開発を始めている」*へと進んだことになります。

db.orm.<Model>はデフォルトのORM経路です。モデルの形に沿っており、コントラクトに対して完全に型付けされ、初回使用時にデータベースへ遅延接続します（ランタイムのdotenv/configで読み込まれた環境から.envのDATABASE_URLを取得します）。ユーザーが準備できたら、より詳細なprisma-next-queriesスキルで、フィルター、結合、トランザクション、SQLビルダー、raw SQL、TypedSQLなど、残りの機能を扱います。

Mongoターゲット： 上記のスニペットはSQLターゲット向けの形です。@prisma-next/mongoでは、db.ormのキーはコレクションのストレージ名（@@map(...)、または@@mapがない場合は小文字にしたモデル名）になるため、同じ一連の操作はawait db.orm.users.create(...) / await db.orm.users.select('id', 'email').all()となり、db.orm.Userではありません。詳細なルールと書き換え手順は、prisma-next-queriesの§ MongoDB ORM addressingを参照してください。

この一連の操作に必要な前提条件。 3つの経路はいずれも、一連の操作に進むまでに次の状態を整えます。

リポジトリのルートにprisma-next.config.tsがあり、ターゲットとコントラクトのソース（通常はsrc/prisma/contract.prismaまたはsrc/prisma/contract.ts）が宣言されています。
コントラクトのソースがsrc/prisma/contract.{prisma,ts}にあります（initで作成されたスターターモデル、contract inferで推論されたコントラクト、またはブートストラップツールが生成したもの）。
src/prisma/db.tsがあり、出力されたコントラクトを使ってランタイムをインスタンス化しています。
DATABASE_URLが.env（またはランタイムの設定で指定された場所）に設定されています。
データベースが初期化済み（db init）またはマーカーで署名済み（db sign）であり、マーカー行が存在し、スキーマがコントラクトと一致しています。

以下の3つのワークフローでは、それぞれの経路でユーザーがこの状態に至るまでの方法を説明します。その後は、上記の一連の操作を共通して行います。

ワークフロー — 初回利用時のガイダンス

トリガー：「Prisma Nextで何ができますか？」「Prismaで次に何ができますか？」「どこから始めればよいですか？」「createprismaを実行したばかりです」「次は何ですか？」、またはこれらに近い質問で、createprisma、prisma-next init、チームメイトなどによってすでにディスク上に作成されたPNプロジェクトがある場合。

ユーザーの大まかな意図は、「Prisma Nextというものを使って、自分のデータベースに対してアプリケーションを実行したい」です。このワークフローの役割は、コントラクトを基点にして往復処理を1つ動かし、ユーザーが次に必要とするタイミングで追加のコマンドが自然に現れるようにすることです。これはガイダンスであり、ツアーでも、機能一覧でも、学習カリキュラムでもありません。

概念 — まず伝えること

Prisma Next は契約ファーストです。フレームワークが行うすべてのこと — クエリ型、マイグレーション、ランタイム型、ドリフト検出 — は、単一の信頼できる情報源である契約から導かれます。契約は、ユーザーのアプリケーションのデータモデルを記述します。フレームワークはそれを読み取り、残りを導き出します。まずはこの点を伝えてください。

「Prisma Next で何ができますか？」 への最初の回答では、契約のパスを伝え、その役割を一文で説明したうえで、ユーザーのアプリケーションを動かす方向へ案内します。機能一覧から始めないでください。コマンド一覧から始めないでください。次のように始めてください。「契約は <path> にあります。これはアプリケーションを記述するもので、クエリ型、マイグレーション、ランタイム型はすべてここから導かれます。アプリが実際にデータベースに接続して動作するようにしましょう。」

ユーザーが状況を把握した後の最初の一連の流れは、接続 → 書き込み → 読み取りです。最初に契約を編集するのでも、最初にマイグレーションを計画するのでもありません。ユーザーにとっての成功は、データベースに接続してアプリケーションコードを実行できることです。

ステップ 1 — プロジェクトを読み取り、契約の場所を伝える

ユーザーに具体的なことを伝える前に、次を確認してください。

リポジトリのルートにある prisma-next.config.ts — 設定されているターゲット（postgres / mongodb）、宣言されている contract: パス、インストールされている拡張機能。
設定で宣言されている契約のソース（標準的には src/prisma/contract.prisma または src/prisma/contract.ts。 TML-2532 より前のプロジェクトでは、代わりに prisma/contract.{prisma,ts} にある場合があります — 設定の contract フィールドを確認してください） — スターターモデルが存在する場合はその内容。
契約と同じ場所にある src/prisma/db.ts — ランタイムのエントリーポイント。
.env / .env.example — DATABASE_URL が設定されているか、サンプルのみか。
必要に応じて pnpm prisma-next db verify — 実際の DB が契約と一致しているか。

次に、契約のパスとその役割をあわせてユーザーに伝えてください。たとえば、次のようにします。「契約は src/prisma/contract.prisma にあり、現在は User モデルを宣言しています。契約はアプリを記述するものです。フレームワークが提供するクエリ型、マイグレーション、ランタイム型はすべてこのファイルから導かれます。次に、アプリをデータベースに接続しましょう。」正確な文言はエージェントに任せます。重要なのは、最初の回答を読んだユーザーが、契約の場所と、それが信頼できる唯一の情報源であることを把握できることです。

ステップ 2 — ユーザーのアプリを接続し、データの往復を実現する

目的は*「アプリが実際にデータベースに接続して動作できるようにすること」であり、「前提条件のチェックリストを満たすこと」*ではありません。具体的な手順は、ステップ 1 で何が整っているかによって異なります。

すべて設定済み。 すぐに行の書き込みと読み取りに進みます（上記の最初の一連の流れ — 接続、書き込み、読み取りを参照）。契約で宣言されているモデルに合わせて、スニペットを調整してください。
DATABASE_URL が未設定。 ユーザーに .env で設定してもらいます（prisma-next.config.ts ではありません — 落とし穴 5 を参照）。次に pnpm prisma-next db init を実行し、現在の契約をそのデータベースに適用してマーカー行を書き込みます。これでアプリが接続できるようになります。
データベースには接続できるが、契約がまだ反映されていない（マーカー行がない、または db verify がドリフトを報告する）。pnpm prisma-next db init を実行します。（短い開発サイクルでは db update が代替手段です。より制約が緩く、マイグレーション履歴は書き込まれません。ユーザーがスキーマをすばやく反復したいときに使います。ユーザーからスキーマ変更を DB に反映する方法を尋ねられた場合に説明してください。先回りして説明する必要はありません。）
契約が空（ブートストラップによってソースが空のままになっている）。フィールドが 2 つあるモデルを 1 つ追加します（例：User { id, email }）。次に pnpm prisma-next contract emit、続けて pnpm prisma-next db init` を実行します。まずは最小限にして、データの往復を実現してから拡張します。

ここでユーザーは、現在の作業に必要なコマンドとして db init（必要に応じて db update、contract emit）を実行します。それらが何をするコマンドなのかは、実際に使うことで理解できます。

ステップ 3 — 行を往復させる

上記の 最初のアーク — 接続、書き込み、読み取り のスニペットを、コントラクトで宣言されている任意のモデルに対して実行します。行が出力されて戻ってきたら、ユーザーは 「プロジェクトがあります」 から 「アプリが自分のデータベースに対して動いています」 へと進んだことになります。それが成果です。

ステップ 4 — 次の手順へ引き継ぐ

次に、何を作りたいかユーザーに尋ねます。その手順を担当するスキルに案内します。

クエリを増やす（フィルター、結合、トランザクション、生 SQL、TypedSQL）→ prisma-next-queries。
モデルの追加、フィールドの変更、リレーションの追加 → prisma-next-contract。このワークフローの中で、contract emit と db update（または migration plan と migrate）を使います。
ミドルウェア、環境設定、複数のターゲット → prisma-next-runtime。
Vite / Next.js / 開発サーバーとの統合 → prisma-next-build。
この時点でツール一式の全体像を知りたい場合は、以下の 日常的に使うコマンド がひと目でわかる概要です。

この流れでのアンチパターン

機能紹介や機能一覧から始める。 ユーザーが尋ねているのは、何が できるか です。実際に使い始めてもらいましょう。
コマンドを使う前に一覧を提示する。 コマンドは具体的な手順に紐づいています。その手順で必要になったときに提示しましょう。
クエリを一度も実行する前に、マイグレーションの概念に踏み込む。 マイグレーションは存在しますが、その価値がわかるのは後です。
一度に複数のモデルを追加する。 まず一つ追加し、クエリが一つ成功したら、反復して進めましょう。
prisma-next.config.ts のキーを順に説明する。 スキャフォールドのデフォルト設定は適切です。変更が必要になったときに見直しましょう。
コントラクトの説明を省く。 たった一行でも、「コントラクトは <path> にあり、これが信頼できる唯一の情報源です」 と伝えれば、ユーザーは全体像をつかめます。これがないと、以降のワークフローはつながりのない儀式のようになってしまいます。

ワークフロー — グリーンフィールド

コンセプト：prisma-next init は、設定、スキーマ、ランタイム、依存関係、コントラクトの emit ステップをスキャフォールドする CLI コマンドです。現在の作業ディレクトリを対象とするため、位置引数としてプロジェクト名を指定することはできません。ディレクトリを作成して cd で移動し、その後 init を実行します。

mkdir my-app && cd my-app
pnpm init                                          # if no package.json yet
pnpm dlx prisma-next init                          # interactive
# or non-interactive (CI / agent runs):
pnpm dlx prisma-next init --yes --target postgres --authoring psl

テレメトリーはオプトアウト方式です。 CLI はデフォルトで匿名の使用状況データを収集します。初回使用時には、init を含むすべてのコマンドが stderr に一度だけ通知を出力し、その後データを送信します。対話形式の同意確認はありません。prisma-next telemetry disable を実行するか、DO_NOT_TRACK=1 または PRISMA_NEXT_DISABLE_TELEMETRY=1 を設定するか、ユーザー設定（prisma-next の設定ディレクトリ。prisma-next.config.ts ではありません）で "enableTelemetry": false を設定すれば、いつでもオプトアウトできます。現在の設定を確認するには、prisma-next telemetry status を実行します。エージェントが実行する場合に関係します。CLI は、エージェントが実行したことを記録します。収集されるデータ、ユーザーごとの設定パス、完全にリセットする方法については、docs/Telemetry.md に記載されています。

init が受け付けるフラグ（信頼できる情報源は prisma-next init --help を実行して確認してください）：

--target <db> — postgres または mongodb。
--authoring <style> — psl または typescript。
--schema-path <path> — デフォルトは prisma/contract.prisma（または prisma/contract.ts）です。正規の src/prisma/ の場所に直接スキャフォールドするには、--schema-path src/prisma/contract.prisma（または .../contract.ts）を指定してください — 現在の init のデフォルトは誤っているため、TML-2532を参照してください。
--force — 確認なしで既存のスキャフォールドを上書きします（スキャフォールド済みディレクトリで init を再実行すると再初期化フローが開始されます — --force は確認を省略します）。
--write-env — .env も書き込みます（デフォルトでは .env.example のみを書き込み、.env はユーザー自身で管理します）。
--probe-db — DATABASE_URL に一度接続し、サーバーのバージョンがターゲットの最小要件を満たしているか確認します。
--strict-probe — プローブに失敗した場合、init を失敗させます（--probe-db がない場合は何もしません）。
--no-install — 依存関係のインストールと初回のコントラクト出力をスキップします。
--no-skill — Prisma Next スキルのインストールをスキップします（ネットワークから隔離された環境や制限された環境向け）。スキルクラスターは常にプロジェクトレベルにインストールされ、グローバルにはインストールされません。そのため、バージョンはプロジェクトの Prisma Next バージョンに固定されます。

init が正常に実行された場合、次のファイルが作成されます。

プロジェクトルートの prisma-next.config.ts。
--schema-path で指定した場所のコントラクトソース — 正規のパスを上書き指定した場合は src/prisma/contract.prisma、（現在誤っている）デフォルトを選択した場合は prisma/contract.prisma。
コントラクトソースと同じディレクトリの db.ts。
人間向けのクイックリファレンスである prisma-next.md。
.env.example（および --write-env を指定した場合は .env）。
package.json（依存関係とスクリプト）および tsconfig.json（必須のコンパイラオプション）を更新します。
依存関係をインストールし、prisma-next contract emit を一度実行します。
Prisma Next スキルをローカルのエージェントランタイムに登録します。

init のデフォルトを選択して、最上位に prisma/ ディレクトリが作成された場合（TML-2532）は、移動を1回、設定の編集を1回行えば整理できます。

mkdir -p src && mv prisma src/prisma
# Then update prisma-next.config.ts so `contract` reads
# 'src/prisma/contract.prisma' (or .ts) instead of 'prisma/contract.prisma'.
pnpm prisma-next contract emit   # re-emits contract.json + contract.d.ts under src/prisma/

db init を実行する前にこれを行ってください — マーカー行を書き込んだ後では、再構成がより困難になります。

init が成功した後は、上記の 最初の一歩 — 接続、書き込み、読み取り の手順に進みます。init はすでに User モデルと Post モデル（両者のリレーションを含む）を備えたスターターコントラクトを作成し、contract emit を一度実行しています。残る前提条件は、DATABASE_URL の設定とデータベースの初期化だけです。次の2つのコマンドを実行します。

.env に DATABASE_URL を設定します（.env.example からコピーします）。
データベースを初期化します：pnpm prisma-next db init。init が生成したスターターコントラクトを使って、テーブル、インデックス、制約を作成し、マーカー行を書き込みます。

次に、上記の 最初の一歩 のスニペットを User モデルに対して実行します。ユーザーがコントラクトを拡張する準備ができたら — モデルの追加、フィールドの変更、リレーションの追加など — prisma-next-contract に引き継ぎます。クエリをさらに扱う場合は、prisma-next-queries に引き継ぎます。

クエリを先に行い、スキーマ編集を先に行わない理由。 init に User と Post が含まれているのは意図的です。ユーザーは、セットアップが機能することを確かめるためにスキーマを設計する必要はありません。コントラクトの拡張は、最初の一歩が完了した後に行う次の作業であり、そこに至るための作業ではありません。ユーザーから 「Comment モデルを追加する」 ところまで一気に進めるよう頼まれた場合は、もちろん対応してください。ただし、プロジェクトが正しく設定されているか少しでも不確かな場合は、まず User または Post に対するクエリを1つ成功させてください。

ワークフロー — Brownfield-DB（既存データベース、コントラクトなし）

概要：PN コントラクトのない既存のデータベースに対して、contract infer は稼働中のスキーマ（テーブル、カラム、インデックス、制約）をたどり、それを記述する PSL コントラクトを書き出します。結果は最終的なコントラクトではなく、出発点です。確認して整えた後、db init でスキーマを最初から再作成するのではなく、db sign で現在のコントラクトハッシュをマーカーとして記録します。

mkdir my-app && cd my-app
pnpm init
pnpm dlx prisma-next init --yes --target postgres --authoring psl
# scaffold lands; you'll overwrite the starter schema below

次に、.env で DATABASE_URL を設定した状態で：

pnpm prisma-next contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma

（注：フラグは --out ではなく --output です。全オプションについては prisma-next contract infer --help を実行してください。）

エージェントはここでいったん停止し、推論された PSL を確認してください。再記述が必要となる兆候は次のとおりです。

PN が分類できなかったテーブル（たとえば、リレーションとして表現できるレガシーな中間テーブル）。
PN の型推測が誤っているカラム（たとえば、pgvector.Vector(length: 1536) のような拡張型にしたいのに String になっている）。
PN が検出できなかった @unique／@index のヒント。
別名を付けたいフィールド名。

その後、再生成して署名します。

pnpm prisma-next contract emit
pnpm prisma-next db sign
pnpm prisma-next db verify   # confirms the DB matches the contract; reports drift if not

次に、上記の 最初のアーク — 接続、書き込み、読み取り のスニペットを実行し、スターターモデルの代わりに既存のテーブルを使います。アークは同じで、そこに至るまでの手順だけが異なります。

日常的に使うコマンド

これは参照用の表であり、ユーザーに読み上げるスクリプトではありません。コマンドは上記のワークフローで、ユーザーが次に必要とする操作に応じて登場します。この表は、ユーザーがより広い視点を求めたとき（通常は最初の往復処理の後）に参照するためのもので、Prisma Next を使い始めたばかりの人が一目で確認できる要約でもあります。フラグの詳細は <command> --help を実行してください。ヘルプの出力が正確な情報源です。

実行したいこと	コマンド	関連するスキル
現在のコントラクトを初めて DB に適用する	`prisma-next db init`	このスキル
コントラクトのソースを編集した後、`contract.json` と `contract.d.ts` を再生成する	`prisma-next contract emit`	`prisma-next-contract`
開発専用の簡易スキーマ同期（マイグレーション履歴は保持しない）	`prisma-next db update`	`prisma-next-migrations`
コントラクトの差分からマイグレーションを計画する	`prisma-next migration plan --name <slug>`	`prisma-next-migrations`
保留中のマイグレーションを適用する	`prisma-next migrate`	`prisma-next-migrations`
稼働中のデータベースを調べる	`prisma-next db schema`	`prisma-next-debug`
DB がコントラクトと一致していることを確認する（ドリフトチェック）	`prisma-next db verify`	`prisma-next-debug`
既存の DB を PN コントラクトに取り込む	`prisma-next contract infer --db "$DATABASE_URL"`	このスキル（ブラウンフィールド）
構造化されたエラーエンベロープを読み解く	（`code`／`why`／`fix` フィールドを読む）	`prisma-next-debug`
バグを報告する、または機能をリクエストする	（フィードバックスキルから送信する）	`prisma-next-feedback`

選択 — PSL と TypeScript による記述

PSL（contract.prisma）— デフォルトです。簡潔で宣言的であり、Prisma を使ったことがある人にはなじみやすい形式です。ほとんどのプロジェクトにおすすめです。
TypeScript（contract.ts）— プログラムで構築する形式です。コントラクトを実際に計算する場合（テナントごとに異なるマルチテナント構成など）、複数のファイルでコントラクトの断片を再利用する場合、または拡張機能が PSL ではまだ表現できない構文を必要とする場合（たとえば、pgvector のパラメーター化されたストレージ型の登録）に使います。prisma-next-build の Vite プラグインと組み合わせると、保存時に自動で出力できます。

後から記述形式を切り替えるには、同じディレクトリで prisma-next init を再実行します。init フローは既存のスキャフォールドを検出し、再初期化するかどうかを確認します（非対話型の実行で確認を省略するには --force を使います）。既存のコントラクトの内容が自動的に変換されることはありません。対象の言語で手動で書き直す必要があります。

よくある落とし穴

位置引数を指定して prisma-next init <project-name> を実行する。 init は現在の作業ディレクトリを対象とします。位置引数としてプロジェクト名を指定することはできません。mkdir foo && cd foo && pnpm dlx prisma-next init を実行してください。
init はデータベースに接続しません。 ファイルのひな形を作成して依存関係をインストールし（初回の contract emit も実行します）、それだけです。db init ／ db update ／ migrate で接続してください。init が成功してクエリが失敗する場合、原因は init ではなく DATABASE_URL です。
推論された PSL を最終的なコントラクトとして扱う。 contract infer は出発点を生成します。読んでいないコントラクトに対して db sign を実行しないでください。
コントラクトを編集した後に emit し忘れる。 コントラクトの生成物（contract.json、contract.d.ts）は、contract emit を実行するまで古いままです。型チェッカーがモデルは「存在しない」と示す場合、emit を実行し忘れています。
.env ではなく prisma-next.config.ts に DATABASE_URL を設定する。 設定ファイルは dotenv/config を介して .env を自動的に読み込みます。URL をハードコードすると、認証情報が漏洩し、環境ごとのオーバーライドも適用されません。prisma-next-runtime を参照してください。
contract.json または contract.d.ts を手動で編集する。 これらは生成物です。次に contract emit を実行すると、変更は上書きされます。代わりにソースを編集してください。
contract infer で --out を使用する。 フラグは --output です。

Prisma Next がまだ対応していないこと

別の ORM からの移行。 Prisma Next は Drizzle ／ Prisma 6/7 ／ Sequelize ／ TypeORM ／ Kysely ／ Knex ／生のドライバーから、スキーマを移行することはできません。回避策：ソースに対応する @prisma-next/migrate-from-<orm>-skill があればインストールするか、既存のデータベースとして扱い、そこから contract infer を実行してください。ガイド付きの移行フローを組み込みで利用したい場合は、prisma-next-feedback スキルから機能リクエストを送信してください。
prisma db push のような本番環境への同期。 db update は開発時の手早い方法です。本番環境では、マイグレーション（migration plan ＋ migrate）を使用してください。PN は「マイグレーションなしで本番環境へ push」する手段をあえて提供していません。prisma-next-migrations を参照してください。
Studio ／ GUI データベースブラウザー。 稼働中の DB を CLI のツリー形式で要約するには、prisma-next db schema を使用してください。インタラクティブな UI が必要な場合は、prisma-next-feedback スキルから機能リクエストを送信してください。

参照ファイル

このスキルは意図的に本文のみで構成されています。フラグの詳細については、prisma-next init --help、contract infer --help、db sign --help が正式な情報源です。迷った場合は --help を実行し、このスキルから推測するのではなく、実際のコマンドの説明を読んでください。

チェックリスト

Markdown 対応

ログインしてコメント

基本情報

作者: prisma
リポジトリ: prisma/prisma-next
カテゴリ: データ・データベース
インストール数: 2,045
GitHub スター: 411

問題を報告