メインコンテンツへスキップ

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

Prisma ORM 3は、以前のバージョン (2.xバージョン) からアップグレードする場合、多くの破壊的変更を導入しています。そのため、このアップグレードがアプリケーションにどのように影響するかを理解し、スムーズな移行を確実にするために必要な調整を行うことが重要です。

以下に、破壊的変更のリストと、それらの対処法を示します。

破壊的変更​

参照アクション​

バージョン3.xで参照アクションが導入されたことにより、これまでPrisma Clientでランタイムでのカスケード削除を防いでいたセーフティネットが削除されました。

結果として、アプリケーションで作業しているワークフローによっては影響を受ける可能性があります。スキーマを確認し、参照アクションを明示的に定義する必要があるかどうかを判断することをお勧めします。

進め方を理解するには、参照アクションのアップグレードパスをご覧ください。

名前付き制約​

Prisma ORMが制約とインデックスに名前を付けるために従う規則を変更しました。また、Prismaスキーマで制約を明示的に制御する方法として、PSLにmap属性（データベースレベル名）とname属性（Prisma Client API名）の明確な区別を導入しました。

これは、Prisma migrateまたはdb pullを実行する際に、この新しい規則に従うため、影響があることに気づくでしょう。スキーマを調整して、制約とインデックスの名前を適切に反映させることをお勧めします。

詳しい進め方については、名前付き制約のアップグレードパスをご覧ください。

$queryRaw​

バージョン3.x以降、$queryRawメソッドはテンプレートリテラルのみをサポートするようになりました。

これは、アプリケーションが文字列を使用する$queryRaw呼び出しに依存していた場合、それらの呼び出しは**もはや機能しません**。セキュリティ上の理由から、可能な限りテンプレートリテラルを使用するか、またはSQLインジェクションを防ぐためにクエリを慎重にエスケープした上で、$queryRawUnsafeに頼ることをお勧めします。

新しい$queryRawおよび$queryRawUnsafeメソッドについては、ドキュメントのRawデータベースアクセスセクションで詳しく学ぶことができます。

Json Null Equality​

Jsonフィールドをnull値でフィルタリングすることはできません。このGitHub Issueを参照してください。これは、{ equals: null }がデータベースのカラム値がNULLであるかどうかをチェックし、カラム内のJSON値がnullであるかどうかをチェックしないためです。

この問題を解決するため、JsonフィールドのnullをJsonNull、DbNull、AnyNullに分割することにしました。

  • JsonNull: JSON内のnull値を選択します。
  • DbNull: データベース内のNULL値を選択します。
  • AnyNull: JSON null値とデータベースNULL値の両方を選択します。

Prisma Schemaに以下のモデルがあるとします。

model Log {
  id Int @id
  meta Json
}

3.0.1以降、JsonフィールドでnullをフィルタリングしようとするとTypeErrorが表示されます。

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: null
                ^ TypeError: Type 'null' is not assignable to type
        }
    },
  },
});

これを修正するには、新しいnull型の一つをインポートして使用します。

import { Prisma } from '@prisma/client'

prisma.log.findMany({
  where: {
    data: {
      meta: {
        equals: Prisma.AnyNull,
      },
    },
  },
})

これは、create、update、およびupsertにも適用されます。Jsonフィールドにnull値を挿入するには、次のように記述します。

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.JsonNull,
  },
})

そして、JsonフィールドにデータベースNULLを挿入するには、次のように記述します。

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.DbNull,
  },
})
注意

このAPIの変更は、JSON nullとデータベースNULLの間に違いがないMongoDBコネクタには適用されません。

また、array_contains演算子にも適用されません。これは、JSON配列内にはJSON nullしか存在しないためです。JSON配列内にデータベースNULLは存在できないため、{ array_contains: null }は曖昧ではありません。

特定のアップグレードパス​

prismaおよび@prisma/clientパッケージをPrisma ORM 3にアップグレードする​

バージョン2.xから3.xにアップグレードするには、prismaと@prisma/clientの両方のパッケージを更新する必要があります。prismaと@prisma/clientの両方のパッケージは、破壊的変更から保護するためにバージョン番号にキャレット^を付けてインストールされます。

キャレット^を無視してメジャーバージョンをまたいでアップグレードするには、npmまたはyarnでアップグレードするときに@3タグを使用できます。

危険

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

npm install prisma@3 @prisma/client@3
© . All rights reserved.