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

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

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

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

使用 CLI 部署 Data Connect 服務時，系統會遷移 SQL 結構定義、更新 Data Connect 結構定義，然後更新每個連接器。

重要部署概念

如要充分瞭解部署作業，請務必注意有關結構定義和連接器的重要概念。

結構定義部署作業

部署 Data Connect 架構會影響 Cloud SQL 資料庫的 SQL 架構。Data Connect 可協助您在部署期間遷移結構定義，無論您是使用新資料庫，還是需要以非破壞性方式調整現有資料庫，都能派上用場。

Data Connect 架構遷移有兩種不同的架構驗證模式：strict 和 compatible。

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

  • 如要進行相容模式驗證，資料庫結構定義必須相容於應用程式結構定義，才能更新應用程式結構定義；您也可以選擇進行其他變更，例如捨棄結構定義、資料表或資料欄。

    相容表示結構定義遷移只會影響應用程式結構定義中參照的資料表和資料欄。資料庫中應用程式結構定義未使用的元素不會修改。因此，部署後資料庫可能包含未使用的：

    • 結構定義
    • 表格
    • 欄

連接器部署作業

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

Data Connect 會將連接器更新中的重大變更分析整合至 Firebase CLI。

CLI 會分析每個連接器相對於架構的變更，並針對可能改變用戶端行為 (警告層級訊息) 或可能或將會中斷 (中斷層級訊息) 先前版本用戶端程式碼的連接器變更，發布一組評估訊息。

例如：

  • 如果從查詢中移除可為空值的欄位，且沒有 @retired 結構定義註解，就可能改變用戶端行為。
  • 如果連接器變更可能或將會導致用戶端中斷，包括將可為空值的作業變數變更為非空值 (沒有預設值)，或是將欄位的資料型別變更為不相容的型別 (例如 String 變更為 Int)。

如需更詳盡的警告層級和破壞性層級情境清單，請參閱 CLI 參考指南。

按照部署工作流程操作

您可以在本機專案目錄和 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 會嘗試部署結構定義和連接器。

並驗證新結構定義不會中斷任何現有連線。進行重大變更時，請遵循最佳做法。

此外，系統也會先驗證 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

復原部署作業

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

遷移資料庫結構定義

如果您正在快速製作原型、實驗結構定義，且知道結構定義變更會造成破壞性影響，可以規劃使用 Data Connect 工具驗證變更，並監督更新的執行方式。

比較 SQL 結構定義變更

你可以驗證變更：

firebase dataconnect:sql:diff

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

這項指令會比較服務的本機結構定義與對應 Cloud SQL 資料庫的目前結構定義。如有差異，系統會列印出用來修正差異的 SQL 指令

套用變更

確認無誤後，即可發出 firebase dataconnect:sql:migrate 指令，將變更部署至結構定義 Cloud SQL 執行個體。系統會提示你核准變更。

firebase dataconnect:sql:migrate [serviceId]

在互動式環境中，系統會顯示 SQL 遷移陳述式和動作提示。

以嚴格或相容模式遷移

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

如要調整這項行為，請修改 dataconnect.yaml 檔案。取消註解 schemaValidation 鍵，並宣告 COMPATIBLE，這樣在遷移時只會套用必要變更。

schemaValidation: "COMPATIBLE"

或者，將行為設為 STRICT，這樣系統就會套用所有結構定義變更，並強制資料庫結構定義與應用程式結構定義相符。

schemaValidation: "STRICT"

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

可更新連接器

執行 firebase deploy 時，CLI 會啟動適用連接器的更新，並發布適用的警告層級 (可能影響用戶端行為) 和重大層級 (可能或一定會中斷) 評估訊息。

使用 CLI 管理連結器更新

CLI 在互動模式和非互動模式下的行為略有不同。

如您所料，在互動模式下，CLI 會提示您接受所有訊息。您可以使用 --force 旗標覆寫並強制部署連接器。

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

在非互動模式中，只要沒有中斷層級的評估，CLI 就會部署連接器。否則，指令碼會結束並記錄重大變更。您可以設定 --force 旗標來覆寫及部署。

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

詳情請參閱 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 限制，以便透過您定義的連接器將資料新增至表格。

後續步驟