アップグレード方法
概要
このページでは、Prisma 1 から Prisma ORM バージョン 2.x 以降へのアップグレードをいつ、どのように行うかについて、情報に基づいた意思決定を行うのに役立ちます。
アップグレードドキュメント
アップグレードドキュメントは複数のページで構成されています。以下にそれらの使用方法の概要を示します。
- アップグレード方法（現在地）：アップグレードプロセス全般について学ぶための出発点。
- スキーマの非互換性：Prisma 1 と Prisma ORM 2.x（およびそれ以降のバージョン）間のスキーマの非互換性に関するリファレンスページ。このページを読むことは必須ではありませんが、アップグレードプロセスの特定の手順をより深く理解するのに役立ちます。
これらの 2 つのページに加えて、アップグレードプロセスの例のシナリオを段階的に説明するさまざまな実践ガイドがあります。
- Prisma レイヤーのアップグレード：Prisma 1 のセットアップがどのようなものであっても、常にこのガイドに従ってアップグレードプロセスを開始する必要があります。
このガイドが完了したら、アプリケーションレイヤーをアップグレードするために次の 4 つのガイドのいずれかを選択できます。
- 旧 Nexus から新 Nexus へ：GraphQL Nexus で Prisma 1 を現在実行している場合は、このガイドを選択してください。
- prisma-binding から Nexus へ：
prisma-bindingを使用して Prisma 1 を現在実行しており、Nexusにアップグレードしたい場合は、このガイドを選択してください。 - prisma-binding から SDL-first へ：
prisma-bindingを使用して Prisma 1 を現在実行しており、SDL-first GraphQL サーバーにアップグレードしたい場合は、このガイドを選択してください。 - REST API：Prisma Client 1 を使用して Prisma 1 を現在実行しており、REST API を構築している場合は、このガイドを選択してください。
Prisma 1 と Prisma ORM バージョン 2.x 以降の主な違い
大まかに言って、Prisma 1 と Prisma ORM バージョン 2.x 以降の最大の相違点を以下にまとめます。
Prisma ORM 2.x 以降のバージョン
- データベースプロキシサーバー（つまり、Prisma サーバー）をホストする必要はありません。
- Prisma 1 の機能をよりモジュール化し、専用のツールに分割します。
- Prisma Client：Prisma Client 1.0 の改良版
- Prisma Migrate：データモデリングと移行（以前の
prisma deploy）。
- Prisma スキーマを使用します。これは、Prisma 1 データモデルと
prisma.ymlをマージしたものです。 - GraphQL SDL に基づくのではなく、独自のモデリング言語を使用します。
- 「データベース用の GraphQL API」を公開するのではなく、Prisma Client API を介したプログラムによるアクセスのみを許可します。
- Prisma ORM バインディングをサポートしなくなりました。
- より強力なイントロスペクションを通じて、Prisma ORM 2.x 以降のバージョンを既存のデータベースに接続できます。
機能パリティ
Prisma ORM 2.x 以降のバージョンは、Prisma 1 との完全な機能パリティをまだ備えていません。Prisma ORM バージョン 2.x 以降でまだ欠落している最大の機能は、リアルタイムサブスクリプションです。
- リアルタイム API (サブスクリプション)：Prisma ORM バージョン 2.x 以降は現在、データベースで発生しているイベントをサブスクライブする方法がなく、リアルタイムで通知を受け取ることができません。リアルタイム API が Prisma ORM バージョン 2.x 以降に追加されるかどうか、いつ、どのような形で追加されるかは現在不明です。当面の間、ネイティブデータベーストリガーを使用してリアルタイム機能を実装するか、GraphQL サブスクリプションを使用している場合は、ミューテーションリゾルバー内でサブスクリプションを手動でトリガーすることを検討できます。
スキーマの非互換性
Prisma 1 で prisma deploy を実行したときに作成されるデータベーススキーマは、Prisma ORM バージョン 2.x 以降で作成されるスキーマと部分的にのみ互換性があります。このセクションでは、一般的な非互換性と潜在的な回避策の概要を示します。-
注：問題とそれぞれの回避策の詳細な説明については、スキーマの非互換性ページを参照してください。
以下は、さまざまな列の概要です。
- 問題：Prisma 1 から Prisma ORM バージョン 2.x 以降にアップグレードする際の問題の簡単な説明
- SQL：SQL スキーマに非破壊的な変更を加えることで解決できますか？
- Prisma スキーマ：Prisma ORM バージョン 2.x 以降のスキーマに非破壊的な変更を加えることで解決できますか？
- Prisma 1 の破壊：SQL ステートメントは Prisma 1 のセットアップを破壊しますか？これは、段階的なサイドバイサイドアップグレード戦略を選択した場合にのみ関連します。
| 問題 | SQL | Prisma スキーマ | Prisma 1 の破壊 |
|---|---|---|---|
| デフォルト値がデータベースで表現されない | はい | はい | いいえ |
| ID 値として生成された CUID がデータベースで表現されない | いいえ | はい | いいえ |
@createdAt がデータベースで表現されない | はい | はい | いいえ |
@updatedAt がデータベースで表現されない | いいえ | はい | いいえ |
インライン 1-1 関係が 1-n として認識される（UNIQUE 制約の欠落） | はい | いいえ | いいえ |
| すべての非インライン関係が m-n として認識される | はい | いいえ | はい |
Json 型がデータベースで TEXT として表現される | はい | いいえ | いいえ (MySQL) はい (PostgreSQL) |
Enum がデータベースで TEXT として表現される | はい | いいえ | いいえ (MySQL) はい (PostgreSQL) |
| 必須の 1-1 関係がデータベースで表現されない | いいえ | はい | いいえ |
Prisma 1 の @db 属性が Prisma スキーマに転送されない | いいえ | はい | いいえ |
| CUID の長さの不一致 | はい | いいえ | いいえ |
| スカラーリスト（配列）が追加テーブルで維持される | 依存 | いいえ | 依存 |
注：Prisma スキーマにおける回避策の一般的な欠点は、データベースを再イントロスペクションすると、Prisma スキーマへの変更が失われるため、各イントロスペクションの実行後に手動で再追加する必要があることです。
Prisma 1 アップグレード CLI
Prisma 1 アップグレード CLIは、スキーマの非互換性ページで説明されている回避策を適用するのに役立ちます。データベーススキーマを修正し、Prisma ORM バージョン 2.x 以降と互換性を持たせるための SQL ステートメントを生成します。アップグレード CLI はステートメントを生成して出力するだけで、データベースに対して実行される操作を完全に制御できることに注意してください。アップグレード CLI は、Prisma スキーマの回避策も処理します。
大まかに言って、アップグレード CLI を使用したアップグレードワークフローは次のようになります。
初期設定の場合
- Prisma ORM バージョン 2.x 以降の CLI をインストールし、
npx prisma initを実行して Prisma ORM をセットアップします。 - データベースに接続し、
npx prisma db pullでイントロスペクションします。
スキーマの非互換性を修正する場合
npx prisma-upgradeでアップグレード CLI を呼び出します。- アップグレード CLI は、データベースで実行する SQL コマンドを生成します。
- データベースに対して SQL コマンドを実行します。
prisma db pullコマンドを再度実行します。npx prisma-upgradeコマンドを再度実行します。- アップグレード CLI は、不足している属性を追加して、Prisma スキーマ（バージョン 2.x 以降）を調整します。
アップグレード CLI は、いつでもプロセスを停止して再開できるように設計されていることに注意してください。アップグレード CLI によって生成された SQL コマンドをデータベースに対して実行すると、次回アップグレード CLI を呼び出したときに SQL コマンドは表示されなくなります。これにより、都合の良いときにすべてのスキーマの非互換性を段階的に解決できます。
アップグレード戦略
主なアップグレード戦略は 2 つあります。
- すべてを一度にアップグレード：プロジェクトから Prisma 1 を完全に削除し、すべてを Prisma ORM バージョン 2.x 以降に一度に移行します。
- 段階的なサイドバイサイドアップグレード：Prisma ORM バージョン 2.x 以降を既存の Prisma 1 プロジェクトに追加し、既存の Prisma 1 機能を新しい Prisma 機能に段階的に置き換えながら、サイドバイサイドで実行します。
Prisma 1 と Prisma ORM 2.x 以降のバージョンをサイドバイサイドで実行することを計画している場合は、Prisma 1 のセットアップを破壊するスキーマの互換性をまだ解決してはならないことに注意してください。
どちらの戦略を選択すべきか
プロジェクトがまだ本番環境で実行されていない場合、またはトラフィックとユーザーデータが少ない場合は、すべてを一度に戦略をお勧めします。
プロジェクトがすでに多くのトラフィックを抱え、データベースに多くのユーザーデータが保存されている場合は、Prisma 1 と Prisma ORM 2 以降を一定期間サイドバイサイドで実行し、以前のすべての Prisma 1 機能を Prisma ORM 2 以降のバージョンに置き換えるまで実行する段階的なアップグレード戦略を検討することをお勧めします。
段階的なアップグレード戦略を選択し、Prisma 1 と Prisma ORM バージョン 2.x 以降をサイドバイサイドで実行する予定の場合、「Prisma 1 の破壊」変更が必要なスキーマの非互換性を修正することはできません。これは、これらのデータ移行が Prisma 1 が期待するスキーマを破壊するためです。これは、Prisma Client API が本来ほど慣用的ではないと感じるかもしれませんが、それでも Prisma Client のフル機能セットを利用できることを意味します。
アップグレードパス
どちらの戦略を選択しても、大まかに言って、想定されるアップグレードパスは次のようになります。
- 新しい Prisma ORM バージョン 2.x 以降の CLI を開発依存関係としてインストールします。
- Prisma スキーマを作成し、データベース接続 URL を構成します。
- Prisma ORM バージョン 2.x 以降の CLI を使用して、Prisma 1 データベースをイントロスペクションし、Prisma スキーマを生成します。
- Prisma 1 アップグレード CLIを実行して、Prisma スキーマを「修正」します。
- Prisma Client バージョン 2.x 以降をインストールして生成します。
- アプリケーションコードを調整します。具体的には、Prisma Client 1.0 からの API 呼び出しを Prisma Client バージョン 2.x 以降のものに置き換えます。
次のステップ
アップグレードすることを決定したら、Prisma ORM レイヤーのアップグレードガイドに進んでください。