管理核心資料庫遷移

EmDash 核心遷移更新 EmDash 自身的資料表以及內容資料表上的標準欄位。它們不會建立、刪除或重新命名您的集合和欄位；有關內容模型變更，請參閱 演進已部署的網站。

執行時遷移模式預設為 auto，因此現有部署會在啟動時繼續套用待處理的核心遷移。部署管理的遷移允許建置在新應用程式碼接收流量之前遷移其資料庫，然後讓執行時驗證或信任該部署步驟。

建置、遷移、部署、檢查

Astro 建置或同步會寫入 .emdash/migrations.json。此無密鑰清單記錄了該建置使用的確切 EmDash 版本、有序遷移集、地區設定配置和適配器遷移執行器。

從產生清單的相依性所在的專案執行這些命令。首先建置並檢查目標。

pnpm build
pnpm emdash migrate --status

確認回報的目標是預期的資料庫後，啟動互動式遷移。在確認前再次在提示中審查目標。然後部署相同的建置並檢查已部署的架構。

pnpm emdash migrate
pnpm wrangler deploy
pnpm emdash migrate --check

emdash migrate --status 回報已套用、待處理和未知的遷移，而不變更資料庫。簡單的 emdash migrate 命令顯示目標，並在套用待處理遷移之前要求確認。

--check 從不套用遷移，當已知遷移待處理或資料庫包含建置未知的遷移記錄時以非零退出。當您想在不使用 check 的「需要工作」非零退出狀態的情況下檢查相同的遷移集時，請使用 --status。CLI 參考 區分待處理、未知、確認、中斷和操作退出碼。

非互動式套用和每個 --json 套用都需要 --expected-target-fingerprint；如果解析的目標不匹配，命令將失敗。在自動化部署工作中使用這些選項，而不是上述互動式工作流程。

使用 --manifest path/to/migrations.json 指定儲存在其他位置的清單。對於本機調查，--from-config [--config astro.config.mjs] 在不執行 Astro 鉤子或啟動伺服器的情況下明確評估受信任的專案配置。部署管線應使用建置清單。

明確選擇資料庫

配置的適配器向清單提供無密鑰的目標資訊。認證資訊保留在環境變數中，僅由遷移命令讀取。

相對 SQLite 路徑從專案根目錄解析，而不是從已安裝的 EmDash 套件或 shell 的目前子目錄解析。PostgreSQL、libSQL 和 Hyperdrive 目標標籤省略認證資訊和 URL 參數。

遷移前佈建 D1

建立 D1 資料庫和遷移其架構是分開的操作。emdash migrate 從不建立缺少的資料庫。

您也可以提供 --account-id 與 --d1 <資料庫UUID或名稱>。名稱查詢必須恰好解析為一個資料庫。預覽 ID、佔位符 ID、衝突的帳戶和模糊的繫結會以封閉方式失敗。

在 CI 中配置 D1 遷移

D1 不提供 PostgreSQL 使用的諮詢遷移鎖。每個帳戶和資料庫 UUID 最多執行一個遷移工作。

在 CI 環境中設定以下密鑰和變數：

• 密鑰 CLOUDFLARE_API_TOKEN：具有 D1 編輯權限的範圍權杖。
• 變數 CLOUDFLARE_ACCOUNT_ID：擁有資料庫的 Cloudflare 帳戶 ID。
• 變數 D1_DATABASE_ID：正式環境 D1 資料庫 UUID。
• 變數 EMDASH_TARGET_FINGERPRINT：在本機審查帳戶和資料庫後 emdash migrate --status 列印的指紋。

以下 GitHub Actions 工作流程使用這些值，並將並行群組鍵限定為兩個不可變的 D1 識別碼。其套用步驟是非互動式的，因此明確提供已審查的目標指紋。

name: Deploy

on:
  workflow_dispatch:

concurrency:
  group: emdash-migrations-${{ vars.CLOUDFLARE_ACCOUNT_ID }}-${{ vars.D1_DATABASE_ID }}
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - name: Inspect EmDash migration target
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --status --json \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"
      - name: Apply EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          EMDASH_TARGET_FINGERPRINT: ${{ vars.EMDASH_TARGET_FINGERPRINT }}
        run: |
          pnpm emdash migrate \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}" \
            --expected-target-fingerprint "$EMDASH_TARGET_FINGERPRINT"
      - run: pnpm wrangler deploy
      - name: Check EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --check \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"

僅在本機審查變更的目標後才更新 EMDASH_TARGET_FINGERPRINT。指紋不包含認證資訊，但在未檢查帳戶和資料庫的情況下變更它會移除防止遷移錯誤資料庫的保護。

Hyperdrive 連線到來源

Hyperdrive 的遷移執行器開啟到來源的直接 PostgreSQL 連線。它不透過 Hyperdrive 傳送遷移流量，不使用可選的快取繫結，也不繼承 Worker 的私有網路可達性。

部署執行器必須能夠到達來源。當預設的繫結特定變數不合適時，在 hyperdrive() 上設定 migrationConnectionStringEnv，並僅向遷移工作提供該變數。保持執行時 Hyperdrive 認證資訊和直接來源部署認證資訊分開。

逐步採用執行時強制

以下 EmDash 整合配置在保留開發中自動遷移的同時啟用執行時強制。

emdash({
	database,
	migrations: {
		runtime: "check",
		dev: "auto",
	},
});

• auto 是向後相容的預設值。執行時啟動時檢查並套用待處理的遷移。
• check 執行定向狀態查詢，當已知遷移待處理時在服務請求之前回傳 503。在滾動部署期間容忍來自較新相容建置的記錄。
• manual 不執行執行時遷移或狀態查詢。僅在部署管線可靠地套用和檢查每個建置後使用。

當同一構件透過多個環境提升時，EMDASH_MIGRATIONS_MODE 可以覆蓋執行時模式。設定和開發旁路路由遵循有效模式；它們不能在 check 或 manual 後面靜默遷移。

保守的推出方式是：引入部署工作時使用 auto，工作可靠後使用 check，當每次部署都強制執行外部檢查時使用 manual。

滾動部署期間的相容性

核心遷移遵循擴展/部署/收縮排序。部署可能會暫時針對擴展的資料庫執行舊的和新的應用程式隔離，並且回填可能仍在進行中。在每個已部署版本停止使用架構之前，不要收縮架構。

未知的已套用遷移記錄僅在此滾動部署方向上被執行時 check 容忍。CLI 的精確檢查會回報它們，apply 拒絕變更，因為資料庫可能更新或具有不同的遷移歷史。

疑難排解

• 未找到遷移清單。 首先建置或同步專案。對於非標準構件位置使用 --manifest，或明確選擇 --from-config 進行本機調查。
• 構件與專案的 EmDash 不匹配。 重新建置並一起部署應用程式和清單。執行專案的 CLI 而不是全域安裝。
• 目標缺少或模糊。 首先佈建它，然後提供明確的資料庫路徑、連線變數名稱、D1 選擇器或選定的 Wrangler 配置和環境。EmDash 不會從不相關的環境變數或繫結中猜測。
• 目標指紋已變更。 停下來審查顯示的帳戶、環境、資料庫名稱、UUID 或路徑。僅在確認預期目標後更新期望的指紋。
• 存在未知的遷移記錄。 不要刪除記錄或重新執行 apply。確認應用程式構件是預期版本，並調查是否有更新或不同的建置遷移了資料庫。
• D1 寫入結果不明確。 不要重播遷移命令。對相同的帳戶和資料庫 UUID 執行 emdash migrate --status，檢查結果，如果遷移中途停止則升級處理。
• Hyperdrive 無法連線。 測試從部署執行器到 PostgreSQL 來源的可達性，並驗證直接來源變數。Worker 到 Hyperdrive 的連線性不能證明執行器可以到達來源。