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

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

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

以下に、破壊的変更の一覧とそれらへの対処方法を示します。

破壊的変更​

参照アクション​

バージョン 3.x での参照アクションの導入により、以前はランタイム時にカスケード削除を防いでいた Prisma Client の安全策がなくなりました。

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

手順については、「参照アクションのアップグレードパス」を参照してください。

名前付き制約​

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

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

手順の詳細については、「名前付き制約のアップグレードパス」を確認してください。

$queryRaw​

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

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

新しい `$queryRaw` および `$queryRawUnsafe` メソッドの詳細については、ドキュメントの「Raw database access」セクションを参照してください。

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` にも適用されます。`null` 値を `Json` フィールドに挿入するには、次のように記述します

import { Prisma } from '@prisma/client'

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

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

import { Prisma } from '@prisma/client'

prisma.log.create({
  data: {
    meta: Prisma.DbNull,
  },
})
警告

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

また、JSON 配列内には JSON null のみが存在する可能性があるため、`array_contains` 演算子にも適用されません。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