新しいデータモデル構文：スキーマ制御の強化と移行の簡素化

⚠️ この記事は古くなっています。現在は非推奨となった Prisma 1 に関するものです。最新バージョンの Prisma について詳しく知るには、ドキュメントをお読みください。⚠️

ここ数ヶ月、私たちはコミュニティと協力して、Prisma の改良されたデータモデル仕様を定義してきました。この新しいバージョンは datamodel v1.1 と呼ばれ、本日の安定版リリースで利用可能です。ドキュメントはこちらをご覧ください。

本日より、Prisma の公開デモサーバーは、新しいデータモデル構文を使用するようになります。既存のプロジェクトをアップグレードする方法については、ドキュメントまたはこのチュートリアルビデオをご覧ください。

---

データモデリングへのより柔軟なアプローチ

データモデルは、すべての Prisma プロジェクトの基盤です。これは、基盤となるデータベースのスキーマの基盤として機能します。

現在のデータモデルは、リレーション、テーブル/カラムの名前付け、システムフィールドなど、データベースレイアウトについて独断的です。新しいデータモデル構文は、多くの制限を取り払い、開発者がスキーマをより細かく制御できるようにします。

データベースレイアウトのより詳細な制御

新しいデータモデル構文によって可能になったことのいくつかをご紹介します。

• リレーションがリレーションテーブルを使用するか、外部キーを使用するかを指定する
• モデル/フィールド名は、基盤となるテーブル/カラムの名前と異なってもよい
• 任意のフィールドを id フィールドとして使用し、「独自の ID を持ち込む」
• 任意のフィールドを createdAt または updatedAt フィールドとして使用する

よりシンプルな移行と改善されたイントロスペクション

以前の Prisma バージョンでは、開発者は PRISMA_CONFIG の migrations フラグを設定することにより、Prisma にデータベース移行を実行させるかどうかを決定する必要がありました。

migrations フラグは最新の Prisma バージョンで削除されました。つまり、開発者はいつでも手動でデータベースを移行するか、Prisma を移行に使用するかのいずれかを選択できるようになりました。

また、既存のデータベースのイントロスペクションにも多大な投資を行い、レガシーデータベースで Prisma を使用している開発者や、ある時点で手動移行を実行する必要がある開発者向けに、スムーズなワークフローを実現しました。

---

改善されたデータモデル構文の新機能

モデル名とフィールド名を基盤となるテーブルとカラムにマッピングする

古いデータモデル構文では、テーブルとカラムは常にデータモデルのモデルとフィールドの名前と完全に一致していました。新しい @db ディレクティブを使用すると、基盤となるデータベースでテーブルとカラムをどのように呼び出すかを制御できます。

この場合、基盤となるテーブルは user と呼ばれ、カラムは full_name と呼ばれます。

データベーススキーマでのリレーションの表現方法を決定する

古いデータモデルは、データベーススキーマのリレーションについて独断的です。それらは常にリレーションテーブルとして表現されます。

一方、これにより、既存のリレーションを余分な作業なしで多対多リレーションに簡単に移行できます。ただし、リレーションテーブルはクエリにコストがかかることが多いため、この柔軟性にはパフォーマンスのペナルティが伴う可能性があります。

1:1 および 1:n リレーションは外部キーを介して表現できるようになりましたが、m:n リレーションは引き続きリレーションテーブルとして表現されます。

新しいデータモデルを使用すると、開発者は基盤となるデータベースでのリレーションの表現を完全に制御できます。次の 2 つのオプションがあります。

• インライン参照（つまり外部キー）を介してリレーションを表現する
• リレーションテーブルを介してリレーションを表現する

インラインリレーションとリレーションテーブルを使用するリレーションの 2 つの例を次に示します。

インラインリレーションの場合、@relation(link: INLINE) ディレクティブの配置によって、外部キーが格納されるリレーションの端が決定されます。この例では、User テーブルに格納されています。

任意のフィールドを id、createdAt、または updatedAt として使用する

古いデータモデルでは、開発者は一意の ID を自動的に生成したり、レコードがいつ作成/最終更新されたかを追跡したりする場合、予約済みフィールドを使用する必要がありました。

新しい @id、@createdAt、および @updatedAt ディレクティブを使用すると、この機能をモデルの任意のフィールドに追加できるようになりました。

より柔軟な ID

現在のデータモデルは、データベースレコードのグローバルに一意な ID を生成および保存するために、常に CUID を使用します。datamodel v1.1 では、カスタム ID を維持したり、他の ID タイプ（整数、シーケンス、UUID など）を使用したりすることも可能になりました。

---

新しいデータモデル構文を使い始める

新しいデータモデルを探索するための 2 つの短いチュートリアルをご用意しました。

• オプション A：古い Prisma プロジェクトを新しいデータモデル構文にアップグレードする
• オプション B：新しいデータモデル構文でゼロから始める

既存のデータベースで始めるためのより広範なチュートリアルと手順については、ドキュメントをご覧ください。

前提条件：最新の Prisma CLI をインストールする

最新バージョンの Prisma CLI をインストールするには、次を実行します。

Docker で Prisma を実行する場合は、Docker イメージを 1.31 にアップグレードする必要があります。

オプション A：古い Prisma バージョンからアップグレードする

既存の Prisma プロジェクトをアップグレードする場合は、prisma introspect を実行するだけで、新しい構文でデータモデルを生成できます。正確なプロセスは、以下のセクションとこのビデオの例で説明されています。

1. 古いデータモデルのセットアップ

（古い）データモデルを使用する実行中の Prisma プロジェクトが既にあると仮定します。

2. Prisma サーバーをアップグレードする

Prisma サーバーのデプロイに使用する Docker Compose ファイルで、prismagraphql/prisma イメージに最新の 1.31 Prisma バージョンを使用していることを確認してください。例：

実行中の Prisma サーバーをアップグレードする

3. イントロスペクションを介して新しいデータモデルを生成する

ここで prisma deploy を実行すると、古い構文のデータモデルを更新された Prisma サーバーにデプロイしようとしているため、Prisma CLI はエラーをスローします。

これらのエラーを修正する最も簡単な方法は、イントロスペクションを介して新しい構文で記述されたデータモデルを生成することです。prisma.yml が配置されているディレクトリ内で次のコマンドを実行します。

これにより、データベースがイントロスペクトされ、新しい構文で記述された別のデータモデルが datamodel-TIMESTAMP.prisma（例：datamodel-1554394432089.prisma）という名前で生成されます。上記の例では、次のデータモデルが生成されます。

4. 新しいデータモデルをデプロイする

最後のステップは、古い datamodel.prisma ファイルを削除し、生成されたデータモデルの名前を datamodel.prisma に変更することです（prisma.yml の datamodel プロパティが、新しい構文を使用している生成されたファイルを指すようにします）。

それが完了したら、次を実行できます。

5. データベーススキーマを最適化する

イントロスペクションではデータベースレイアウトについて何も変更しなかったため、すべてのリレーションは引き続きリレーションテーブルとして表現されます。古い 1:1 および 1:n リレーションを移行して外部キーを使用する方法については、ドキュメントをご覧ください。

オプション B：ゼロから始める

既存の Prisma プロジェクトをアップグレードする方法を学んだ後、ゼロから始める簡単なセットアップについて説明します。

1. 新しい Prisma プロジェクトを作成する

まず、新しい Prisma プロジェクトをセットアップしましょう。

インタラクティブウィザードで、次を選択します。

1. 新しいデータベースを作成するを選択
2. PostgreSQL（または MySQL、お好みの場合は）を選択
3. お好みの言語でクライアントを選択します（クライアントを使用しないためオプション）

Prisma サーバーとデータベースを Docker 経由で起動する前に、データベースのポートマッピングを有効にします。これにより、後でローカル DB クライアント（Postico や TablePlus など）を使用してデータベースに接続できるようになります。

生成された docker-compose.yml で、データベースの Docker イメージ構成で次の行のコメントを解除します。

2. データモデルを定義する

新しい Prisma 機能を利用するデータモデルを定義しましょう。datamodel.prisma を開き、内容を次のように置き換えます。

このデータモデル定義に関する重要な点を次に示します。

• 各モデルは、モデルにちなんで名付けられたテーブルにマッピングされますが、@db ディレクティブを使用して小文字にされます。
• 次のリレーションがあります。
  • 1:1 User と Profile の間
  • 1:n User と Post の間
  • n:m Post と Category の間
• User と Profile の間の1:1 リレーションは、User モデルの @relation(link: INLINE) でアノテーションが付けられています。これは、リレーションが存在する場合（profile フィールドは必須ではないため、リレーションは NULL になる可能性があります）、データベース内の user レコードが profile レコードへの参照を持つことを意味します。INLINE の代替は TABLE です。この場合、Prisma は専用のリレーションテーブルを介してリレーションを追跡します。
• User と Post の間の1:n リレーションは、post テーブルの author カラムを介してインラインで追跡されます。つまり、Post モデルの author フィールドで @relation(link: INLINE) ディレクティブが推論されます。
• Post と Category の間のn:m リレーションは、PostToCategory という名前の専用リレーションテーブルを介して追跡されます。このリレーションテーブルはデータモデルの一部であり、@relationTable ディレクティブでアノテーションが付けられています。
• 各モデルには、@id ディレクティブでアノテーションが付けられた id フィールドがあります。
• User モデルの場合、データベースは @createdAt ディレクティブでアノテーションが付けられたフィールドを介して、レコードがいつ作成されたかを自動的に追跡します。
• Post モデルの場合、データベースは @createdAt および @updatedAt ディレクティブでアノテーションが付けられたフィールドを介して、レコードがいつ作成および更新されたかを自動的に追跡します。

3. データモデルをデプロイする

次のステップでは、Prisma はこのデータモデルを基盤となるデータベースにマッピングします。

4. Prisma Admin でデータを表示および編集する

ここから、データベース内のデータにプログラムでアクセスする場合は、Prisma クライアントを使用できます。以下では、Prisma Admin を使用してデータを操作する方法について説明します。

ドキュメントにアクセスして、TablePlus を使用してデータベースに接続し、基盤となるデータベーススキーマを探索する方法を学びましょう。

Prisma Admin でデータにアクセスするには、Prisma プロジェクトの Admin エンドポイント https://#:4466/_admin に移動する必要があります。

---

フィードバックとアイデアを共有する

新しいデータモデル構文には、コミュニティから要望のあった多くの機能が既に組み込まれていますが、さらに改善する機会があると考えています。たとえば、データモデルはまだ複数カラムインデックスやポリモーフィックリレーションを提供していません。

現在、新しいデータモデリング言語に取り組んでおり、これは現在使用されているSDLのバリエーションになります。

新しいデータモデルについてのご意見をお聞かせください。フィードバックリポジトリで issue をオープンするか、Spectrum で会話に参加して、フィードバックをお寄せください。