透過使用 rayfin up 或 rayfin up db apply，對資料庫施加 Rayfin 實體變更，並驗證結構是否已到達伺服器。
編輯類別 rayfin/data/ 本身不會改變已部署的資料庫。 Rayfin 只有在你明確套用這些變更時，才會讀取你的實體並產生資料 API 建構器（DAB）設定。
使用 rayfin up 進行應用程式更新
每當你想部署最新的實體變更到 Fabric 應用程式時，即可執行npx rayfin up：
npx rayfin up
此命令：
- 同步執行時設定。
- 套用由
rayfin/data/中的裝飾器產生的資料庫結構描述。 - 啟用時
staticHosting會建置並部署靜態內容。
每次變更 rayfin/data/ 中的檔案後，都請執行該指令。 第一次部署後，後續執行會更新同一部署，而非建立新的部署。
僅套用資料庫架構變更
當你想套用資料庫結構而不同步執行時設定或部署靜態內容時，請使用 npx rayfin up db apply ：
npx rayfin up db apply
當你使用 npm run dev 執行前端、後端已部署完成，並且想要獨立迭代結構描述時，這個進階子指令會很有用。
若變更可能導致資料遺失，例如刪除欄位或重新命名資料表，CLI 會阻擋該操作並描述可能的影響。 在您檢閱這些作業並接受資料遺失後，請使用 --force 套用變更：
npx rayfin up db apply --force
Caution
這個 --force 選項可能會導致永久性的資料遺失。 只有在你審查 CLI 報告的每一個操作後才使用。
驗證已部署的架構
Warning
成功 rayfin up 或 rayfin up db apply 指令並不保證你的前端能立即查詢新的或變更的實體。 在測試實體之前，請先確認部署狀態良好。
在任何變動 rayfin/data/後，請檢查部署狀況：
npx rayfin up status
如果部署恢復正常後，新的或變更的實體仍回傳 GraphQL 錯誤，請明確套用該結構，然後再次測試該實體：
npx rayfin up db apply
只有在 CLI 顯示可能造成破壞的變更，且你接受資料遺失時，才新增 --force。
若要取得機器可讀的部署狀態，請使用 JSON 輸出：
npx rayfin up status --json
你可以在指令碼中使用 JSON 回應，等待部署進入健康狀態後，再執行進一步的檢查。
遵循典型的結構工作流程
# 1. Edit an entity, such as rayfin/data/Todo.ts.
# 2. Apply the application changes.
npx rayfin up
# 3. Verify that the deployment is healthy.
npx rayfin up status
# 4. If the changed entity still fails, apply the schema explicitly.
npx rayfin up db apply
如果步驟 4 顯示可能具有破壞性的操作，請先檢查該操作，然後再使用 --force 重新執行該命令。
排除結構變更
GraphQL 會回傳內部伺服器錯誤
檢查受影響實體的每個 @text() 欄位是否有遺失 max 值。 使用 Microsoft SQL Server 時，NVARCHAR(MAX) 若沒有 @text()，就會產生 max 欄位，這可能會導致無法產生 GraphQL 結構描述。
新增明確的最大長度，然後套用該結構：
@text({ max: 200 })
title!: string;
npx rayfin up db apply --force
使用 --force 之前，請先檢視已回報的作業。
CLI 回報了一項可能造成破壞的變更
檢視列出的作業，包括已刪除的欄位、已縮小的型別，以及已重新命名的資料表。 只有在您確認可以接受資料遺失後，才使用 --force 重新執行該指令。
結構描述套用失敗
執行 npx rayfin up status，等服務恢復正常後再嘗試套用結構。
該資料服務沒有方言
當 services.data.enabled 為 true 時，請在 rayfin/rayfin.yml 中設定 dialect: mssql。
services:
data:
enabled: true
dialect: mssql
使用 AI 提示
請將以下提示複製到 GitHub Copilot 或其他有權限存取你專案和終端機的程式代理程式中：
I just added a new field to an entity in my Rayfin project's rayfin/data/ folder. Run
`npx rayfin up` to apply the change, then run `npx rayfin up status` to confirm the
deployment is healthy. If querying the changed entity still fails after that, run
`npx rayfin up db apply` and check again. Review any potentially destructive operations with me before using `--force`.