prisma-next-runtime

Prisma Next — ランタイム（db.ts の配線）

データコントラクトを編集すれば、あとは Prisma にお任せください。

このスキルでは、ランタイムのエントリーポイントである db.ts と、データベースクライアントに拡張機能、ミドルウェア、環境設定を組み合わせる方法を説明します。

使用する場面

• ユーザーが初めて db.ts を設定する場合（初期化後）。
• ユーザーがミドルウェア（テレメトリー、リント、予算、カスタム）を追加したい場合。
• ユーザーが環境ごとの設定（開発環境と本番環境、マルチリージョン）を行いたい場合。
• ユーザーが Postgres、SQLite、Mongo のファサードを切り替えたい場合。
• ユーザーが db.transaction(...) で操作をラップしたい場合（Postgres と SQLite）。
• ユーザーが単発スクリプト（tsx my-script.ts、Node CLI、CI タスク）を実行していて、クエリの完了後にプロセスが終了しない場合、またはスクリプトの終了処理（db.close()、await using）が必要な場合。
• ユーザーが次の語句に言及した場合：db.ts、postgres()、mongo()、ミドルウェア、テレメトリー、リント、予算、DATABASE_URL、.env、コネクションプール、poolOptions、開発環境と本番環境、トランザクション、リードレプリカ、複数データベース、スクリプトが終了しない、ハング、db.close、db.end、接続を閉じる、pool.end、await using。

使用しない場面

• ユーザーがクエリを記述したい場合 → prisma-next-queries。
• ユーザーが Supabase を利用している場合 — ロール優先の supabase() ファクトリー、asUser(jwt) / asAnon() / asServiceRole()、JWT 設定、RLS → prisma-next-supabase。
• ユーザーがコントラクトを編集したい場合 → prisma-next-contract。
• ユーザーが Prisma Next をビルドツール（Vite プラグイン、Next.js、…）に接続したい場合 → prisma-next-build。
• ユーザーが接続エラーやランタイムエラーをデバッグしたい場合 → prisma-next-debug。
• ユーザーがバグや機能リクエストを報告したい場合 → prisma-next-feedback。

主な概念

• db.ts はランタイムのエントリーポイントです。 @prisma-next/<target> ファサード（@prisma-next/postgres/runtime、@prisma-next/sqlite/runtime、または @prisma-next/mongo/runtime）からランタイムファクトリーを、コントラクトのアーティファクト（contract.json と contract.d.ts の Contract 型）および任意のミドルウェアとともにインポートします。アプリの他の部分がインポートする db の値をエクスポートします。
• ファサードのランタイムファクトリーは、ユーザーが作成する db.ts からインポートする唯一のインターフェースです。 各ファクトリーは デフォルト エクスポートです。Postgres の場合：import postgres from '@prisma-next/postgres/runtime'、SQLite の場合：import sqlite from '@prisma-next/sqlite/runtime'、Mongo の場合：import mongo from '@prisma-next/mongo/runtime'。ファクトリーのシグネチャは <Target><Contract>(options) で、型パラメーター（contract.d.ts の Contract 型）が 1 つ、オプションオブジェクトが 1 つです。
• 接続は遅延されます。 ファクトリーはデータベースに同期的には接続しません。静的なクエリサーフェス（db.sql、db.orm）はすぐに利用でき、ドライバー／プールは、ランタイムを必要とする最初の呼び出し時、または明示的に await db.connect({ url }) を呼び出したときにインスタンス化されます。そのため、環境変数の準備が整う前に読み込まれるモジュールでも db.ts をインポートできます。
• ミドルウェアは順番に合成されます。 middleware: [...] 配列の最初のミドルウェアが 最外層 として実行されます。つまり、処理に入るときに最初に操作を受け取り、戻るときに最後に受け取ります。テレメトリーを先頭に置くと、予算／リントの失敗がテレメトリーのスパン内に記録されます。
• prisma-next.config.ts と .env の使い分け。 設定（defineConfig({ contract, db, extensions, migrations })）では、コントラクトのパス、インストール済みの拡張機能、マイグレーションディレクトリ、デフォルトの接続文字列といった、プロジェクトの静的な構成を指定します。.env には環境ごとの値（DATABASE_URL、シークレット）を設定します。設定は dotenv/config を介して .env を自動的に読み込みます。設定ファイルに DATABASE_URL をハードコードすると、認証情報が漏洩し、環境ごとの上書きができなくなります。
• ビルドシステム／開発サーバーとの統合は別のスキルです。 vite dev による自動出力は prisma-next-build が担当します。このスキルで扱うランタイム側は、contract.json／contract.d.ts がどのようにディスクに配置されたかにかかわらず、それらを読み取るため、2 つのスキルを問題なく組み合わせられます。

ワークフロー — 基本的な db.ts

考え方：db.ts は、出力されたコントラクトの成果物（ターゲットに合わせた形式）と、それらに対してクエリを実行するランタイムとの境界です。重要なインポートは3つあります。ランタイムファクトリー、静的なクエリのインターフェースに型を付けるための Contract 型、そして構築時にランタイムが構造を検証できるようにする JSON 成果物です。

init は（--target postgres の場合）、次のようなファイルをスキャフォールドします。

// src/prisma/db.ts
import postgres from '@prisma-next/postgres/runtime';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

export const db = postgres<Contract>({
  contractJson,
  url: process.env['DATABASE_URL'],
});

（現在、init は代わりに prisma/db.ts にスキャフォールドします。prisma-next-quickstart の TML-2532 を参照してください。標準のパスは src/prisma/db.ts です。src/ の残りのファイルは、階層に応じて ./prisma/db または ../prisma/db からインポートします。）

知っておくべきことは3つあります。

• <Contract> 型パラメーターは重要です。 これがないと、静的なインターフェースは汎用的な形に縮退し、モデル名のオートコンプリートが失われます。出力された ./contract.d.ts から、必ず Contract をインポートしてください。
• with { type: 'json' } は必須です。 Node の ESM JSON インポート属性の仕様です。これがないと、インポート時にエラーになります。
• 構築時の url は省略可能です。 db.ts の読み込み時に DATABASE_URL が設定されていなくても、ファクトリーはクライアントを返します。後から await db.connect({ url }) を呼び出せます。ファクトリーでのエラーは遅延され、ランタイムが実際に必要になった場合にのみ発生します。

Mongo ファサードも同じ構築方法（import mongo from '@prisma-next/mongo/runtime'）で、ライフサイクルメソッドも同じ db.connect(...) と db.close() を使います。Mongo ファサードは db.transaction(...) を公開しません。 回避策については Prisma Next がまだ対応していないこと を参照してください。ORM のインターフェースは、キーの扱いが1点異なります。 Mongo では、db.orm のキーは PSL のモデル名ではなく、コレクションのストレージ名（@@map(...) の値、または @@map が設定されていない場合は小文字にしたモデル名）です。そのため、model User { … @@map("users") } は db.orm.User ではなく db.orm.users から参照します。SQL ビルダーのレーン（db.sql.<table>）は Mongo には存在せず（db.sql は undefined です）。ルールの詳細と SQL ターゲットの例を書き換える方法については、prisma-next-queries § MongoDB ORM の指定方法 を参照してください。

ワークフロー — スクリプトとして実行する場合（終了処理）

考え方：接続してクエリを実行したあと、プロセスの終了を想定する短いスクリプトは、ファサードが所有する pg.Pool が Node のイベントループを稼働状態に保つため、Postgres では終了しません。データの往復処理は成功しますが、スクリプトは終了しません。スクリプトが戻る前に await db.close() を呼び出してください（または、スクリプトモジュールのトップレベルで await using を使い、モジュール終了時に終了処理を実行してください。これが重要な理由については、下記のブロックスコープに関する警告を参照してください）。

基本形 — db.ts から db をエクスポートし、スクリプトでインポートして、最後に閉じます。

// src/scripts/hello.ts
import { db } from '../prisma/db';

const created = await db.orm.User.create({ email: '[email protected]', name: 'Alice' });
const read = await db.orm.User.first();
console.log({ created, read });

await db.close();

TS 5.2 以降の慣用的な形 — クライアントをスクリプトモジュールのトップレベルで構築し、モジュール終了時に [Symbol.asyncDispose] が close() を呼び出すようにします。

// src/scripts/hello.ts — top-level await in a script module
import postgres from '@prisma-next/postgres/runtime';
import type { Contract } from '../prisma/contract.d';
import contractJson from '../prisma/contract.json' with { type: 'json' };

await using db = postgres<Contract>({ contractJson, url: process.env.DATABASE_URL! });

const user = await db.orm.User.first();
console.log(user);
// db.close() runs automatically when the script module exits.

await using はブロックスコープです。リクエストハンドラー内に記述しないでください

このセクションで最も重要なルールです。await using db = postgres(...) は、外側のブロックを抜けるときに破棄されます。スクリプトモジュールでは、そのブロックはモジュール本体であり、プロセス終了時に破棄されます。これは問題ありません。一方、リクエストハンドラーでは、外側のブロックはハンドラー関数なので、破棄はリクエストごとに実行されます。呼び出しごとに新しい pg.Pool が作成され、TCP 接続が大量に発生し、接続の作成と破棄を繰り返すホットループになります。

// DO NOT do this — closes the pool after every request.
app.get('/users', async (req, res) => {
  await using db = postgres<Contract>({ contractJson, url: process.env.DATABASE_URL! });
  const users = await db.orm.User.all();
  res.json(users);
});

サーバーで適切なのは、db.ts にモジュールレベルのシングルトンを置き、ハンドラーからインポートし、プロセスの存続中は決して閉じないパターンです。

// src/prisma/db.ts — constructed once, lives for the process
export const db = postgres<Contract>({ contractJson, url: process.env.DATABASE_URL });

// src/routes/users.ts
import { db } from '../prisma/db';

app.get('/users', async (req, res) => {
  const users = await db.orm.User.all();
  res.json(users);
});

サーバー（HTTP ハンドラー、リクエストループ内のワーカー）は、通常の稼働中に db.close() を呼び出しません。プールはプロセスの存続中、開いたままです。db.close() と await using は、tsx my-script.ts、Node CLI コマンド、CI タスク、単発のシード実行など、短時間だけ実行するスクリプト向けです。リクエストループ内で実行されるコードには使用しません。

セマンティクス：

• close() は冪等です。 2 回呼び出しても何も起きません。
• close() は終端処理です。 閉じた db は再接続しません。別の接続が必要な場合は、新しいクライアントを構築してください。close 後に db.runtime()、db.connect(...)、db.transaction(...)、db.prepare(...) を呼び出すと、Error('<target> client is closed') で拒否されます（例：'Postgres client is closed'、'SQLite client is closed'、'Mongo client is closed'）。
• close() は実行中のクエリを中断しません。 close() を呼び出す前に、処理中の作業を await してください。close() 後も保持されている db.runtime().execute(plan) の非同期イテレーターと PreparedStatement ハンドルは、次回の呼び出し時に失敗します。
• 所有権。 close() が解放するのは、ファサードが構築したもの（{ url } からの pg.Pool、{ url } / { uri, dbName } からの MongoClient、{ path } からの SQLite ハンドル）だけです。独自の pg.Pool / pg.Client（Postgres の pg: オプション）、mongodb.MongoClient（Mongo の mongoClient: オプション）、または構築済みの binding を渡した場合、db.close() はそれらに触れません。そのライフサイクルはご自身で管理してください。

db.end() は存在しません。 node-postgres で一般的に使われる名前は、pg.Pool の pool.end() です。Prisma Next のランタイムクライアントは pg.Pool ではありません。適切な呼び出しは await db.close() です。

ワークフロー — テレメトリーミドルウェア

概要：テレメトリーミドルウェアはすべての操作を検知し、それぞれに対して構造化イベント（開始、成功、エラー）を出力します。各イベントを、使用しているオブザーバビリティスタックのコレクターに渡します。

import postgres from '@prisma-next/postgres/runtime';
import { createTelemetryMiddleware } from '@prisma-next/middleware-telemetry';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

export const db = postgres<Contract>({
  contractJson,
  url: process.env['DATABASE_URL'],
  middleware: [
    createTelemetryMiddleware({
      onEvent: (event) => {
        // forward to your collector, log, etc.
      },
    }),
  ],
});

createTelemetryMiddleware は、ユーザーが個別にインストールできる別パッケージ（@prisma-next/middleware-telemetry）として提供されており、Postgres ファサードの /middleware サブパスではありません。直接インストールしてください。pnpm ls @prisma-next/middleware-telemetry を実行して、ロックファイルに含まれていることを確認してください。

ワークフロー — Lint と予算のミドルウェア

概要：Lint は型チェックをすり抜ける記述ミス（大きなテーブルに対する WHERE のない DELETE や LIMIT のない SELECT など）を検出し、予算は実行時に行数とレイテンシの上限を適用します。どちらも構造化エラーエンベロープを通じて検出結果を提示するため、エージェントはコードに基づいて分岐できます。

これらは基盤となる SQL ランタイムパッケージ（@prisma-next/sql-runtime）に含まれており、Postgres ファサードからはまだ再エクスポートされていません。Prisma Next がまだ対応していないことを参照してください。正規のインポート方法は、examples/prisma-next-demo/src/prisma/db.ts 以下のサンプルアプリで確認できます。

import postgres from '@prisma-next/postgres/runtime';
import { budgets, lints } from '@prisma-next/sql-runtime';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

export const db = postgres<Contract>({
  contractJson,
  url: process.env['DATABASE_URL'],
  middleware: [
    lints({
      severities: {
        selectStar: 'warn',
        noLimit: 'error',
        deleteWithoutWhere: 'error',
        updateWithoutWhere: 'error',
        readOnlyMutation: 'error',
      },
    }),
    budgets({
      maxRows: 10_000,
      defaultTableRows: 10_000,
      tableRows: { user: 10_000, post: 50_000 },
      maxLatencyMs: 1_000,
      severities: { rowCount: 'error', latency: 'warn' },
    }),
  ],
});

オプションの全容については、ソースを確認してください：packages/2-sql/5-runtime/src/middleware/lints.ts と .../budgets.ts。severities のキー（Lint 用の selectStar、noLimit、deleteWithoutWhere、updateWithoutWhere、readOnlyMutation、予算用の rowCount、latency）が正となる情報源です。ripgrep で見つからないキーを推測で追加しないでください。

ワークフロー — 複数のミドルウェアを組み合わせる

middleware: [
  createTelemetryMiddleware({ onEvent }),  // outermost — sees all sub-failures as inner errors
  lints({ severities: { noLimit: 'error' } }),
  budgets({ maxLatencyMs: 5_000 }),         // innermost — runs closest to the driver
],

順序は重要です。外側に置いたものがラップします。テレメトリーを最初に置くと、予算や Lint の失敗がスパンとして記録されます（エージェントは、同じトレース内の操作と Lint コードを関連付けられます）。

ワークフロー — 接続を設定する

基本的な考え方：ランタイムでは、url、pg（あらかじめ構築された pg.Pool または pg.Client）、binding（明示的な種類タグ）の3つのいずれかの形式でバインディングを指定します。これらは相互に排他的です。pg 形式は、独自のプールをすでに管理しているプロジェクト（例：Lambda レイヤー）向けです。デフォルトは url です。プールの調整には poolOptions.connectionTimeoutMillis / poolOptions.idleTimeoutMillis を使います。driverOptions ではありません。

// Default — URL string, factory constructs the pool.
postgres<Contract>({
  contractJson,
  url: process.env['DATABASE_URL'],
  poolOptions: {
    connectionTimeoutMillis: 20_000,
    idleTimeoutMillis: 30_000,
  },
});

// BYO pool — pass a pg.Pool you already created.
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
postgres<Contract>({ contractJson, pg: pool });

型レベルで url と pg キーは相互に排他的です。両方を渡すとエラーになります。

DATABASE_URL は .env に記述します。CLI は emit / verify / migration コマンドでこれを読み込み、ランタイムは db.ts の読み込み時に process.env から読み込みます。

ワークフロー — 環境ごとの設定（dev と prod）

基本的な考え方：環境ごとに DATABASE_URL を1つ設定し、残りの db.ts の構成は同じにします。ミドルウェアの動作を環境によって変える場合（例：dev のみ厳格な lint を適用する場合）は、db.ts で process.env['NODE_ENV'] に基づいて分岐します。

const isProd = process.env['NODE_ENV'] === 'production';

export const db = postgres<Contract>({
  contractJson,
  url: process.env['DATABASE_URL'],
  middleware: isProd
    ? [createTelemetryMiddleware({ onEvent })]
    : [
        createTelemetryMiddleware({ onEvent }),
        lints({ severities: { noLimit: 'error', deleteWithoutWhere: 'error' } }),
      ],
});

ローカルでは .env を使い、prod ではデプロイ先プラットフォームのシークレットを使います。.env をコミットしてはいけません。

ワークフロー — トランザクション

この考え方は Postgres と SQLite に適用されます。db.transaction(fn) はトランザクションを開始し、db と同じ sql / orm インターフェースを持つ tx コンテキストをコールバックに渡します。正常に戻るとコミットし、エラーがスローされるとロールバックします。コールバック内では、書き込みがトランザクション内で実行されるように、db.sql / db.orm ではなく tx.sql と tx.orm を使います。Mongo ファサードには db.transaction(...) がありません。

await db.transaction(async (tx) => {
  const user = await tx.orm.User.create({ email: '[email protected]' });
  await tx.orm.Post.create({ userId: user.id, title: 'hello' });
  // If either call throws, both inserts roll back.
});

コールバックは、返した値をそのまま返します。トランザクションラッパーはその値を呼び出し元に渡します。tx オブジェクトは、トランザクション内で SQL ビルダープランを実行するための execute(plan) を公開します。

ワークフロー — Postgres、SQLite、Mongo を切り替える

基本的な考え方：ファサードの選択は db.ts（@prisma-next/postgres、@prisma-next/sqlite、または @prisma-next/mongo）と prisma-next.config.ts（どの defineConfig をインポートするか）に組み込まれます。プロジェクトの対象を切り替えるには、同じディレクトリで prisma-next init を再実行し、別の対象を選択します。init フローは既存のスキャフォールドを検出し、再初期化するか確認します（--force を指定すると確認を省略します）。PN は新しいファサード向けに prisma-next.config.ts と db.ts を再スキャフォールドします。新しい対象の慣用表現に合わせて、コントラクトソースを書き直す必要があります（Mongo ではネストされたドキュメントを表現し、Postgres / SQLite ではリレーションを表現します）。

切り替え後（Mongo）：

// src/prisma/db.ts (Mongo)
import mongo from '@prisma-next/mongo/runtime';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

export const db = mongo<Contract>({ contractJson, url: process.env['DATABASE_URL'] });

SQLite：

// src/prisma/db.ts (SQLite)
import sqlite from '@prisma-next/sqlite/runtime';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

export const db = sqlite<Contract>({ contractJson, path: 'app.db' });

構築時の path は省略可能です（後から db.connect({ path }) を呼び出せます）。省略しても、ファサードはクライアントを返します。SQLite ファサードは、Postgres と同じ db.sql、db.orm、db.transaction(...)、db.close()、[Symbol.asyncDispose] のインターフェースを公開します。Mongo ファサードは db.orm、db.close()、[Symbol.asyncDispose] を共有しますが、db.sql と db.transaction(...) はありません。

db.sql / db.orm のインターフェース名は変わりませんが、それぞれが公開する演算子は対象ごとに異なります（Mongo には JOIN がありません）。

ワークフロー — ビルドシステム／開発サーバーとの統合

コントラクトソースが変更されるたびに prisma-next contract emit を手動で実行するのではなく、開発サーバーの実行中にコントラクト成果物を自動で再生成したい場合は、prisma-next-build のビルドツールプラグインを使います。

• Vite：@prisma-next/vite-plugin-contract-emit をインストールし、vite.config.ts で prismaVitePlugin('prisma-next.config.ts') を登録します。
• Next.js、Webpack、esbuild、Rollup、Turbopack：現時点で公式プラグインはありません。代替策として、prisma-next contract emit を実行する prebuild スクリプトを使います。手順については prisma-next-build を参照してください。

ランタイム側（このスキル）は、どの方法でも同じです。db.ts はディスクから contract.json と contract.d.ts を読み込みます。ビルドシステムプラグインの役割は、開発中にこれらのファイルを最新の状態に保つことです。

よくある落とし穴

1. prisma-next.config.ts に DATABASE_URL をハードコードする。 認証情報が漏えいし、環境ごとの上書きができなくなります。.env を使用してください。
2. postgres<Contract>(...) で <Contract> 型パラメーターを省略する。 省略すると、静的な型情報が汎用的な形に縮小され、モデルのオートコンプリートが使えなくなります。型パラメーターは 2 つではありません。以前の 2 パラメーター形式（postgres<Contract, TypeMaps>）は廃止されています。
3. コントラクトのインポートに with { type: 'json' } を付け忘れる。 Node の ESM JSON インポート属性仕様で必須です。
4. ミドルウェアの順序は重要です。 外側のミドルウェアが内側をラップします。内側のミドルウェアのエラーをテレメトリーで捕捉したい場合は、テレメトリーを最初に配置してください。
5. 存在しないファサードのサブパスからミドルウェアをインポートする。 @prisma-next/postgres/middleware は存在しません。テレメトリーは @prisma-next/middleware-telemetry から、lint／予算は現在 @prisma-next/sql-runtime から取得します（Prisma Next がまだ対応していないことを参照）。
6. lint／予算のオプション名を思い込みで決める。 lint で指定するのは（上記 5 つのキーを持つ）severities であり、requireWhere／maxRowsWithoutLimit ではありません。予算では maxLatencyMs（maxDurationMs ではありません）に加えて、maxRows／defaultTableRows／tableRows を使用します。迷ったらソースを読んでください。
7. 再出力せずにターゲットを切り替える。 コントラクトの成果物はターゲットに応じた形式です。ターゲットを変更したら出力してください。
8. Postgres でクエリの完了後もスクリプトが終了しない。 pg.Pool が Node のイベントループを動作中のままにします。解決方法：スクリプトの終了前に await db.close() を呼び出すか、スクリプトモジュールの先頭で await using db = postgres<Contract>(...) を使用します。リクエストハンドラー内に await using db = postgres(...) を記述してはいけません。ブロックスコープのため、リクエストのたびにプールが閉じられます。サーバーでの適切なパターンは、プロセスの存続期間中保持される db.ts 内のモジュールレベルのシングルトンです。

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

• @prisma-next/postgres/middleware サブパス。 Postgres ファサードはランタイムファクトリー（./runtime）、設定（./config）、コントラクトビルダー（./contract-builder）、制御（./control）、ファミリー（./family）、ターゲット（./target）、サーバーレス（./serverless）を再エクスポートしますが、ミドルウェアは再エクスポートしません。現在の回避策：lints と budgets は @prisma-next/sql-runtime から、createTelemetryMiddleware は @prisma-next/middleware-telemetry からインポートしてください。遭遇したその他の不足点は、prisma-next-feedback 経由で報告してください。
• 複数データベースへのルーティング／読み取りレプリカ。 Prisma Next には、標準搭載のプライマリー／レプリカルーターやシャード対応クライアントはありません。回避策：データストアごとに個別の db.ts インスタンスを設定し、アプリケーションコードから適切なものを呼び出してください。複数データベースへのルーティングを標準機能として必要とする場合は、prisma-next-feedback スキル経由で機能リクエストを送信してください。
• 第一級の設定フィールドとしての接続プーリング。 poolOptions.connectionTimeoutMillis と poolOptions.idleTimeoutMillis は接続されていますが、その他の pg.Pool のチューニング項目（最大接続数、allowExitOnIdle、SSL オプションなど）は、名前を指定して公開されていません。回避策：独自に pg.Pool を作成し、pg: 経由で渡してください。ファサードで公開するプールフィールドの追加が必要な場合は、prisma-next-feedback スキル経由で機能リクエストを送信してください。
• 標準搭載のクエリロガーミドルウェア。 Prisma Next には「すべてのクエリをログに記録する」ミドルウェアはありません。回避策：各操作をラップしてログを記録する小さなカスタムミドルウェアを作成するか、createTelemetryMiddleware を使用して onEvent コールバック内でログを記録してください。標準搭載のクエリログが必要な場合は、prisma-next-feedback スキル経由で機能リクエストを送信してください。

参考ファイル

このスキルは意図的に本文のみで構成されています。オプションの詳細については、prisma-next init --help、packages/3-extensions/postgres/src/config/define-config.ts の defineConfig ファクトリー、packages/3-extensions/postgres/src/runtime/postgres.ts の postgres() ファクトリー、および packages/2-sql/5-runtime/src/middleware/{lints,budgets}.ts のミドルウェアソースが正式な情報源です。迷ったらソースを読んでください。

チェックリスト

• db.ts が @prisma-next/<target>/runtime（postgres、sqlite、または mongo）からランタイムファクトリーをインポートし、./contract.d から Contract 型をインポートしている。
• コントラクトの JSON インポートに with { type: 'json' } を指定している。
• postgres<Contract>(...) の型パラメーターは <Contract> のみ（2 つ目のパラメーターは指定しない）。
• DATABASE_URL は .env に記述し、prisma-next.config.ts には記述していない。
• ミドルウェアの順序を意図的に設定している（通常、テレメトリーを最外側にする）。
• lints／budgets では、確認済みのオプションキー（severities、maxLatencyMs、maxRows、tableRows）を使用している。
• 環境ごとの差異がある場合は、NODE_ENV などで条件を分けている。
• コミットするファイルに認証情報をハードコードしていない。
• @prisma-next/postgres/middleware というサブパス、@prisma-next/postgres-extension-audit パッケージ、または postgres<...> の 2 つ目の型パラメーターを捏造していない。
• Mongo ファサードで db.transaction(...) が利用できると主張していない。これを公開しているのは Postgres と SQLite のみ。
• 読み取りレプリカ／複数 DB／追加のプール設定を捏造していない。Prisma Next がまだ対応していない機能 を案内し、prisma-next-feedback に誘導している。
• ビルドシステム／開発サーバーに関するプロンプト（Vite プラグイン、Next.js プラグインなど）は、prisma-next-build に誘導している。