Prisma Migrate 入門

本頁面解釋瞭如何在開發環境中使用 Prisma Migrate 開始遷移你的 schema。

從零開始使用 Prisma Migrate

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

1. 建立一個 Prisma schema

   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])
   }
   提示

   你可以在 schema 中使用原生型別對映屬性來決定建立哪種確切的資料庫型別（例如，String 可以對映到 varchar(100) 或 text）。

   1. 建立第一次遷移

   prisma migrate dev --name init

   顯示CLI結果

   你的 Prisma schema 現在與資料庫 schema 同步，並且你已初始化了遷移歷史記錄

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

2. 向你的 schema 新增額外欄位

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

3. 建立第二次遷移

   prisma migrate dev --name added_job_title

   顯示CLI結果

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

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

你現在擁有一個遷移歷史記錄，可以進行原始碼管理，並用於部署更改到測試環境和生產環境。

將 Prisma Migrate 新增到現有專案

將 Prisma Migrate 新增到現有專案所涉及的步驟是：

1. 內省資料庫以更新你的 Prisma schema
2. 建立基線遷移
3. 更新你的 schema 或遷移以解決 Prisma Schema Language 不支援的特性
4. 應用基線遷移
5. 提交遷移歷史記錄和 Prisma schema

內省以建立或更新你的 Prisma schema

確保你的 Prisma schema 與資料庫 schema 同步。如果你正在使用 Prisma Migrate 的舊版本，這應該已經實現了。

1. 內省資料庫以確保你的 Prisma schema 是最新的

   prisma db pull

建立基線遷移

基線化是為以下資料庫初始化遷移歷史記錄的過程：

• 在你開始使用 Prisma Migrate 之前就已存在
• 包含必須維護的資料（如生產環境），這意味著資料庫不能被重置

基線化告訴 Prisma Migrate 假定一個或多個遷移已經被應用。這可以防止生成的遷移在嘗試建立已存在的表和欄位時失敗。

要建立基線遷移

1. 如果你有一個 prisma/migrations 資料夾，請刪除、移動、重新命名或歸檔此資料夾。
2. 執行以下命令以在你偏好的名稱下建立 migrations 目錄。本例將使用 0_init 作為遷移名稱

   mkdir -p prisma/migrations/0_init
   注意

   0_很重要，因為 Prisma Migrate 以字典序應用遷移。你可以使用不同的值，例如當前時間戳。

3. 使用 prisma migrate diff 生成遷移並儲存到檔案

   npx prisma migrate diff \
   --from-empty \
   --to-schema-datamodel prisma/schema.prisma \
   --script > prisma/migrations/0_init/migration.sql
4. 審查生成的遷移。

解決 Prisma Schema Language 不支援的特性

要包含資料庫中已存在的不支援的資料庫特性，你必須替換或修改初始遷移 SQL

1. 開啟在建立基線遷移部分生成的 migration.sql 檔案。
2. 修改生成的 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 錯誤

應用初始遷移

要應用你的初始遷移

1. 在你的資料庫上執行以下命令

   npx prisma migrate resolve --applied 0_init

2. 審查資料庫 schema，以確保遷移達到所需的最終狀態（例如，透過將 schema 與生產資料庫進行比較）。

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

提交遷移歷史記錄和 Prisma schema

將以下內容提交到原始碼管理：

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

進一步瞭解

• 有關將遷移部署到生產環境的更多資訊，請參閱使用 Prisma Migrate 部署資料庫更改指南。
• 要了解如何使用 prisma migrate diff、prisma db execute 和/或 prisma migrate resolve 除錯和解決生產環境中的失敗遷移，請參閱生產故障排除指南。