prisma-upgrade-v7

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

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

適用するタイミング

次の場合は、このスキルを参照してください。

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

優先度別ルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	スキーマの移行	CRITICAL	schema-changes
2	データベース接続	CRITICAL	driver-adapters
3	モジュールシステム	CRITICAL	esm-support
4	設定と環境変数	HIGH	prisma-config, env-variables
5	削除された機能	HIGH	removed-features
6	Accelerate	HIGH	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 7 には MongoDB コネクターがありません。provider = "mongodb" を使用しているプロジェクトには、このガイドの手順を適用しないでください。実際の判断（意図的に v6 を使い続けるか、Prisma 8 に移行するか）については、prisma-mongodb-upgrade スキルを参照してください。

重要な注意事項

• MongoDB プロジェクトは Prisma 6.x を使い続けるか、Prisma 8 に移行してください - MongoDB アプリを Prisma 7 の SQL クライアントの経路に移行しないでください（prisma-mongodb-upgrade を参照）
• 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 を実行してテストする

アップグレードコマンドのクイックリファレンス

# Update packages
npm install @prisma/client@7
npm install -D prisma@7

# Install a driver adapter (PostgreSQL or Prisma Postgres via direct TCP)
npm install @prisma/adapter-pg pg

# Install dotenv for env loading
npm install dotenv

# Regenerate client
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 and CommonJS configuration
references/schema-changes.md     - Generator, output, imports, and generated entrypoints
references/driver-adapters.md    - Required driver adapter setup
references/prisma-config.md      - New configuration file
references/env-variables.md      - Environment variable loading
references/removed-features.md   - Middleware, metrics, and CLI flags
references/accelerate-users.md   - Special handling for 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 を更新する

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

// After (v7)
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
  // Optional if you need 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

# Prisma Postgres in standard Node.js apps (recommended)
npm install @prisma/adapter-pg pg

# Prisma Postgres serverless driver (edge/serverless)
npm install @prisma/adapter-ppg @prisma/ppg

# Neon
npm install @prisma/adapter-neon

公開されている Prisma 7.6.0 パッケージには、MongoDB 用の SQL @prisma/adapter-* パッケージがありません。MongoDB プロジェクトをアップグレードする場合は、ここで作業を中止し、標準的な Prisma 7 の移行手順には進まず、そのプロジェクトを最新の Prisma 6.x リリースで使用してください。

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

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

// After (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  # if needed

トラブルシューティング

「Cannot find module」エラー

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

SSL 証明書エラー

• 以前の動作を維持する必要がある場合は、アダプターの設定に ssl: { rejectUnauthorized: false } を追加します
• または、NODE_EXTRA_CA_CERTS／OpenSSL の CA 設定を使用して証明書を適切に設定します

接続タイムアウトの問題

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

リソース

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

使用方法

まず references/schema-changes.md と references/driver-adapters.md に従い、その後、プロジェクトの設定に応じて残りのリファレンスファイルを適用します。