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

> Prisma ORMをv6からv7へ安全に移行する実装ガイド。Rustエンジン廃止とdriver adapter必須化、generatorのprisma-client化（output必須・node_modules脱却・import元変更）、prisma.config.tsへの設定移行、$useミドルウェア廃止→Client Extensions、Prisma.validatorのレガシー化→satisfies、自動シード廃止、削除CLIフラグまでを、破壊的変更ごとの手順とチェックリストで解説します。

- 公開日: 2026-06-26
- 著者: 友田 陽大
- タグ: Prisma, TypeScript, PostgreSQL, アーキテクチャ設計, 型安全
- URL: https://tomodahinata.com/blog/prisma-orm-v6-to-v7-migration-guide

## 要点

- v7の核はRustエンジン廃止。クエリエンジンがTS＋WASMになり、全DBでdriver adapter（PostgreSQLは@prisma/adapter-pg）が必須。公式ベンチで最大3.4倍・バンドル約90%減
- generatorがprisma-clientへ。outputが必須でnode_modulesに生成されなくなり、importは@prisma/clientから生成先パスへ全面変更
- 設定はprisma.config.tsへ。defineConfig＋envで宣言。環境変数は自動読込されないのでdotenvを併用する
- $useミドルウェアは削除→Client Extensions（$extends）へ。Prisma.validatorはレガシー化→TypeScriptのsatisfiesへ
- 自動シード廃止（db seedの明示実行のみ）、一部CLIフラグ削除。まず動く形（generator・adapter・import）に直してから最適化する段階移行が安全

---

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

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

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

---

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

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

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

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

---

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

| 領域 | v6（旧） | v7（現行） |
| --- | --- | --- |
| クエリエンジン | Rust製バイナリを同梱 | **Rustフリー**（TS＋WASMのクエリコンパイラ） |
| generator | `prisma-client-js`（`node_modules`生成） | **`prisma-client`**（`output`必須・コード内生成） |
| driver adapter | 任意（Preview） | **全DBで必須**（PostgreSQLは`@prisma/adapter-pg`） |
| import 元 | `@prisma/client` | **生成先パス**（例 `../generated/prisma/client`） |
| 設定 | `package.json` の `"prisma"` キー | **`prisma.config.ts`**（`defineConfig`） |
| ミドルウェア | `$use` | **削除** → Client Extensions（`$extends`） |
| 検証ヘルパ | `Prisma.validator` | **レガシー化** → `satisfies` |
| シード | `migrate dev`等で自動実行 | **`db seed` の明示実行のみ**（自動廃止） |
| 一部CLIフラグ | `--skip-generate` 等 | 一部**削除** |

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

---

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

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

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

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

```ts
// 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](/blog/prisma-performance-optimization-n-plus-1-connection-pool-guide)）。

---

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

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

```prisma
// 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` 等）。「生成し忘れたまま本番」をビルド手順で塞ぎます。

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

---

## 4. 設定を `prisma.config.ts` へ

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

```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` 拡張へ移植します。

```ts
// 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`** ＋生成型に置き換えます。

```ts
// 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](/blog/prisma-orm-production-guide-type-safe-database-v7-driver-adapters)）。

---

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

### 7.1 自動シードの廃止

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

### 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更新・検証まで、決済基盤での無停止刷新の知見を活かしてお手伝いします。