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

Prisma ORM の型システムの使い方

このガイドでは、Prisma ORM の型システムを紹介し、データベース内の既存のネイティブ型をイントロスペクトする方法、および Prisma Migrate または db push でスキーマ変更をデータベースに適用する際に型を使用する方法について説明します。

Prisma ORM の型システムはどのように機能しますか？​

Prisma ORM は、フィールドが保持できるデータの種類を定義するために型を使用します。Prisma ORM は、簡単に始められるように、ほとんどのデフォルトのユースケースをカバーする少数のコアスカラー型を提供しています。たとえば、次のブログ投稿モデルを見てください。

schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Post {
  id        Int      @id
  title     String
  createdAt DateTime
}

Post モデルの title フィールドは String スカラー型を使用し、createdAt フィールドは DateTime スカラー型を使用します。

データベースにも独自の型システムがあり、列が保持できる値の型を定義します。ほとんどのデータベースは、列が格納できるものを正確にきめ細かく制御できるように、多数のデータ型を提供しています。たとえば、データベースは、複数のサイズの整数や XML データに対する組み込みサポートを提供している場合があります。これらの型の名前はデータベースによって異なります。たとえば、PostgreSQL では、boolean の列型は boolean ですが、MySQL では通常 tinyint(1) 型が使用されます。

上記のブログ投稿の例では、PostgreSQL コネクタを使用しています。これは、Prisma スキーマの datasource ブロックで指定されています。

デフォルトの型マッピング​

コアスカラー型を使い始められるように、Prisma ORM は、各スカラー型を基盤となるデータベースのデフォルト型にマッピングするデフォルトの型マッピングを提供しています。例:

  • デフォルトでは、Prisma ORM の String 型は、PostgreSQL の text 型および MySQL の varchar 型にマッピングされます。
  • デフォルトでは、Prisma ORM の DateTime 型は、PostgreSQL の timestamp(3) 型および SQL Server の datetime2 型にマッピングされます。

特定のデータベースのデフォルトの型マッピングについては、Prisma ORM のデータベースコネクタページを参照してください。たとえば、こちらの表は、PostgreSQL のデフォルトの型マッピングを示しています。
特定の Prisma ORM 型のすべてのデータベースのデフォルトの型マッピングを確認するには、Prisma スキーマリファレンスのモデルフィールドのスカラー型セクションを参照してください。たとえば、こちらの表は、Float スカラー型のデフォルトの型マッピングを示しています。

ネイティブ型マッピング​

Prisma ORM 型のデフォルトの型マッピングの 1 つではない、より具体的なデータベース型を使用する必要がある場合があります。この目的のために、Prisma ORM は、コアスカラー型を改良するためのネイティブ型属性を提供しています。たとえば、上記の Post モデルの createdAt フィールドでは、デフォルトの型マッピングである timestamp(3) の代わりに date 型を使用して、基盤となる PostgreSQL データベースで日付のみの列を使用したい場合があります。これを行うには、@db.Date ネイティブ型属性を createdAt フィールドに追加します。

schema.prisma
model Post {
  id        Int      @id
  title     String
  createdAt DateTime @db.Date
}

ネイティブ型マッピングを使用すると、データベース内のすべての型を表現できます。ただし、Prisma ORM のデフォルトでニーズが満たされる場合は、それらを使用する必要はありません。これにより、一般的なユースケースに対して、より短く、より読みやすい Prisma スキーマになります。

データベース型をイントロスペクトする方法​

イントロスペクト既存のデータベースの場合、Prisma ORM は各テーブル列のデータベース型を取得し、対応するモデルフィールドの正しい Prisma ORM 型を使用して Prisma スキーマで表現します。データベース型がその Prisma ORM スカラー型のデフォルトのデータベース型でない場合、Prisma ORM はネイティブ型属性も追加します。

例として、PostgreSQL データベースの User テーブルを考えてみましょう。

  • データ型が serial の id 列
  • データ型が text の name 列
  • データ型が boolean の isActive 列

これは、次の SQL コマンドで作成できます。

CREATE TABLE "public"."User" (
  id serial PRIMARY KEY NOT NULL,
  name text NOT NULL,
  "isActive" boolean NOT NULL
);

プロジェクトのルートディレクトリから実行する次のコマンドを使用して、データベースをイントロスペクトします。

npx prisma db pull

次の Prisma スキーマが得られます。

schema.prisma
model User {
  id       Int     @id @default(autoincrement())
  name     String
  isActive Boolean
}

データベースの id、name、および isActive 列は、それぞれ Int、String、および Boolean Prisma ORM 型にマッピングされます。データベース型は、これらの Prisma ORM 型のデフォルトのデータベース型であるため、Prisma ORM はネイティブ型属性を追加しません。

次に、次の SQL コマンドを実行して、データ型が date の createdAt 列をデータベースに追加します。

ALTER TABLE "public"."User"
ADD COLUMN "createdAt" date NOT NULL;

データベースを再度イントロスペクトします。

npx prisma db pull

Prisma スキーマには、DateTime の Prisma ORM 型を持つ新しい createdAt フィールドが含まれるようになりました。createdAt フィールドには @db.Date ネイティブ型属性もあります。これは、PostgreSQL の date が DateTime 型のデフォルト型ではないためです。

schema.prisma
model User {
  id        Int      @id @default(autoincrement())
  name      String
  isActive  Boolean
  createdAt DateTime @db.Date
}

スキーマ変更をデータベースに適用する際に型を使用する方法​

Prisma Migrate または db push を使用してスキーマ変更をデータベースに適用すると、Prisma ORM は、各フィールドの Prisma ORM スカラー型と、対応するデータベース列の正しいデータベース型を決定するために持つネイティブ属性の両方を使用します。

例として、次の Post モデルを含む Prisma スキーマを作成します。

schema.prisma
model Post {
  id        Int      @id
  title     String
  createdAt DateTime
  updatedAt DateTime @db.Date
}

この Post モデルには、次のものがあります。

  • Prisma ORM 型が Int の id フィールド
  • Prisma ORM 型が String の title フィールド
  • Prisma ORM 型が DateTime の createdAt フィールド
  • Prisma ORM 型が DateTime で、@db.Date ネイティブ型属性を持つ updatedAt フィールド

次に、プロジェクトのルートディレクトリから実行する次のコマンドを使用して、これらの変更を空の PostgreSQL データベースに適用します。

npx prisma db push

データベースに、新しく作成された Post テーブルがあることがわかります。

  • データベース型が integer の id 列
  • データベース型が text の title 列
  • データベース型が timestamp(3) の createdAt 列
  • データベース型が date の updatedAt 列

@db.Date ネイティブ型属性は、updatedAt 列のデータベース型をデフォルトの timestamp(3) ではなく date に変更することに注意してください。

Prisma ORM の型システムの使用に関する詳細​

Prisma ORM の型システムの使用に関する詳細なリファレンス情報については、次のリソースを参照してください。

  • 各データベースプロバイダーのデータベースコネクタページには、Prisma ORM 型とデータベース型間のデフォルトの型マッピングの表と、Prisma ORM の対応するネイティブ型属性を持つデータベース型の表を含む型マッピングセクションがあります。たとえば、PostgreSQL の型マッピングセクションはこちらです。
  • Prisma スキーマリファレンスのモデルフィールドのスカラー型セクションには、各 Prisma ORM スカラー型のサブセクションがあります。これには、各データベースのその Prisma ORM 型のデフォルトマッピングの表と、各データベースの対応するデータベース型とその Prisma ORM のネイティブ型属性をリストした表が含まれています。たとえば、String Prisma ORM 型のエントリはこちらです。