部署及管理 Data Connect 結構定義和連接器

Firebase Data Connect 服務有三個主要元件：

  • 具有專屬 SQL 結構定義的基礎 PostgreSQL 資料庫
  • Data Connect 應用程式結構定義 (在 .gql 檔案中宣告)
  • 多個連接器 (在 .gql 檔案中宣告)。

SQL 結構定義是資料的真實來源，Data Connect 結構定義是連接器可查看該資料的方式，而連接器會宣告用戶端可用來存取該資料的 API。

使用 CLI 部署 Data Connect 服務時，您會先遷移 SQL 結構定義，然後更新 Data Connect 結構定義，最後更新各個連接器。

重要部署概念

如要全面瞭解部署作業，請務必留意 結構定義和連接器

結構定義部署項目

部署 Data Connect 結構定義會影響 Cloud SQL 資料庫的 SQL 結構定義。Data Connect 可協助您遷移結構定義 部署這個資料庫，無論您使用的是新的資料庫 以非破壞性的方式調整現有資料庫

Data Connect 結構定義遷移作業有兩項不同的結構定義驗證 模式：嚴格和相容模式。

  • 在嚴格模式驗證中，資料庫結構定義必須「完全」符合應用程式結構定義，應用程式結構定義才能更新。系統會從資料庫中刪除未在 Data Connect 結構定義中使用的任何資料表或資料欄。

  • 相容模式驗證要求資料庫結構定義必須與應用程式結構定義「相容」，應用程式結構定義才能更新；任何會刪除結構定義、資料表或欄位的額外變更都是選用的。

    相容表示結構定義遷移作業只會影響應用程式結構定義中參照的資料表和欄。資料庫中未受應用程式結構定義影響的元素，將維持不變。因此，在這之後 則資料庫可能包含未使用的：

    • 結構定義
    • 資料表
    • 欄
，瞭解如何調查及移除這項存取權。

連接器部署

Data Connect 查詢和變異不會由用戶端程式碼提交，也不會在伺服器上執行。不過在部署時 這些 Data Connect 作業會儲存在伺服器上 Cloud Functions。也就是說，部署作業可能會導致現有使用者無法正常使用。

按照部署工作流程進行

您可以同時處理本機專案中的 Data Connect 專案 目錄和 Firebase 控制台中。

以下是建議的部署流程：

  1. 使用 firebase dataconnect:services:list 列出目前已部署的結構定義和連接器。
  2. 管理任何結構定義更新。
    1. 使用 firebase dataconnect:sql:diff 檢查 Cloud SQL 資料庫和本機 Data Connect 結構定義之間的 SQL 結構定義差異。
    2. 視需要使用 dataconnect:sql:migrate 執行 SQL 結構定義遷移作業。
  3. 執行 firebase deploy 來執行結構定義和連結部署作業，可針對結構定義、連接器或資源組合執行。

部署及管理 Data Connect 資源

建議您在執行部署作業前，先驗證實際工作環境資源。

firebase dataconnect:services:list

在本機專案目錄中工作時，您通常會使用 firebase deploy 指令，將結構定義和連接器部署至實際工作環境。 提供互動式意見回饋

使用任何 deploy 指令時，--only dataconnect 旗標可讓您區隔 您專案中其他產品的 Data Connect 項部署作業。

一般部署

firebase deploy --only dataconnect

在這個一般部署作業中，Firebase CLI 會嘗試部署結構定義和連接器。

它會驗證新的結構定義不會中斷任何現有的連接器。 進行破壞性變更時，請遵循最佳做法。

並在更新 SQL 結構定義前，驗證 SQL 結構定義是否已遷移。 Data Connect 結構定義。如果沒有，系統會自動提示您選擇 遷移結構定義的必要步驟。

--force 旗標部署

firebase deploy --only dataconnect --force

如果您不想進行連接器或 SQL 結構定義驗證，可以使用 --force 重新執行指令，以便略過這些驗證。

--force 部署作業仍會檢查 SQL 結構定義是否與 Data Connect 結構定義相符，並在相容性不佳時發出警告和提示。

部署所選資源

如要以更精細的控制方式進行部署，請使用 --only 旗標搭配 serviceId 引數。如要只部署特定服務的結構定義變更：

firebase deploy --only dataconnect:serviceId:schema

您也可以為指定的連接器和服務部署所有資源。

firebase deploy --only dataconnect:serviceId:connectorId

最後，您可以為單一服務部署結構定義和所有連接器。

firebase deploy --only dataconnect:serviceId

復原部署項目

如要執行手動復原作業，請查看舊版程式碼， 並部署 Kubernetes如果原始部署作業包含破壞性的重大變更，您可能無法完全復原任何已刪除的資料。

遷移資料庫結構定義

如果您正在快速設計原型、透過結構定義進行實驗並瞭解結構定義 但您可以規劃使用 Data Connect 工具 確認變更並監督更新方式。

比較 SQL 結構定義變更

您可以驗證變更：

firebase dataconnect:sql:diff

您可以傳遞以半形逗號分隔的服務清單。

這個指令會將服務的本機結構定義與對應 Cloud SQL 資料庫的目前結構定義進行比較。差異點則會先輸出 為修正該差異而執行的 SQL 指令

套用變更

確認一切都符合需求，且準備好將變更部署至結構定義 Cloud SQL 執行個體時，請發出 firebase dataconnect:sql:migrate 指令。系統會提示您核准變更。

firebase dataconnect:sql:migrate [serviceId]

在互動式環境中，SQL 遷移陳述式和動作提示 高度。

以嚴格或相容模式遷移

在全新專案中，預設的結構定義驗證模式 migrate 指令的行為是套用應用程式結構定義所需的所有資料庫結構定義變更，然後提示您核准會刪除結構定義、資料表或資料欄的選用作業，以便強制資料庫結構定義與應用程式結構定義完全相符。

您可以修改 dataconnect.yaml 檔案來調整這個行為。 取消 schemaValidation 鍵的註解並宣告 COMPATIBLE， 必要的變更都會套用到遷移作業。

schemaValidation: "COMPATIBLE"

您也可以將行為設為 STRICT，以套用所有結構定義變更，並 強制資料庫結構定義與應用程式結構定義相符。

schemaValidation: "STRICT"

詳情請參閱 Data Connect CLI 參考資料。

管理結構定義和連接器的最佳做法

Firebase 建議您在 Data Connect 專案中遵循一些做法。

盡量減少破壞性變更

  • Firebase 建議保留「Data Connect」的結構定義和連接器 檔案位於原始碼控管系統中
  • 盡量避免破壞性變更。一些常見的破壞性示例 變更包括：
    • 從結構定義中移除欄位
    • 在結構定義中將可為空值的欄位設為不可為空值 (例如 Int -> Int!)
    • 重新命名結構定義中的欄位。
  • 如果確實需要從結構定義中移除欄位，建議您拆分該欄位 並部署至幾個部署項目，以盡可能降低影響：
    • 首先，請移除連接器中任何欄位的參照，然後進行部署 相關變更
    • 接著請更新應用程式，改用新產生的 SDK。
    • 最後，移除結構定義 .gql 檔案中的欄位，然後遷移 SQL 檔案 並再次部署

使用新資料庫時採用嚴格模式

如果您正在透過新的資料庫使用 Data Connect，並經常使用 開發應用程式結構定義，而且您想確保資料庫結構定義 必須與應用程式結構定義一致 「dataconnect.yaml」中的「schemaValidation: "STRICT"」。

如此可確保系統一併套用選擇性的變更。

如果資料庫內有正式環境資料，請使用相容模式

如果要變更包含正式環境資料的資料庫 建議您在相容模式下執行結構定義遷移作業，確保 但不會捨棄現有資料您可以在 dataconnect.yaml 中指定 schemaValidation: "COMPATIBLE"

在相容模式下，系統只會將必要的結構定義遷移變更套用至您的 資料庫

  • DROP SCHEMA、DROP TABLE 和 DROP COLUMN 視為選用陳述式，因此即使資料庫架構包含應用程式架構中未定義的架構、資料表或欄，也不會為您的計畫產生這些陳述式。
  • 如果資料庫資料表包含非空值資料欄，但應用程式結構定義中未包含該資料欄，系統會移除 NOT NULL 限制，以便透過定義的連接器將資料新增至資料表。

後續步驟