Prisma v7 マイグレーション戦略：実践ガイド

はじめに

Prisma v7 は、prisma.config.ts の導入や型安全性の強化など、大きな変更が加わったメジャーバージョンです。本記事では、実際のプロジェクトで v6 から v7 に移行した際の知見を共有します。

主な変更点

prisma.config.ts の導入

v7 では、Prisma の設定を TypeScript ファイルで管理できるようになりました。

// prisma.config.ts
import { defineConfig } from "prisma/config";

export default defineConfig({
  earlyAccess: true,
  schema: "./prisma/schema.prisma",
});

Datasource URL の管理

schema.prisma から url を削除し、環境変数や config から注入する形に変更されました。これにより、環境ごとの接続先切り替えがよりクリーンになりました。

移行手順

1. 依存関係の更新

npm install prisma@7 @prisma/client@7

2. prisma.config.ts の作成

プロジェクトルートに prisma.config.ts を作成し、既存の設定を移行します。

3. スキーマの更新

datasource ブロックから url を削除します。

datasource db {
  provider = "postgresql"
  // url は prisma.config.ts から注入
}

4. マイグレーションの実行

export DATABASE_URL="postgresql://..."
npx prisma migrate dev --name v7-migration

遭遇した課題と解決策

Issue 1: 型の非互換

v7 では一部の型定義が変更されています。特に Prisma.XXXCreateInput の一部フィールドの型が厳密化されました。

解決策: prisma generate を実行し直し、型定義を更新します。IDE のキャッシュもクリアします。

Issue 2: トランザクションの挙動変更

$transaction の挙動が一部変更されています。

解決策: 公式ドキュメントを確認し、新しい API に合わせてコードを修正します。

まとめ

Prisma v7 への移行は、いくつかの課題はあるものの、prisma.config.ts による設定管理の改善や型安全性の向上など、メリットが大きいです。段階的に移行を進めることをお勧めします。