アップグレード方法
概要
このページは、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 1を
prisma-bindingで実行しており、Nexusにアップグレードしたい場合は、このガイドを選択してください。 - prisma-bindingからSDL-firstへ: 現在、Prisma 1を
prisma-bindingで実行しており、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 1のデータモデルと`prisma.yml`を統合したPrisma スキーマを使用します。
- 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対多として認識される（UNIQUE制約の欠如） | はい | いいえ | いいえ |
| すべての非インラインリレーションが多対多として認識される | はい | いいえ | はい |
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 1プロジェクトにPrisma ORMバージョン2.x以降を追加し、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レイヤーのアップグレード」ガイドに進んでください。