什麼是 Prisma ORM？

Prisma ORM 是一個開源新一代 ORM。它由以下部分組成：

• Prisma Client：為 Node.js 和 TypeScript 自動生成且型別安全 (type-safe) 的查詢建構器。

• Prisma Migrate：遷移系統 (Migration system)。

• 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 允許開發者以直觀的資料建模語言來定義他們的應用程式模型。它同時包含了資料庫連接的設定並定義了一個產生器 (generator)。

datasource db {
  provider = "postgresql"
}

generator client {
  provider = "prisma-client"
  output   = "./generated"
}

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[]
}

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

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

model Post {
  id        String  @id @default(auto()) @map("_id") @db.ObjectId
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  String  @db.ObjectId
}

model User {
  id    String  @id @default(auto()) @map("_id") @db.ObjectId
  email String  @unique
  name  String?
  posts Post[]
}

注意：Prisma schema 具有強大的資料建模功能。例如，它允許你定義「Prisma 層級」的 關聯欄位，這將使處理 Prisma Client API 中的關聯變得更加容易。在上述範例中，User 上的 posts 欄位僅定義在「Prisma 層級」，這表示它不會在底層資料庫中展現為外鍵 (foreign key)。

在此 schema 中，你需要設定三件事：

• 資料來源 (Data source)：指定你的資料庫連接。資料庫連接網址 (URL) 設定在 prisma.config.ts 中。
• 產生器 (Generator)：指出你想要生成 Prisma Client。
• 資料模型 (Data model)：定義你的應用程式模型。

設定資料庫連接

資料庫連接網址設定在 prisma.config.ts 檔案中。請在專案根目錄中建立一個 prisma.config.ts 檔案。

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx ./prisma/seed.ts',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

資訊

使用 Prisma CLI 命令時，環境變數不會自動載入。您需要使用像 dotenv 這樣的套件從 .env 檔案載入環境變數，或確保您的環境變數已在您的 shell 中設定。

Prisma Schema 資料模型

本頁面重點在於資料模型。你可以在各自的文件頁面中進一步了解 資料來源 和 產生器。

Prisma Schema 資料模型的功能

資料模型是 模型 (models) 的集合。模型有兩個主要功能：

• 代表關聯式資料庫中的資料表，或是 MongoDB 中的集合 (collection)。
• 為 Prisma Client API 中的查詢提供基礎。

取得資料模型

將資料模型「取得」到 Prisma schema 中主要有兩種工作流程：

• 手動編寫資料模型，並透過 Prisma Migrate 將其對應到資料庫。
• 透過對資料庫進行 內省 (introspection) 來生成資料模型。

一旦定義了資料模型，你就可以 生成 Prisma Client，這將為定義的模型公開 CRUD 及更多查詢功能。如果你使用 TypeScript，你將獲得所有查詢的完整型別安全性（即使只擷取模型欄位的子集）。

使用 Prisma Client 存取資料庫

生成 Prisma Client

使用 Prisma Client 的第一步是安裝 @prisma/client 和 prisma npm 套件。

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

然後，你可以執行 prisma generate。

npx prisma generate

prisma generate 指令會讀取你的 Prisma schema 並生成 Prisma Client 程式碼。程式碼會根據 generator 區塊中 output 欄位指定的路徑進行生成（例如上述 schema 範例中的 ./generated）。

當你修改資料模型後，需要透過執行 prisma generate 手動重新生成 Prisma Client，以確保生成的程式碼已更新。

使用 Prisma Client 向資料庫發送查詢

一旦 Prisma Client 生成完畢，你就可以在程式碼中匯入它並向資料庫發送查詢。設定程式碼如下所示。

匯入並實例化 Prisma Client

import { PrismaClient } from './generated/client'

const prisma = new PrismaClient()

const { PrismaClient } = require('./generated/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 中有兩種方法。根據你選擇的方法，主要的 Prisma ORM 工作流程可能會有所不同。

Prisma Migrate

使用 Prisma Migrate（Prisma ORM 的整合式資料庫遷移工具），工作流程如下：

1. 手動調整你的 Prisma schema 資料模型。
2. 使用 prisma migrate dev CLI 指令遷移你的開發資料庫。
3. 在應用程式程式碼中使用 Prisma Client 來存取資料庫。

若要進一步了解 Prisma Migrate 工作流程，請參閱：

• 使用 Prisma Migrate 部署資料庫變更

• 使用 Prisma Migrate 進行開發

SQL 遷移與內省

如果由於某種原因你無法或不想使用 Prisma Migrate，你仍然可以使用內省從資料庫 schema 更新 Prisma schema。使用 SQL 遷移與內省 的典型工作流程略有不同：

1. 使用 SQL 或第三方遷移工具手動調整資料庫 schema。
2. (重新)對你的資料庫進行內省。
3. 可選：(重新)設定你的 Prisma Client API。
4. (重新)生成 Prisma Client。
5. 在應用程式程式碼中使用 Prisma Client 來存取資料庫。

若要進一步了解內省工作流程，請參考 內省章節。