Prisma v6 → v7 移行ガイド：Rustフリー化・driver adapter必須化・prisma-client generator・prisma.config.ts・ミドルウェア廃止を安全に乗り越える

Prisma ORM v7（2025年11月リリース）は、単なるバージョンアップではなくアーキテクチャの世代交代です。長年同梱されてきた Rust製クエリエンジンが廃止され、クライアントの生成方式・接続方式・設定の置き場所まで変わりました。恩恵は大きい——公式ベンチマークで最大3.4倍高速・バンドル約90%減（約14MB→1.6MB）、エッジ/サーバーレスへの展開が劇的に単純化されます。一方で、v6 のコードはそのままでは動きません。

この記事は、Prisma を v6 から v7 へ安全に移行するための実装ガイドです。破壊的変更を1つずつ、手順とともに潰していきます。v7 前提の新規実装はPrisma ORM 本番運用ガイド（v7）に、移行後のデータモデリング・マイグレーション・パフォーマンスは各スポーク記事にまとめています。

この記事のルール：手順・破壊的変更は Prisma 公式の v7 アップグレードガイド/チェンジログ（2026年6月時点） に基づきます。移行は本番に当てる前に必ずステージングで検証し、各公式ドキュメントで最新手順を確認してください。題材は PostgreSQL です。

0. メンタルモデル：まず動かし、それから磨く

依存の大型刷新は、一気に全部を「あるべき姿」へ書き換えようとすると沼ります。私が決済基盤の依存刷新で守ったのは、「まず最小の変更で動く形にし、それから段階的に最適化する」という順序です。

v7 移行も同じです。最初に直すべきは3点だけ——generator・driver adapter・import パス。これで Prisma は動き出します。Client Extensions 化や prisma.config.ts の整備、satisfies への置換は、動いてから順に進めればよい。「動く」と「綺麗」を分けることが、移行を完了させるコツです。

移行の最短経路：① generator を prisma-client ＋ output 指定 → ② driver adapter で PrismaClient を生成 → ③ import 元を生成先パスへ。ここまでで起動する。残りは後追い。

1. 何が変わったのか（破壊的変更の全体像）

以下、移行で手を動かす順に解説します。

2. driver adapter の導入と PrismaClient の再構築

Rustエンジンが消えたため、接続を担う driver adapter を明示的に入れます。これが v7 移行の心臓部です。

npm install @prisma/client@7 @prisma/adapter-pg
npm install -D prisma@7

PrismaClient の生成を、adapter 必須の形に書き換えます。

// v6（旧）
// import { PrismaClient } from "@prisma/client";
// export const prisma = new PrismaClient();

// v7（新）
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client"; // ← 生成先からimport

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
export const prisma = new PrismaClient({ adapter });

公式は v7 の変更を「新しい Prisma Client の作り方は、全DBで driver adapter を要求するように変わった」と明言しています。接続プールのチューニングも、接続文字列のクエリパラメータではなくadapter 側のオプションに移った点に注意します（→パフォーマンス最適化ガイド §5）。

3. generator を prisma-client へ（output 必須）

スキーマの generator ブロックを書き換えます。output が必須になり、生成物は node_modules ではなくあなたのリポジトリ内に出ます。

// v6（旧）
// generator client {
//   provider = "prisma-client-js"
// }

// v7（新）
generator client {
  provider     = "prisma-client"          // 新generator
  output       = "../src/generated/prisma" // 生成先（必須）
  runtime      = "nodejs"                  // 必要なら edge/bun などへ
  moduleFormat = "esm"                     // esm | cjs
}

これに伴う実務対応。

• import 元を全面置換：@prisma/client → 生成先パス（例 @/generated/prisma/client）。PrismaClient・Prisma 名前空間・エラー型すべて。エディタの一括置換で機械的に直せます。
• 生成物は .gitignore：src/generated/ を無視し、CI/デプロイのビルド前に prisma generate を必ず走らせます（postinstall 等）。「生成し忘れたまま本番」をビルド手順で塞ぎます。

npx prisma generate # 新generatorでクライアントを再生成

4. 設定を prisma.config.ts へ

v6 で package.json の "prisma" キーに置いていた設定（シード等）を、型安全な prisma.config.ts へ移します。

// prisma.config.ts（プロジェクト直下）
import "dotenv/config"; // v7は環境変数を自動読込しない
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: "tsx prisma/seed.ts",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

ハマりどころ：v7 は環境変数を自動で読み込みません。import "dotenv/config" 等で明示的にロードします。設定がコードになることで、モノレポやCIでの再現性が上がります。

5. ミドルウェア $use → Client Extensions

$use ミドルウェアは v7 で削除されました。公式の文言は「クライアントミドルウェアAPIは削除された。可能なら Client Extensions を使え」。ロギングや計測は $extends の query 拡張へ移植します。

// v6（旧）：$use ミドルウェア
// prisma.$use(async (params, next) => {
//   const start = Date.now();
//   const result = await next(params);
//   console.log(`${params.model}.${params.action} ${Date.now() - start}ms`);
//   return result;
// });

// v7（新）：Client Extensions
export const prisma = basePrisma.$extends({
  query: {
    $allModels: {
      async $allOperations({ model, operation, args, query }) {
        const start = performance.now();
        const result = await query(args);
        console.log(JSON.stringify({ model, operation, ms: Math.round(performance.now() - start) }));
        return result;
      },
    },
  },
});

Extensions は拡張ごとに新しいクライアントを返すため、適用範囲を限定でき、型も保たれます。ミドルウェアより安全な設計です。

6. Prisma.validator → satisfies

Prisma.validator<...>() は**レガシー（旧 prisma-client-js 専用）**になり、新 generator では使えません。TypeScript ネイティブの satisfies ＋生成型に置き換えます。

// v6（旧）
// const userSelect = Prisma.validator<Prisma.UserSelect>()({ id: true, email: true });

// v7（新）：satisfies で同等の型チェック
import { Prisma } from "./generated/prisma/client";

const userArgs = { include: { posts: true } } satisfies Prisma.UserDefaultArgs;
type UserWithPosts = Prisma.UserGetPayload<typeof userArgs>;

satisfies は「リテラルの形を生成型に適合させつつ、推論を保つ」ため、validator の役割をより素直に果たします（→Prisma 本番運用ガイド §4）。

7. シードと CLI フラグの変更

7.1 自動シードの廃止

v7 では「シードは npx prisma db seed の明示実行でのみ起動。migrate dev / migrate reset 時の自動シードは廃止」されました。CIやローカルで「リセットしたら勝手に入る」前提のスクリプトは、明示実行に直します。シード本体も driver adapter 必須です（→Migrate 本番運用ガイド §8）。

7.2 削除された CLI フラグ

--skip-generate / --skip-seed や一部のDB URLフラグなどが削除されました。CI スクリプトやドキュメントにこれらが残っていないか確認し、prisma.config.ts ベースの構成に寄せます。

その他の留意点：Metrics プレビュー機能の削除など、利用していた周辺機能が影響を受ける場合があります。自プロジェクトで使っている機能を、公式の v7 アップグレードガイドの一覧と突き合わせて確認してください。

8. 移行の進め方（推奨フロー）

段階移行を、安全な順序で。

1. ブランチを切り、ステージングで検証（本番に直接当てない）。
2. 依存を更新（prisma・@prisma/client を v7、@prisma/adapter-pg を追加）。
3. generator を prisma-client ＋ output、prisma generate。
4. PrismaClient を adapter 付きに、import を生成先パスへ一括置換。→ ここでまず動く。
5. 型エラーを潰す（Prisma 名前空間・エラー型の import 元も生成先へ）。
6. $use を Extensions へ、validator を satisfies へ。
7. 設定を prisma.config.ts に移し、シードを db seed 明示実行に。
8. CIを更新：ビルド前 prisma generate、本番適用は migrate deploy、削除フラグを除去。
9. 回帰テスト/E2Eで主要フローを確認し、ステージング→本番へ。

可観測性と切り戻し：移行PRは小さく分け、各段でテストを通します。万一に備え、依存のバージョン固定とロールバック手順を用意しておくこと。アプリの依存刷新も、決済の無停止移行と同じく「段階・検証・切り戻し可能」を守れば怖くありません。

9. v6 → v7 移行チェックリスト

• prisma / @prisma/client を v7、driver adapter（@prisma/adapter-pg）を追加
• generator を prisma-client に、output を指定、prisma generate 実行
• new PrismaClient({ adapter }) に書き換え（adapter 必須）
• import 元を生成先パスへ一括置換（PrismaClient・Prisma・エラー型）
• 生成物を .gitignore、CI/デプロイのビルド前に prisma generate を強制
• $use ミドルウェアを Client Extensions（$extends） へ移植
• Prisma.validator を satisfies ＋ GetPayload へ置換
• 設定を prisma.config.ts（defineConfig＋env）へ。dotenv で環境変数を明示ロード
• シードを db seed 明示実行に（自動シード前提を撤去）
• 削除された CLIフラグ（--skip-generate 等）をスクリプトから除去
• 接続プール設定を adapter 側へ移行
• ステージングで回帰テスト/E2E → 段階的に本番へ。切り戻し手順を用意

まとめ

Prisma v7 への移行は、見出しこそ多いものの、核は「driver adapter 必須化」と「generator の prisma-client 化」の2つです。まずこの2点（＋import 置換）で動かし、それから Extensions 化・prisma.config.ts・satisfies を順に整える——「動く」と「綺麗」を分ける段階移行なら、安全に完了できます。得られるのは、Rustフリー化による速度・軽量性・エッジ展開の容易さという実利です。

「Prisma v7 への移行を、本番を止めずに安全に完了させたい」「依存の大型刷新を、段階移行と回帰テストで事故なく進めたい」——移行計画の設計からPR分割・CI更新・検証まで、決済基盤での無停止刷新の知見を活かしてお手伝いします。