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

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

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

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

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

npm
yarn
pnpm

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

yarn up prisma@5 @prisma/client@5

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 日にサポート終了 (end-of-life) を迎えます。そのため、現在の 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 にアップグレードしました。破壊的な変更は見られず、ユーザープロジェクトで変更が必要になるとは予想していませんが、SQLite を使用している場合、特に Prisma ORM の機能を超える可能性のある生のクエリを使用している場合は、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 の変更ガイドを確認してください。以下の対応が必要です。

アレイショートカットの削除

Prisma ORM 5 では、多数の「アレイショートカット」のサポートが終了しました。これらのショートカットは、アレイベースの演算子に単一の要素を値として追加する際に、その要素をアレイでラップする代わりに利用されていました。タイピングをより一貫性があり論理的にし、新しい JSON Protocol に準拠するために、これらの演算子にはアレイ値を必須とするようになりました。

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

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

CockroachDB データベースに接続する際に `cockroachdb` プロバイダーが必須になりました

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

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

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

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

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

`@prisma/client/runtime` からパブリック API を使用する

@prisma/client/runtime からのインポートは、Prisma ORM 5 では使用できなくなりました。以前にこの名前空間で使用可能だったパブリック 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 より前は、nullable なリバースリレーションが生成された型で nullable としてマークされないという長年のバグがありました。たとえば、次のスキーマを考えてみましょう。

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 は nullable ですが、Post.user は nullable ではないため、これは明らかに意図されていません。Prisma ORM 5 では、Address.user の型は UserNullableRelationFilter になり、この問題が解決されます。

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

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

特定のインスタンスでは、1 つのモデルが、リバースリレーションのプロパティ名が同じである他の 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 exit フックよりも利点はありません。このフックの代わりに、組み込みの Node.js exit イベントを使用することをお勧めします。

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` プロパティを削除

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

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

`migration-engine` を `schema-engine` にリネーム

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

Serverless Framework の例

確認されている例の 1 つは、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 をお楽しみください。

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

バージョンの変更​

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

TypeScript の最小バージョン変更​

PostgreSQL の最小バージョン変更​

Prisma Client に埋め込まれた SQLite のバージョンを更新​

主な変更点​

rejectOnNotFound パラメーターの削除​

jsonProtocol がプレビューから外れる​

アレイショートカットの削除​

CockroachDB データベースに接続する際に cockroachdb プロバイダーが必須になりました​

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

@prisma/client/runtime からパブリック API を使用する​

特定のランタイムのプライベート API を使用する​

生成された型の変更​

null 可能性を考慮した RelationFilterInput の変更​

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

その他の変更点​

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

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

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

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

migration-engine を schema-engine にリネーム​

Serverless Framework の例​