Claude Code 寫資料庫遷移：分階段改，先驗證再移除

改欄位，亦要照顧仲運作緊嘅程式

假設 users.name 要拆成幾個新欄位。直接重新命名舊欄位，舊版服務、報表或者排程仍然讀緊 name，就可能即時出錯。

常用做法係 expand–migrate–contract：先加新結構，再搬資料同切換程式，最後先移除舊結構。呢個方法有助管理相容性，但唔保證零停機，亦唔代表每一步都可以無損復原。

以下係規劃同審閱教學，SQL 只應先喺受控測試環境試。正式執行要由有權限嘅負責人確認版本、備份、影響範圍同操作窗口。

1. 先確認資料本身可以點轉

姓名唔可以可靠地按空格拆成姓同名。中文名、複姓、單名、不同文化嘅次序同稱謂，都會令簡單拆分出錯。

先決定產品真正需要乜：如果只係 Email 稱呼，可能保留顯示名稱已足夠。真係要新欄位，就要定義由用戶確認、人工處理或保留未分類資料嘅方法，唔好靠 Claude 猜。

請根據目前資料庫版本、ORM、部署流程同讀寫入口，提出分階段遷移計劃，暫時唔修改或執行 SQL。

列出每階段：舊版同新版程式讀寫邊啲欄位、鎖定要求、失敗停止條件、監察指標，以及可唔可以退回舊版程式。

標出唔能夠無損轉換嘅資料。唔好用空格自動判斷姓名，亦唔好將重新拼合字串當成原始資料已復原。

2. 擴充：先加欄位，保留舊欄位

以下只示範增加兩個可空值欄位：

ALTER TABLE users ADD COLUMN first_name TEXT;
ALTER TABLE users ADD COLUMN last_name TEXT;

「通常唔需要重寫整張表」同「唔需要鎖」係兩回事。PostgreSQL 嘅 ALTER TABLE 仍可能需要強鎖，並等待其他交易；等待期間亦可能影響之後嘅請求。可按操作需要設定 lock_timeout 等等待上限，先觀察長交易，再喺相近負載測試。

亦唔可以一概話加固定 DEFAULT 一定重寫整表。PostgreSQL 較新版本對部分非易變預設值有最佳化；實際行為要按版本同表達式核對。參考PostgreSQL ALTER TABLE 文件。

外鍵或 CHECK 約束可研究先用 NOT VALID 加入、再另行 VALIDATE CONSTRAINT 嘅做法；適用限制、鎖定同舊資料驗證要按版本確認，唔係任何約束都支援。

Prisma 專案唔好用 prisma db push 代替正式 migration 部署流程；先審閱產生嘅 SQL，並喺測試環境跑遷移。

ORM 產生嘅 migration 要逐句睇，唔好只睇 model 差異。新程式如果即時讀新欄位，就必須等新增欄位完成先部署，唔係任何先後次序都安全。

3. 搬移：處理新寫入，再補舊資料

先盤點所有寫入入口：API、後台、批次匯入、排程、直接 SQL 同外部整合。只搜尋一個欄位字串未必搵得齊，ORM 別名同動態 SQL 都可能漏。

過渡期要決定邊份資料作準，同一項更新點樣保持一致。應用程式雙寫通常要喺同一個交易完成；如果有舊版程式繼續只寫舊欄位，就要先處理佢，唔可以假設新程式已涵蓋所有寫入。

根據已確認嘅轉換規則，設計補資料程序，先提供草稿。

要有試行模式、批次處理、穩定游標、每批完成記錄同重試方法。列明點避免覆蓋用戶喺補資料期間新修改嘅值。

先處理少量測試資料，再根據鎖等待、複寫延遲、磁碟同正常 API 延遲調整批次大小。超過已定門檻就停止，唔好無限重試。

FOR UPDATE SKIP LOCKED 可以用喺特定並行批次設計，但唔係加上去就自動安全。鎖要同更新放喺合適交易，跳過嘅資料最後亦要補返。單靠新欄位係 NULL 判斷進度亦可能出錯，因為 NULL 可以係合法結果。

驗證唔止睇總行數：要查漏項、轉換失敗、重複、抽樣內容，同新舊讀取路徑結果。確認後先逐步切換讀取，保留可以停低嘅中間狀態。

4. 收尾：按證據移除，唔係等夠七日

等七日或者三十日都唔係保證。要睇最長排程週期、報表、舊版服務、資料匯出、復原流程，以及團隊支援舊版嘅窗口。

列出仍引用舊欄位嘅程式、報表、排程、資料匯出同資料庫物件。

說明觀察期涵蓋咗邊啲使用週期，邊啲尚未驗證。確認舊版程式已退出、雙寫安排已調整，並完成資料完整性檢查。

只提出移除草稿同復原限制，唔好執行 DROP。若無法確認原始資料有可用備份，明確標記未準備好。

刪欄位後再加返同名欄位，只係恢復結構，唔會自動恢復資料。備份要實際測試還原；由新欄位推回舊字串亦未必保持原始格式。某些情況向前修正比執行 down migration 更適合。

多租戶同索引要另外核對

多租戶共用一張表時，按租戶分批補資料可以控制工作量，但表級結構鎖仍然影響整張表。RLS 亦唔可以直接假設完全無關，要檢查執行角色、政策同新增程式嘅存取行為。

CREATE INDEX CONCURRENTLY 可減少對正常寫入嘅阻塞，但有自己嘅限制同失敗處理，亦唔可以隨意包入一般交易區塊。每項操作都應按實際 PostgreSQL 版本同工具文件確認。

一份好遷移計劃，要答到「中途停喺呢度會點」。Claude 可以幫你整理依賴同檢查遺漏，但唔應代替實際負載測試同操作審批。