はじめに
Prisma ORM v7 が先日リリースされました。
ちょうど新しいサービスを作っているタイミングでアップデートに気づいたのですが、これまでの設定手順ではうまく動かない部分があり少し苦戦しました。
せっかくなので、つまずいた点や変更内容をまとめていこうと思います。
Prisma ORM v7 について
今回のリリースは、設計思想そのものが大きく変わったアップデートとなっています。
Prismaはこれまで、 どこでも安定して使える汎用性を重視し、Rust 製のクエリエンジンと Node.js バインディングによる構成を採用していました。
しかし、サーバレスやエッジなどの Node.js に依存していない環境で扱いにくかったり、ビルドやデプロイが複雑になってしまったりなどの課題がありました。
また、Prisma へのコミットには Rust と TypeScript 両方の知識が必要であり、コミュニティへの参画のハードルを高めていました。
さらに、現在のwebアプリケーションの実行環境が JavaScript / TypeScript 互換の実行基盤へ広がっている現状 を踏まえ、Prisma は TypeScript を中心とした設計へ移行する方針を打ち出しました。
これにより、今回のリリースでは TypeScript に最適化された設計 となっています。
主な新機能や改善点
1. Rust-free / ESM Prisma Client のデフォルト化
- Rust 製エンジンを廃し、TypeScript + WebAssembly / ESM ベースの Prisma Client がデフォルトに
- バンドル出力が90%縮小
- クエリ実行速度が3倍高速化
- CPUとメモリ使用率が大幅に低減
- Vercel EdgeおよびCloudflare Workers向けのデプロイが簡素化
移行の方法は下記のようにシンプルで良いですね。
generator client {
- providor = "prisma-client-js"
+ providor = "prisma-client"
}
2. 型生成 & TypeScript サポートの強化
- 型生成の最適化
- スキーマに対して生成・評価される型数が 約98%削減
- クエリの型推論に必要な型が 約45%削減
- TypeScript の型チェックが 約70%高速化
これによりエディタの補完や応答性も大幅に改善されました。
3. クライアント生成先の見直し & 新設定ファイルの導入
- 設定 (データソースの URL、migration/seed 設定など) を一元管理できる prisma.config.ts ファイルが必須に。CLI や設定の混在による混乱を防ぎ、動的設定 (dotenv 等) も可能に。
- これまで node_modules に自動生成されていた Prisma Client/型定義を、プロジェクト内 (例: src/generated/prisma) に出力する構成が標準に。
これらにより、ソースコードとして Prisma の設定や生成された型を管理できるので、環境による差異など起こりにくくなりました。
((ちなみに私は、この変更を全く知らなかったのでとても詰まりました💦))
下記のように設定できます！
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'
export default defineConfig({
schema: 'prisma/schema.prisma', // schema定義のパス
migrations: {
path: 'prisma/migrations', // migrationファイルたちのパス
seed: 'tsx prisma/seed/init.ts' // '$ prisma db seed' で実行されるコマンド
},
datasource: {
url: env('DATABASE_URL'),
},
})
これに伴い、datasourceの定義を消すことができます。
generator client {
provider = "prisma-client"
+ output = "./generated/prisma" // 生成ファイルの出力先
}
datasource db {
provider = "postgresql"
- url = env("DATABASE_URL")
}
また、生成先も変わるので、import元のパスも変更する必要があります。
- import { PrismaClient } from '@prisma/client'
+ import { PrismaClient } from './generated/prisma/client'
4. 新しくなった Prisma Studio の CLI 統合
- v7 で、CLI から起動する Prisma Studio が刷新。データベースのレコードやリレーションをより分かりやすく可視化・操作でき、リレーション構造の把握も容易に。
5. その他
- mapped enums のサポートなど、以前から要望のあった機能が v7 で取り入れられ、TypeScript + 型安全 + DB スキーマの整合性をより強化。
- Node.js や TypeScript のバージョン要件を引き上げ。最新環境での安定性とモダン開発体験を重視。
- 最低: Node.js 20.19 / TS 5.4.0
- 推奨: Node.js 22.x / TS 5.9.x
破壊的変更
- いくつかの破壊的変更があるので、まとめます。
1. 設定ファイルの追加
- 3. クライアント生成先の見直し & 新設定ファイルの導入 の章で紹介した内容です。
2. クライアントインスタンス化時にドライバーアダプターが必須に
- PostgreSQLを使用している場合には、
PrismaPgというアダプターを使用する必要があります。
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client'
const globalForPrisma = global as unknown as {
prisma: PrismaClient
}
const adapter = new PrismaPg({
connectionString: process.env.DATABASE_URL,
})
export const prisma =
globalForPrisma.prisma ||
new PrismaClient({
adapter,
})
if (process.env.NODE_ENV !== 'production') {
globalForPrisma.prisma = prisma
}
- SQLiteを使用している場合には、
PrismaBetterSqlite3というアダプターを使用する必要があります。
import { PrismaClient } from './generated/prisma/client'
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
const globalForPrisma = global as unknown as {
prisma: PrismaClient
};
const adapter = new PrismaBetterSqlite3({
connectionString: process.env.DATABASE_URL || 'file:./local.db',
})
export const prisma =
globalForPrisma.prisma ||
new PrismaClient({
adapter,
})
if (process.env.NODE_ENV !== 'production') {
globalForPrisma.prisma = prisma
}
3. 暗黙の自動実行が削除
ポストインストールフックが削除されました。
インストール時に自動で走らなくなるため、明示的に実行する必要があります。
$ npx prisma generate
また、$ prisma migrate dev や $ prisma migrate reset を実行すると、シードスクリプトが自動的に実行されていましたが、削除されました。
v7 でデータベースにシードするには、明示的に実行する必要があります。
$ npx prisma db seed
まとめ
以上が、Prisma ORM v7 のまとめとなります。
書き方が結構変わっていたり、利用するための最低Node等のバージョン等もあるので、注意して導入してみてください！
また、いくつかまだうまく動作していない部分があるような記事も見かけたので、その辺りも注意が必要です。
参考
Discussion