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

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

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 スキーマに、新しい createdAt フィールドが DateTime の Prisma ORM 型で含まれるようになりました。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 型のエントリはこちらです。
© . All rights reserved.