Prisma Migrate 入門

本頁說明如何使用 Prisma Migrate 在開發環境中開始遷移你的架構 (Schema)。

從零開始使用 Prisma Migrate

要在開發環境中開始使用 Prisma Migrate

建立 Prisma 架構 (Schema)

Prisma 7

Prisma 6

schema.prisma

datasource db {
  provider = "postgresql"
}

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

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

schema.prisma

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

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

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

提示

你可以在架構中使用原生資料庫類型映射屬性來決定具體要建立的資料庫類型（例如，String 可以映射為 varchar(100) 或 text）。

對於 Prisma 7，請確保專案根目錄中有一個 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",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

建立第一次遷移
prisma migrate dev --name init
顯示CLI結果
你的 Prisma 架構現在已與資料庫架構同步，且你已初始化遷移歷史記錄
```
migrations/
  └─ 20210313140442_init/
    └─ migration.sql
```
注意：資料夾名稱會與你顯示的不同。資料夾命名格式為 YYYYMMDDHHMMSS_name_標記中的文字。

在架構中新增其他欄位

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

建立第二次遷移

prisma migrate dev --name added_job_title

顯示CLI結果

你的 Prisma 架構再次與資料庫架構同步，且你的遷移歷史記錄中包含兩次遷移

migrations/
  └─ 20210313140442_init/
    └─ migration.sql
  └─ 20210313140442_added_job_title/
    └─ migration.sql

現在，你擁有一個可以進行版本控制的遷移歷史記錄，並可用於將變更部署到測試環境和正式環境。

將 Prisma Migrate 新增至現有專案

將 Prisma Migrate 新增至現有專案的步驟如下：

內省 (Introspect) 資料庫以更新你的 Prisma 架構
建立基準遷移（Baseline migration）
更新架構或遷移，以解決 Prisma 架構語言不支援的功能
應用基準遷移 (Baseline migration)
提交遷移歷史記錄與 Prisma 架構

內省以建立或更新你的 Prisma 架構

確保你的 Prisma 架構與資料庫架構同步。如果你使用的是舊版 Prisma Migrate，這應該已經是同步狀態。

內省資料庫以確保你的 Prisma 架構為最新版本
```
prisma db pull
```

建立基準遷移

基準化 (Baselining) 是為資料庫初始化遷移歷史記錄的過程，該資料庫：

在你開始使用 Prisma Migrate 之前就已存在
包含必須保留的資料（例如正式環境），這意味著資料庫無法被重置

基準化會告知 Prisma Migrate 預設已有一個或多個遷移已經應用。這可以防止在嘗試建立已存在的資料表和欄位時，自動生成的遷移失敗。

要建立基準遷移：

如果你已有 prisma/migrations 資料夾，請刪除、移動、重新命名或歸檔該資料夾。
執行以下指令以建立一個帶有你偏好名稱的 migrations 目錄。此範例將使用 0_init 作為遷移名稱
```
mkdir -p prisma/migrations/0_init
```
注意
0_ 字首非常重要，因為 Prisma Migrate 會依照字典順序 (lexicographic order)應用遷移。你可以使用其他值，例如當前時間戳。

使用 prisma migrate diff 產生遷移並將其儲存至檔案

npx prisma migrate diff \
--from-empty \
--to-schema-datamodel prisma/schema.prisma \
--script > prisma/migrations/0_init/migration.sql

審閱產生的遷移。

解決 Prisma 架構語言不支援的功能

若要納入資料庫中已存在的不支援的資料庫功能，你必須替換或修改初始遷移的 SQL

開啟在建立基準遷移章節中產生的 migration.sql 檔案。
修改產生的 SQL。例如：

如果變更很小，你可以將額外的自定義 SQL 附加到產生的遷移中。以下範例建立了部分索引：

/* Generated migration SQL */

CREATE UNIQUE INDEX tests_success_constraint ON posts (subject, target)
  WHERE success;

如果變更重大，使用資料庫轉儲（mysqldump, pg_dump）的結果來替換整個遷移檔案可能會比較容易。使用 pg_dump 進行此操作時，你需要透過以下指令更新 search_path：SELECT pg_catalog.set_config('search_path', '', false);；否則會遇到以下錯誤：The underlying table for model '_prisma_migrations' does not exist.
資訊
請注意，在同時建立所有資料表時，資料表的順序很重要，因為外鍵是在同一步驟中建立的。因此，請重新排序或將約束建立移至最後一步（在所有資料表建立完成後），這樣你就不會遇到 can't create constraint 錯誤。

應用初始遷移

要應用你的初始遷移：

對你的資料庫執行以下指令

npx prisma migrate resolve --applied 0_init

審閱資料庫架構，確保遷移達到預期的最終狀態（例如，透過將架構與正式環境資料庫進行比較）。

新的遷移歷史記錄和資料庫架構現在應該與你的 Prisma 架構同步。

提交遷移歷史記錄與 Prisma 架構

將以下內容提交到版本控制：

整個遷移歷史記錄資料夾
schema.prisma 檔案

進階內容

請參閱使用 Prisma Migrate 部署資料庫變更指南，以深入了解如何將遷移部署到正式環境。
請參閱正式環境故障排除指南，了解如何使用 prisma migrate diff、prisma db execute 和/或 prisma migrate resolve 來調試並解決正式環境中失敗的遷移。

從零開始使用 Prisma Migrate​

將 Prisma Migrate 新增至現有專案​

內省以建立或更新你的 Prisma 架構​

建立基準遷移​

解決 Prisma 架構語言不支援的功能​

應用初始遷移​

提交遷移歷史記錄與 Prisma 架構​

進階內容​