[DOCS] - Experiment how to do db migration involving changed schema and existing data - on empty database

[arealclimber]

Summary

[DOCS] - Experiment how to do db migration involved changed schema and existing data - on empty database

ref

• https://github.com/CAFECA-IO/iSunFA/issues/3293
• KM
• https://www.youtube.com/watch?v=PX881bVAPxM
• https://www.prisma.io/docs/orm/prisma-client/deployment/deploy-migrations-from-a-local-environment

Tasks

實驗空白資料庫遷移流程

1. 了解 sql 語法

2. 開空白資料庫

3. 寫 sql 腳本去修改 db data and schema，實驗 sql 腳本是否有寫錯

   1. psql -h <HOST_IP> -U <USER_NAME> -d <DATABASE_NAME> -f <SQL_FILE_NAME>

4. [測試在 schema 跟 migration.sql 不同的情況]手動更新 schema.prisma、將 sql 腳本放到 prisma/migration 裡，並且執行以下指令，將 migration.sql 應用到 db 後，查看 db 跟 schema.prisma 是否將資料庫結構改成需要的樣子

   1. npx prisma migrate deploy

5. [測試 KM 的遷移步驟]更新 schema.prisma ，然後執行npx prisma migrate dev --create-only --name custom-sql-migration指令，產生 migration.sql 之後，根據需求編輯 migration.sql ；修改好 migration.sql 之後在空白資料庫執行 npx prisma migrate deploy 、npx prisma generate 、npx prisma db seed

Dependencies

No response

Other Dependencies

No response

Additional Notes

No response

[arealclimber]

ALTER TABLE 相關語法.md Database migration 常見情境.md Prisma vs 直接寫 SQL 遷移的差異.md SQL 語法.md 使用 Prisma CLI 檢視.md 其他操作.md 基本操作.md 如何檢視資料庫遷移結果.md 建立檢查清單.md 直接連接資料庫檢視.md 紀錄檢查結果.md 資料庫物件命名慣例.md

[arealclimber]

flowchart TD
    A["開始"] --> B{"選擇遷移方法"}
    B -- 方法一 --> C["手動編寫 migration.sql"]
    C --> C1["受影響的檔案: prisma/migrations/\_migration.sql"]
    C1 --> D["運行 npx prisma migrate deploy"]
    D --> D1["應用 migration.sql 至資料庫"]
    D1 --> E["部署遷移"]
    E --> n1
    E --> F["檢視遷移結果"]
    F --> G["結束"]
    B -- 方法二 --> H["修改 schema.prisma"]
    H --> H1["受影響的檔案: prisma/schema.prisma"]
    H1 --> I["運行 npx prisma migrate dev"]
    I --> I1["生成 prisma/migrations/\_migration.sql"]
    I1 --> J["版本控制提交"]
    J --> K["運行 npx prisma migrate deploy"]
    K --> K1["應用 prisma/migrations/\_migration.sql 至資料庫"]
    K1 --> M["部署遷移"]
    M --> F
    n1["運行 npx prisma db pull 將資料庫結構更新到 schema.prisma"]

    n1@{ shape: rect}

[arealclimber]

參考 KM ，畫出 db migration 最佳實踐流程圖

graph TD
    Start[開始資料庫遷移] --> CheckEnv{檢查環境}

    CheckEnv -->|本地開發環境| LocalDev[本地開發流程]
    CheckEnv -->|雲端環境| CloudDev[雲端部署流程]

    %% 本地開發流程
    LocalDev --> BackupLocal[備份本地資料庫]
    BackupLocal --> ModifySchema[修改 schema.prisma]
    ModifySchema --> CreateOnly[運行 prisma migrate dev --create-only]
    CreateOnly --> EditSQL[檢查/編輯 migration.sql]
    EditSQL --> TestLocal[本地測試遷移]
    TestLocal --> CheckResult{檢查結果}

    CheckResult -->|失敗| ModifySchema
    CheckResult -->|成功| GitCommit[提交到版本控制]

    %% 雲端部署流程
    CloudDev --> BackupCloud[備份雲端資料庫]
    BackupCloud --> RunDeploy[運行 prisma migrate deploy]
    RunDeploy --> VerifyCloud[驗證雲端遷移]
    VerifyCloud --> DeployResult{部署結果}

    DeployResult -->|失敗| Rollback[執行回滾計劃]
    DeployResult -->|成功| UpdateClient[更新 Prisma Client]

    %% 共同結束流程
    GitCommit --> RunDeploy
    Rollback --> BackupCloud
    UpdateClient --> End[結束遷移]

    %% 子步驟說明
    subgraph "本地開發檢查項目"
        TestLocal --> CheckSchema[檢查 Schema 變更]
        TestLocal --> CheckSQL[驗證 SQL 語法]
        TestLocal --> RunTests[執行單元測試]
    end

    subgraph "雲端部署檢查項目"
        VerifyCloud --> CheckDB[檢查資料庫結構]
        VerifyCloud --> ValidateData[驗證資料完整性]
        VerifyCloud --> MonitorPerf[監控性能影響]
    end

[arealclimber]

took 6 hrs done