Prisma ORM 7 へのアップグレード

Prisma ORM v6 から v7 への移行の完全ガイドです。このアップグレードでは、新しい prisma-client ジェネレーター、ドライバーアダプター、prisma.config.ts、明示的な環境読み込み、生成されたクライアントエントリポイントに関する重大な破壊的変更が導入されています。

適用時期

以下の場合、このスキルを参照してください:

• Prisma v6 から v7 へのアップグレード
• prisma-client ジェネレーターへの更新
• ドライバーアダプターのセットアップ
• prisma.config.ts の設定
• アップグレード後のインポートエラーの修正

優先度別のルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	スキーマ移行	重大	schema-changes
2	データベース接続	重大	driver-adapters
3	モジュールシステム	重大	esm-support
4	設定と環境	高	prisma-config, env-variables
5	削除される機能	高	removed-features
6	Accelerate	高	accelerate-users

クイックリファレンス

• schema-changes - ジェネレーターの移行、必須の出力パス、生成されたエントリポイント、Prisma.validator の置き換え
• driver-adapters - SQL プロバイダーに必須のアダプターインストール、プール差分、Prisma Postgres アダプターの選択肢
• esm-support - ESM ファースト セットアップ、および moduleFormat = "cjs" での CommonJS フォールバック
• prisma-config - prisma.config.ts の作成と使用
• env-variables - 明示的な環境読み込み
• removed-features - 削除されたミドルウェア、メトリクス、レガシー CLI 動作
• accelerate-users - Accelerate ユーザー向けの移行に関する注記

重要な注記

• MongoDB プロジェクトは Prisma 6.x に留まるべき - MongoDB アプリを Prisma 7 の SQL クライアントパスに移行しないでください
• Node.js 20.19.0 以上 が必須
• TypeScript 5.4.0 以上 が必須
• 最新の安定版 Prisma ORM バージョン: 7.6.0

アップグレード手順の概要

1. パッケージを v7 に更新
2. モジュール形式を選択 (デフォルトは esm、必要な場合は cjs)
3. TypeScript 設定を更新
4. スキーマ ジェネレーターブロックを更新
5. prisma.config.ts を作成
6. SQL プロバイダー用のドライバーアダプターをインストールして設定
7. Prisma Client インポートを更新
8. クライアント インスタンス化を更新
9. Prisma.validator などの非推奨ヘルパーパターンを置き換え
10. prisma generate を実行してテスト

クイックアップグレードコマンド

# パッケージを更新
npm install @prisma/client@7
npm install -D prisma@7

# ドライバーアダプターをインストール (PostgreSQL または直接 TCP 経由の Prisma Postgres)
npm install @prisma/adapter-pg pg

# 環境読み込み用に dotenv をインストール
npm install dotenv

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

破壊的変更のまとめ

変更	v6	v7
モジュール形式	暗黙的/混合	ESM ファースト、moduleFormat = "cjs" サポート
ジェネレータープロバイダー	prisma-client-js	prisma-client がデフォルト、レガシーセットアップ用に prisma-client-js も存在
出力パス	自動 (node_modules)	明示的指定が必須
ドライバーアダプター	オプション	SQL プロバイダーに必須
設定ファイル	.env + スキーマ	prisma.config.ts
環境読み込み	自動	手動 (dotenv)
生成されたエントリポイント	単一パッケージエクスポート	client, browser, models, enums エントリポイント
型安全クエリフラグメント	Prisma.validator()	TypeScript satisfies
ミドルウェア	$use()	クライアント拡張
メトリクス	プレビュー機能	削除

ルールファイル

各破壊的変更の詳細な移行ガイド:

references/esm-support.md        - ESM および CommonJS 設定
references/schema-changes.md     - ジェネレーター、出力、インポート、生成されたエントリポイント
references/driver-adapters.md    - 必須のドライバーアダプター設定
references/prisma-config.md      - 新しい設定ファイル
references/env-variables.md      - 環境変数読み込み
references/removed-features.md   - ミドルウェア、メトリクス、CLI フラグ
references/accelerate-users.md   - Accelerate 用の特別な対応

ステップバイステップ移行

1. ESM ファーストプロジェクト向けに package.json を更新

{
  "type": "module"
}

CommonJS に留まる必要がある場合は、アプリを CJS のまま保ち、ESM を強制する代わりにジェネレーターブロックで moduleFormat = "cjs" を設定してください。

2. tsconfig.json を更新

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2023",
    "strict": true,
    "esModuleInterop": true
  }
}

3. schema.prisma を更新

// 前 (v6)
generator client {
  provider = "prisma-client-js"
}

// 後 (v7)
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
  // CommonJS が必要な場合はオプション:
  // moduleFormat = "cjs"
}

4. prisma.config.ts を作成

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

5. ドライバーアダプターをインストール (SQL プロバイダーのみ)

# PostgreSQL
npm install @prisma/adapter-pg pg

# MySQL
npm install @prisma/adapter-mariadb mariadb

# SQLite
npm install @prisma/adapter-better-sqlite3 better-sqlite3

# 標準 Node.js アプリ用 Prisma Postgres (推奨)
npm install @prisma/adapter-pg pg

# Prisma Postgres サーバーレスドライバー (エッジ/サーバーレス)
npm install @prisma/adapter-ppg @prisma/ppg

# Neon
npm install @prisma/adapter-neon

MongoDB には、公開済み Prisma 7.6.0 パッケージに SQL @prisma/adapter-* パッケージがありません。MongoDB プロジェクトをアップグレードする場合は、標準 Prisma 7 移行パスに従う代わりに、そのプロジェクトを最新の Prisma 6.x リリースに留めてください。

6. クライアント インスタンス化を更新

// 前 (v6)
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

// 後 (v7)
import { PrismaClient } from '../generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL
})

const prisma = new PrismaClient({ adapter })

7. Prisma.validator を satisfies で置き換え

import { Prisma } from '../generated/prisma/client'

const userSelect = {
  id: true,
  email: true,
  name: true,
} satisfies Prisma.UserSelect

8. マイグレーションを実行して生成

npx prisma generate
npx prisma migrate dev  # 必要な場合

トラブルシューティング

「Cannot find module」エラー

• ジェネレーター output パスがインポートパスと一致していることを確認してください
• prisma generate が正常に実行されたことを確認してください

SSL 証明書エラー

• 古い動作を保持する必要がある場合は、アダプター設定に ssl: { rejectUnauthorized: false } を追加してください
• または NODE_EXTRA_CA_CERTS / OpenSSL CA 設定で証明書を適切に設定してください

接続タイムアウト問題

• ドライバーアダプターは基になるドライバーのデフォルトを使用しており、これは v6 と異なります
• 必要に応じてアダプターでプール設定を明示的に設定してください

リソース

• 公式 v7 アップグレードガイド
• ドライバーアダプター ドキュメント
• Prisma 設定 リファレンス

使用方法

references/schema-changes.md と references/driver-adapters.md を最初に確認してから、プロジェクトセットアップに基づいて残りのリファレンスファイルを適用してください。