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

Prisma ORMとは？

Prisma ORMは、オープンソース次世代ORMです。以下の部分で構成されています。

  • Prisma Client: Node.jsとTypeScript用の自動生成および型安全なクエリビルダー

  • Prisma Migrate: マイグレーションシステム

  • Prisma Studio: データベース内のデータを表示および編集するためのGUI。

    情報

    Prisma Studioは、Prisma ORMの中で唯一オープンソースではない部分です。Prisma Studioはローカルでのみ実行できます。

Prisma Clientは、あらゆる Node.js（サポートされているバージョン）またはTypeScriptバックエンドアプリケーション（サーバーレスアプリケーションやマイクロサービスを含む）で使用できます。これは、REST API、GraphQL API、gRPC API、またはデータベースを必要とするその他のものでありえます。

Prisma ORMはどのように機能するのですか？​

Prisma schema​

Prisma ORMツールキットのツールを使用するすべてのプロジェクトは、Prisma schemaから始まります。Prisma schemaを使用すると、開発者は直感的なデータモデリング言語でアプリケーションモデルを定義できます。また、データベースへの接続とジェネレーターも定義します。

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

generator client {
  provider = "prisma-client-js"
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  Int?
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

注記: Prisma schemaには強力なデータモデリング機能があります。たとえば、「Prismaレベル」のリレーションフィールドを定義して、Prisma Client APIのリレーションクエリを扱いやすくすることができます。上記の例では、Userのpostsフィールドは「Prismaレベル」でのみ定義されており、基盤となるデータベースの外部キーとしては現れません。

このスキーマでは、次の3つを設定します。

  • データソース: データベース接続を指定します（環境変数を介して）
  • ジェネレーター: Prisma Clientを生成したいことを示します
  • データモデル: アプリケーションモデルを定義します

Prisma schemaデータモデル​

このページでは、データモデルに焦点を当てています。データソースとジェネレーターの詳細については、それぞれのドキュメントページをご覧ください。

Prisma schemaデータモデルの機能​

データモデルは、モデルの集合です。モデルには2つの主要な機能があります。

  • リレーショナルデータベースのテーブルまたはMongoDBのコレクションを表す
  • Prisma Client APIのクエリの基盤を提供する

データモデルを取得する​

Prisma schemaにデータモデルを「取得」するための2つの主要なワークフローがあります。

データモデルが定義されたら、Prisma Clientを生成できます。これにより、定義されたモデルのCRUDおよびその他のクエリが公開されます。TypeScriptを使用している場合は、モデルのフィールドのサブセットのみを取得する場合でも、すべてのクエリに対して完全な型安全性が得られます。

Prisma Clientでデータベースにアクセスする​

Prisma Clientの生成​

Prisma Clientを使用する最初のステップは、@prisma/clientとprisma npmパッケージをインストールすることです。

npm install @prisma/client
npm install prisma --save-dev

次に、prisma generateを実行できます。

npx prisma generate

prisma generateコマンドは、Prisma schemaを読み取り、Prisma Clientコードを生成します。コードは、デフォルトでnode_modules/.prisma/clientフォルダーに生成されます。

データモデルを変更した後、node_modules/.prisma/client内のコードが更新されるように、prisma generateを実行してPrisma Clientを手動で再生成する必要があります。

Prisma Clientを使用してデータベースにクエリを送信する​

Prisma Clientが生成されたら、コードにインポートしてデータベースにクエリを送信できます。これはセットアップコードの例です。

Prisma Clientのインポートとインスタンス化​
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

これで、生成されたPrisma Client APIを介してクエリの送信を開始できます。いくつかのサンプルクエリを次に示します。すべてのPrisma Clientクエリは、プレーンな古いJavaScriptオブジェクトを返すことに注意してください。

利用可能な操作の詳細については、Prisma Client APIリファレンスを参照してください。

データベースからすべてのUserレコードを取得する​
// Run inside `async` function
const allUsers = await prisma.user.findMany()
返された各Userオブジェクトにpostsリレーションを含める​
// Run inside `async` function
const allUsers = await prisma.user.findMany({
  include: { posts: true },
})
"prisma"を含むすべてのPostレコードをフィルタリングする​
// Run inside `async` function
const filteredPosts = await prisma.post.findMany({
  where: {
    OR: [
      { title: { contains: 'prisma' } },
      { content: { contains: 'prisma' } },
    ],
  },
})
同じクエリで新しいUserレコードと新しいPostレコードを作成する​
// Run inside `async` function
const user = await prisma.user.create({
  data: {
    name: 'Alice',
    email: 'alice@prisma.io',
    posts: {
      create: { title: 'Join us for Prisma Day 2020' },
    },
  },
})
既存のPostレコードを更新する​
// Run inside `async` function
const post = await prisma.post.update({
  where: { id: 42 },
  data: { published: true },
})

TypeScriptでの使用法​

TypeScriptを使用する場合、このクエリの結果は静的に型付けされるため、存在しないプロパティに誤ってアクセスすることはありません（タイプミスはコンパイル時にキャッチされます）。Prisma Clientの生成された型を活用する方法の詳細については、ドキュメントの生成された型の高度な使用法ページを参照してください。

一般的なPrisma ORMワークフロー​

上記のように、Prisma schemaにデータモデルを「取得」する方法は2つあります。どちらのアプローチを選択するかによって、メインのPrisma ORMワークフローが異なる場合があります。

Prisma Migrate​

Prisma Migrate、Prisma ORMの統合データベースマイグレーションツールを使用すると、ワークフローは次のようになります。

  1. Prisma schemaデータモデルを手動で調整する
  2. prisma migrate dev CLIコマンドを使用して開発データベースを移行する
  3. アプリケーションコードでPrisma Clientを使用してデータベースにアクセスする

Typical workflow with Prisma Migrate

Prisma Migrateワークフローの詳細については、以下を参照してください。

SQLマイグレーションとイントロスペクション​

何らかの理由でPrisma Migrateを使用できない、または使用したくない場合でも、イントロスペクションを使用してデータベーススキーマからPrisma schemaを更新できます。SQLマイグレーションとイントロスペクションを使用する場合の一般的なワークフローはわずかに異なります。

  1. SQLまたはサードパーティのマイグレーションツールを使用してデータベーススキーマを手動で調整する
  2. データベースを（再）イントロスペクションする
  3. オプションでPrisma Client APIを（再）構成する
  4. Prisma Clientを（再）生成する
  5. アプリケーションコードでPrisma Clientを使用してデータベースにアクセスする

Introspect workflow

イントロスペクションワークフローの詳細については、イントロスペクションセクションを参照してください。