跳到主要內容

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. 建立第一個 migration
    prisma migrate dev --name init
    顯示CLI結果

    您的 Prisma schema 現在已與您的資料庫 schema 同步，並且您已初始化 migration 歷史記錄

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

  2. 將其他欄位新增至您的 schema

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

  3. 建立第二個 migration

    prisma migrate dev --name added_job_title
    顯示CLI結果

    您的 Prisma schema 再次與您的資料庫 schema 同步，並且您的 migration 歷史記錄包含兩個 migrations

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

您現在擁有 migration 歷史記錄，您可以將其原始碼控制並用於將變更部署到測試環境和生產環境。

將 Prisma Migrate 新增至現有專案​

將 Prisma Migrate 新增至現有專案所涉及的步驟如下

  1. 反省您的資料庫以更新您的 Prisma schema
  2. 建立基準 migration
  3. 更新您的 schema 或 migration 以解決 Prisma Schema Language 不支援的功能
  4. 套用基準 migration
  5. 提交 migration 歷史記錄和 Prisma schema

反省以建立或更新您的 Prisma schema​

請確保您的 Prisma schema 與您的資料庫 schema 同步。如果您使用的是先前版本的 Prisma Migrate，則應該已經是這樣。

  1. 反省資料庫以確保您的 Prisma schema 是最新的 
    prisma db pull

建立基準 migration​

基準化是為資料庫初始化 migration 歷史記錄的過程，該資料庫

  • 在您開始使用 Prisma Migrate 之前就已存在
  • 包含必須維護的資料（例如生產環境），這表示無法重設資料庫

基準化告訴 Prisma Migrate 假設一個或多個 migrations 已經被套用。這可以防止產生的 migrations 在嘗試建立已存在的表格和欄位時失敗。

若要建立基準 migration

  1. 如果您有 prisma/migrations 資料夾，請刪除、移動、重新命名或封存此資料夾。
  2. 執行以下命令以在內部建立一個名為 migrations 的目錄，並使用您偏好的名稱。此範例將使用 0_init 作為 migration 名稱 
    mkdir -p prisma/migrations/0_init
    注意

    0_ 很重要，因為 Prisma Migrate 以詞彙順序套用 migrations。您可以使用不同的值，例如目前的時間戳記。

  3. 產生 migration 並使用 prisma migrate diff 將其儲存到檔案 
    npx prisma migrate diff \
    --from-empty \
    --to-schema-datamodel prisma/schema.prisma \
    --script > prisma/migrations/0_init/migration.sql
  4. 檢閱產生的 migration。

解決 Prisma Schema Language 不支援的功能​

若要包含資料庫中已存在的不支援的資料庫功能，您必須取代或修改初始 migration SQL

  1. 開啟在建立基準 migration 章節中產生的 migration.sql 檔案。
  2. 修改產生的 SQL。例如
  • 如果變更很小，您可以將額外的自訂 SQL 附加到產生的 migration。以下範例建立部分索引 
    /* Generated migration SQL */

    CREATE UNIQUE INDEX tests_success_constraint ON posts (subject, target)
      WHERE success;
  • 如果變更很大，則將整個 migration 檔案替換為資料庫傾印的結果（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 錯誤

套用初始 migrations​

若要套用您的初始 migration(s)

  1. 針對您的資料庫執行以下命令

    npx prisma migrate resolve --applied 0_init

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

新的 migration 歷史記錄和資料庫 schema 現在應與您的 Prisma schema 同步。

提交 migration 歷史記錄和 Prisma schema​

將以下內容提交到原始碼控制

  • 整個 migration 歷史記錄資料夾
  • schema.prisma 檔案

更進一步​