跳到主要內容

使用擴展與收縮模式遷移資料

10 分鐘

簡介​

在生產環境中變更資料庫結構描述時，確保資料一致性並避免停機至關重要。本指南說明如何使用擴展與收縮模式安全地在欄位之間遷移資料。我們將逐步說明一個實際範例，將布林值欄位替換為列舉欄位，同時保留現有資料。

先決條件​

開始本指南之前，請確保您已具備

  • 已安裝 Node.js（版本 18 或更高版本）
  • 具有現有結構描述的 Prisma ORM 專案
  • 支援的資料庫（PostgreSQL、MySQL、SQLite、SQL Server 等）
  • 開發和生產資料庫的存取權
  • Git 分支的基本理解
  • TypeScript 的基本熟悉度

1. 設定您的環境​

1.1. 檢閱初始結構描述​

從包含 Post 模型的基本結構描述開始

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

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

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
}

1.2. 建立開發分支​

為您的變更建立新分支

git checkout -b create-status-field

2. 擴展結構描述​

2.1. 新增欄位​

更新您的結構描述以新增新的 Status 列舉和欄位

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean? @default(false)
  status    Status   @default(Unknown)
}

enum Status {
  Unknown
  Draft
  InProgress
  InReview
  Published
}

2.2. 建立遷移​

產生遷移

npx prisma migrate dev --name add-status-column

3. 遷移資料​

3.1. 建立遷移腳本​

為資料遷移建立新的 TypeScript 檔案

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  await prisma.$transaction(async (tx) => {
    const posts = await tx.post.findMany()
    for (const post of posts) {
      await tx.post.update({
        where: { id: post.id },
        data: {
          status: post.published ? 'Published' : 'Unknown',
        },
      })
    }
  })
}

main()
  .catch(async (e) => {
    console.error(e)
    process.exit(1)
  })
  .finally(async () => await prisma.$disconnect())

3.2. 設定遷移腳本​

將遷移腳本新增至您的 package.json

{
  "scripts": {
    "data-migration:add-status-column": "tsx ./prisma/migrations/<migration-timestamp>/data-migration.ts"
  }
}

3.3. 執行遷移​

  1. 更新您的 DATABASE_URL 以指向生產資料庫
  2. 執行遷移腳本
npm run data-migration:add-status-column

4. 收縮結構描述​

4.1. 建立清理分支​

建立新分支以移除舊欄位

git checkout -b drop-published-column

4.2. 移除舊欄位​

更新您的結構描述以移除 published 欄位

model Post {
  id      Int      @id @default(autoincrement())
  title   String
  content String?
  status  Status   @default(Unknown)
}

enum Status {
  Draft
  InProgress
  InReview
  Published
}

4.3. 產生清理遷移​

建立並執行最終遷移

npx prisma migrate dev --name drop-published-column

5. 部署到生產環境​

5.1. 設定部署​

將以下命令新增至您的 CI/CD 管道

npx prisma migrate deploy

5.2. 監控部署​

部署後，監看記錄檔中是否有任何錯誤，並監控應用程式的行為。

疑難排解​

常見問題與解決方案​

  1. 遷移因缺少預設值而失敗

    • 請確保您已新增適當的預設值
    • 檢查是否可以遷移所有現有記錄

  2. 資料遺失預防

    • 在執行遷移之前，務必備份資料庫
    • 先在生產資料的副本上測試遷移

  3. 交易回滾

    • 如果資料遷移失敗，交易將自動回滾
    • 修正任何錯誤並重試遷移

後續步驟​

現在您已完成第一次擴展與收縮遷移，您可以

如需更多資訊和更新