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

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

  • 底層 PostgreSQL 資料庫，以及其專屬的 SQL 結構定義
  • 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。也就是說，部署作業可能會導致現有使用者無法正常使用。

按照部署工作流程操作

您可以在本機專案目錄和 Firebase 主控台中處理 Data Connect 專案。

建議的部署流程包括：

  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 會嘗試部署結構定義和連接器。

驗證新結構定義不會影響任何現有連接器。進行重大變更時，請遵循最佳做法。

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

--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

復原部署項目

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

遷移資料庫結構定義

如果您要快速製作原型、嘗試使用結構定義，且知道結構定義變更會造成破壞性影響，可以使用 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 限制，以便透過定義的連接器將資料新增至資料表。

後續步驟