Skip to main content
遷移是 migrations/ 中應用於 @insforge/cli 的版本化 SQL 檔案。每次成功執行都記錄在 system.custom_migrations 中。工作流程是僅向前的。

​
概念

遷移是一個帶有 14 位數 UTC 時間戳前綴的 SQL 檔案：<YYYYMMDDHHmmss>_<name>.sql。CLI 在交易內按順序應用待處理檔案，將 search_path 設定為 public，並僅在成功時記錄歷史。PostgREST 自動重新載入架構中繼資料。檔案內的 BEGIN/COMMIT/ROLLBACK 被拒絕。

​
用法

連結後端，然後建立檔案。
編寫 SQL。
應用待處理的遷移並檢查歷史。
使用 up <version> 針對單個檔案，或使用 up --to <version> 應用到目標為止的所有待處理項。

​
特定用法案例

在現有專案上採用遷移：首先執行 db migrations fetch 來將遠端歷史具體化為本機檔案。一旦應用於遠端，永遠不要就地編輯遷移。改為編寫前向遷移。 選擇加入後，透過檔案路由所有架構變更。臨時儀表板編輯會在 git 和 system.custom_migrations 之間造成漂移。

​
非交易性陳述式

由於 CLI 會把每個遷移檔案放在單個交易內執行（這也是 BEGIN/COMMIT/ROLLBACK 被拒絕的原因），少數無法在交易區塊內執行的 PostgreSQL 命令會在遷移中失敗，並回報類似 CREATE INDEX CONCURRENTLY cannot run inside a transaction block 的錯誤。常見的有：
  • CREATE INDEX CONCURRENTLY — 若可接受短暫的寫入鎖定，就在遷移中使用一般的 CREATE INDEX；或在遷移之外執行並行建置（見下文）。
  • VACUUM — 例行 vacuum 由 PostgreSQL autovacuum 處理，您很少需要自己執行。
  • REINDEX ... CONCURRENTLY、ALTER TYPE ... ADD VALUE（在較舊的 PostgreSQL 上）等類似命令。
請使用 CLI 的 unrestricted 原始 SQL 路徑在遷移之外執行這些命令，它會執行陳述式而不將其包在交易中：
一般的 npx @insforge/cli db query（不帶 --unrestricted）會把陳述式包在交易裡，因此會遇到同樣的錯誤——對於非交易性命令請使用 --unrestricted。
兩種 db query 路徑都會強制套用 30 秒的 statement_timeout，因此在大型資料表上執行 CREATE INDEX CONCURRENTLY 或 VACUUM 可能會逾時。

​
更多資源