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

Prisma ORM 5.0.0では、新しいJSONプロトコルの採用など、多くの変更が導入され、Prisma Clientがデフォルトで高速化されました。これらの変更の完全なリストは、リリースノートで確認できます。

このガイドでは、アップグレードがアプリケーションにどのように影響するか、およびPrisma ORM 5の破壊的変更を処理する方法について説明します。

prismaと@prisma/clientパッケージをバージョン5にアップグレードする

以前のバージョンからPrisma ORM 5にアップグレードするには、prismaと@prisma/clientの両方のパッケージを更新する必要があります。

npm

npm install @prisma/client@5
npm install -D prisma@5

yarn

yarn up prisma@5 @prisma/client@5

pnpm

pnpm upgrade prisma@5 @prisma/client@5

危険

アップグレードする前に、以下の各破壊的変更を確認して、アップグレードがアプリケーションにどのように影響するかを確認してください。

バージョン変更

Prisma ORM 5では、Node.js、TypeScript、PostgreSQLの最小バージョンが変更されています。Prismaバージョン5.0.0以降を使用するには、以下の最小バージョンが必要です。すべての最小バージョン要件については、システム要件を参照してください。

Node.jsの最小バージョン変更

Prisma ORMバージョン5.0.0以降、サポートされるNode.jsの最小バージョンは16.13.0です。プロジェクトがこれより古いバージョンのNode.jsを使用している場合、アップグレードする必要があります。

警告

Node.js v16.xは、OpenSSL 1.1.1のサポート終了と同時に、2023年9月11日にサポート終了となります。そのため、現在のNode.js LTSであるv18.xへのアップグレードを推奨します。Prisma ORM 5がNode.js v16をサポートする最後のメジャーバージョンとなる点にご注意ください。

TypeScriptの最小バージョン変更

Prisma ORMバージョン5.0.0以降、サポートされるTypeScriptの最小バージョンは4.7です。プロジェクトがこれより古いバージョンのTypeScriptを使用している場合、アップグレードする必要があります。

PostgreSQLの最小バージョン変更

Prisma ORMバージョン5.0.0以降、サポートされるPostgreSQLの最小バージョンは9.6です。プロジェクトがこれより古いバージョンのPostgreSQLを使用している場合、アップグレードする必要があります。

警告

Prisma ORMはPostgreSQLバージョン9.6以降をサポートしていますが、現在サポートされており、引き続きアップデートが提供されているバージョンに更新することを強く推奨します。現在サポートされているバージョンを確認するには、PostgreSQLのバージョンポリシーを確認してください。

Prisma Clientに組み込まれたSQLiteのバージョンを更新

Prisma ORMバージョン5.0.0で、組み込みのSQLiteのバージョンを3.35.4から3.41.2にアップグレードしました。破壊的変更は見られず、ユーザープロジェクトでの変更は不要と予想していますが、特にPrisma ORMの機能を越える可能性のある生のクエリでSQLiteを使用している場合は、SQLiteの変更履歴を確認してください。

主な変更点

このセクションでは、Prisma ORM 5における主な破壊的変更の概要を説明します。

rejectOnNotFound パラメータの削除

Prisma ORM 5では、非推奨のパラメータrejectOnNotFoundが削除されました。プロジェクトでrejectOnNotFoundをクエリごと、またはグローバルに使用していたかによって、コードの更新方法が異なります。

rejectOnNotFound パラメータをクエリごとに使用している場合は、クエリレベルでコードを更新する手順に従ってください。

代わりに、rejectOnNotFound パラメータをクライアントレベルで設定していた場合は、クライアントレベルでコードを更新する手順に従う必要があります。

jsonProtocolのプレビュー終了

jsonProtocolプレビュー機能が一般公開されました。この新しいプロトコルは、以前のGraphQLベースのプロトコルと比較して、起動時間を大幅に改善します。Prisma ORM 5にアップグレードする際には、jsonProtocolがプレビュー機能に追加されている場合は、必ず削除してください。

Prisma ORM 4以下

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["jsonProtocol"]
}

Prisma ORM 5

generator client {
  provider = "prisma-client-js"
}

Prisma ORM 5の新しいプロトコルに対応するためにアプリを更新する方法については、jsonProtocol変更ガイドを確認してください。以下の対応が必要です。

• jsonProtocol プレビュー機能の削除
• 特定の配列ショートカットの使用を削除

配列ショートカットの削除

Prisma ORM 5では、いくつかの「配列ショートカット」のサポートを終了します。これらのショートカットは、配列ベースの演算子に単一の要素を配列でラップする代わりに値として追加する方法でした。型定義をより一貫性があり論理的にし、新しいJSONプロトコルに準拠させるため、これらの演算子には配列の値を要求するようになりました。

ほとんどの場合、修正は既存の値を配列でラップするだけで済みます。Prisma ORM 5で削除されたショートカットは以下の通りです。

• OR ショートカット
• in および notIn ショートカット
• PostgreSQL JSON path フィールドショートカット
• スカラーリストショートカット
• MongoDB複合リストショートカット

OR、in、notIn 演算子は影響を受けますが、AND および NOT はこの変更の影響を受けません。

CockroachDBデータベースへの接続には cockroachdb プロバイダが必須に

Prisma ORMバージョン5.0.0では、CockroachDBデータベースへの接続時にcockroachdbプロバイダを使用することが必須となりました。以前はpostgresqlも受け入れていましたが、このオプションは削除されます。

ネイティブデータベース型とpostgresqlプロバイダも使用していた場合、データベースをPostgreSQLからCockroachDBへベースライン化する必要があります。

1. 既存のschema.prismaファイルをバックアップします（例: バージョン管理を使用）。
2. datasourceプロバイダをpostgresqlからcockroachdbに更新します。
3. 既存のPrismaスキーマ（ネイティブ型を含む）をCockroachDBインスタンス上のものに上書きするために、npx prisma db pull --forceを使用します。
4. Prismaスキーマのバックアップとdb pullによって生成された新しいPrismaスキーマとの間の変更を確認します。新しいスキーマをそのまま使用することも、好みのスペースやコメントなどを含めるように更新することもできます。
5. 既存のマイグレーションを削除します。ローカルの設定を既存のCockroachDBインスタンスと一致させるために、ベースラインを実行します。
6. ベースライン化の手順を実行します。これらの手順の後、postgresqlプロバイダからcockroachdbプロバイダへの移行が成功します！

生成されたクライアントからのruntime/index.jsの削除

runtime/index.jsファイルはPrisma Clientから削除されました。

@prisma/client/runtimeからの公開APIの使用

Prisma ORM 5では、@prisma/client/runtimeからのインポートは利用できなくなりました。以前この名前空間で利用可能だった公開APIを使用していた場合、代わりにPrismaをインポートしてアクセスできます。例えば、

import { Decimal, NotFoundError } from '@prisma/client/runtime'
const num = new Decimal(24.454545)
const notFound = new NotFoundError()

は以下のように変更する必要があります。

import { Prisma } from '@prisma/client'
const num = new Prisma.Decimal(24.454545)
const notFound = new Prisma.NotFoundError()

特定のランタイム用のプライベートAPIの使用

内部のプライベートAPIは、予告なく変更される可能性があり、サポートが保証されないため、その使用を強く推奨しません。以前利用可能だったプライベートAPIが必要な場合は、GitHubでお問い合わせください。

生成された型の変更

null許容性に対応するためのRelationFilterInputの変更

Prisma ORM 5より前では、null許容のリバースリレーションが生成された型でnull許容としてマークされないという長年のバグがありました。例えば、以下のスキーマを考えてみましょう。

model User {
  id Int @id

  addressId Int     @unique
  address   Address @relation(fields: [addressId], references: [id])

  post Post[]
}

model Address {
  id Int @id

  user User?
}

model Post {
  id Int @id

  userId Int
  user   User @relation(fields: [userId], references: [id])
}

生成された型では、Address.userとPost.userは同じ型UserRelationFilterを使用していました。これはAddress.userがnull許容であるのに対し、Post.userはそうではないため、明らかに意図しない挙動でした。Prisma ORM 5では、Address.userの型はUserNullableRelationFilterとなり、この問題が解決されます。

コード内で生成された型をインポートしている場合、このようなインスタンスを新しいNullable型を利用するように更新する必要があります。

名前衝突を避けるためのUncheckedUpdateManyInputの変更

特定のケースでは、あるモデルが他の2つのモデルへの2つの外部キーを持ち、それらのモデルがリバースリレーションに対して同じプロパティ名を持っていた場合に、名前の衝突が発生する可能性がありました。例えば、以下のスキーマでは、

model Invoice {
  InvoiceId Int @id @default(autoincrement())

  invoice_items InvoiceItem[]
}

model InvoiceItem {
  InvoiceLineId Int @id @default(autoincrement())

  InvoiceItemInvoiceId Int     @map("InvoiceId")
  invoices             Invoice @relation(fields: [InvoiceItemInvoiceId], references: [InvoiceId])

  TrackId Int
  tracks  Track @relation(fields: [TrackId], references: [TrackId])
}

model Track {
  TrackId Int    @id @default(autoincrement())
  Name    String

  invoice_items InvoiceItem[]
}

InvoiceItem上の2つのリレーション間で名前の衝突が発生していました。リバースリレーション、つまりInvoice.invoice_itemsとTrack.invoice_itemsは、両方ともInvoiceItemUncheckedUpdateManyWithoutInvoice_itemsInputという型を取得していました。Prisma ORM 5では、これが解決され、Prisma ClientはそれぞれInvoiceItemUncheckedUpdateManyWithoutInvoicesInputとInvoiceItemUncheckedUpdateManyWithoutTracksInputを生成します。

コード内で生成された型をインポートしている場合、このようなインスタンスを修正された型に更新する必要があります。

その他の変更

以下の変更は、Prisma ORM 5へのアップグレード後にアプリケーションが初期的にエラーメッセージをスローする原因となる場合があります。幸いなことに、基盤となる機能がしばらくの間削除されていたり、変更が単純な文字列の置換であるため、これらは簡単に解決できます。

非推奨のPrisma CLIフラグの削除

いくつかの非推奨のCLIフラグが削除されました。以下のすべてのフラグは以前のAPIからのものであり、もはや不要です。

• db execute、db seed、db diffで使用されていた--preview-feature
• migrateで使用されていた--experimentalおよび--early-access-feature
• db pushで使用されていた--force/-f
• db pullで使用されていた--experimental-reintrospectionおよび--clean

古いdb push --forceの使用は、新しい実装であるdb push --accept-data-lossに置き換えることができます。

その他のすべてのフラグは以前のAPIからのものであり、もはや不要です。

ライブラリエンジンからのbeforeExitフックの削除

beforeExitフックはPrisma ORMライブラリエンジンから削除されました。この機能はPrisma ORMバイナリエンジンでは最終的なクエリの実行やシャットダウン関連の操作のために引き続き必要ですが、ライブラリエンジンではネイティブNode.jsの終了フックに比べて利点はありません。このフックの代わりに、組み込みのNode.js終了イベントの使用を推奨します。

Prisma ORM 4での以下のコード

const exitHandler = () => {
  // your exit handler code
}

prisma.$on('beforeExit', exitHandler)

は次のようになります。

const exitHandler = () => {
  // your exit handler code
}

process.on('exit', exitHandler)
process.on('beforeExit', exitHandler)
process.on('SIGINT', exitHandler)
process.on('SIGTERM', exitHandler)
process.on('SIGUSR2', exitHandler)

NestJSでbeforeExitフックを使用している場合、サービス内のカスタムenableShutdownHooksメソッドを削除することでPrisma ORM 5にアップグレードできます。

「prisma.service.ts」

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    await this.$connect()
  }

-  async enableShutdownHooks(app: INestApplication) {
-    this.$on('beforeExit', async () => {
-      await app.close()
-    })
-  }
}

代わりに、ライフサイクルイベントを処理する必要がある場合は、NestJSの組み込みenableShutdownHooksメソッドを使用してください。

「main.ts」

- prismaService.enableShutdownHooks(app)
+ app.enableShutdownHooks()

非推奨のprisma2実行ファイルの削除

Prisma ORM 2をリリースした際、Prisma 1と区別するためにprisma2実行ファイルが使用されました。後のリリースで、prisma2 CLIはprisma実行ファイル名を引き継ぎました。

言うまでもなく、prisma2実行ファイルはしばらくの間非推奨となっており、現在は削除されています。スクリプトでPrisma CLIをprisma2として使用している場合は、単純にprismaに置き換えてください。

非推奨のexperimentalFeaturesプロパティの削除

ジェネレーターブロックのpreviewFeaturesフィールドは、以前はexperimentalFeaturesと呼ばれていました。この非推奨のプロパティを削除します。

Prisma ORM 5では、experimentalFeaturesの参照をpreviewFeaturesに手動で更新するか、Prisma VSCode拡張機能の新しいコードアクションを使用する必要があります。

migration-engineがschema-engineに名称変更

prisma migrateやprisma dbなどのコマンドを担当するエンジンは、その用途をより適切に説明するためにmigration-engineからschema-engineに名称変更されました。多くのユーザーにとって変更は不要ですが、このエンジンファイルを明示的に含めるまたは除外する必要がある場合、あるいはその他の理由でエンジン名を参照する必要がある場合は、コード内の参照を更新する必要があります。

Serverless Frameworkでの例

一例として、Serverless Frameworkを使用しているプロジェクトが挙げられます。これらのケースでは、migration-engineを参照しているすべてのパターンをschema-engineを参照するように更新する必要があります。

package:
  patterns:
    - '!node_modules/.prisma/client/libquery_engine-*'
    - 'node_modules/.prisma/client/libquery_engine-rhel-*'
    - '!node_modules/prisma/libquery_engine-*'
    -- '!node_modules/prisma/migration-engine-*'
    -- '!node_modules/prisma/schema-engine-*'

Serverless Frameworkパターンの提案

ドキュメントで推奨されているルールは、不要なエンジンファイルをすべて除外するため、この変更の影響を受けません。

package:
  patterns:
    - '!node_modules/.prisma/client/libquery_engine-*'
    - 'node_modules/.prisma/client/libquery_engine-rhel-*'
    - '!node_modules/prisma/libquery_engine-*'
    -- '!node_modules/@prisma/engines/**'

Prisma ORM 5をお楽しみください！