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

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

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

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

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

重要部署概念

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

結構定義部署作業

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

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

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

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

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

    • 結構定義
    • 資料表
    • 欄

連接器部署作業

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

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

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

例如：

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

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

按照部署工作流程操作

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

建議的部署流程包括：

  1. 使用 firebase dataconnect:services:list 列出目前部署的結構定義和連接器。
  2. 管理任何結構定義更新。
    1. 使用 firebase dataconnect:sql:diff 檢查資料庫和本機結構定義之間的 SQL 結構定義差異。Cloud SQLSQL Connect
    2. 視需要使用 dataconnect:sql:migrate 執行 SQL 結構定義遷移作業。
  3. 執行 firebase deploy，部署結構定義和連線，可選擇只部署結構定義、只部署連接器，或同時部署兩者。

部署及管理 SQL Connect 資源

建議您先驗證正式環境資源，再執行部署作業。

firebase dataconnect:services:list

在本地專案目錄中工作時，您通常會使用 firebase deploy 指令將結構定義和連接器部署到正式環境，並取得互動式意見回饋。

使用任何 deploy 指令時，--only dataconnect 旗標可讓您將部署作業與專案中的其他產品分開。SQL Connect

正常部署

firebase deploy --only dataconnect

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

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

此外，系統也會先驗證 SQL 結構定義是否已遷移，再更新 SQL Connect 結構定義。如果沒有，系統會自動提示您完成遷移結構定義的所有必要步驟。

--force 個旗標部署項目

firebase deploy --only dataconnect --force

如果連接器或 SQL 結構定義驗證都不是問題，可以重新執行指令並加上 --force，忽略這些驗證。

--force 部署作業仍會檢查 SQL 結構定義是否與 SQL Connect 結構定義相符、警告不相容問題，並提示。

部署所選資源

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

復原部署作業

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

遷移資料庫結構定義

如果您正在快速製作原型、實驗結構定義，且知道結構定義變更會造成破壞性影響，可以規劃使用 SQL 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"

詳情請參閱 SQL 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 建議您在SQL Connect專案中遵循某些做法。

盡量減少破壞性變更

  • Firebase 建議將SQL Connect結構定義和連接器檔案保留在原始碼控管中。
  • 請盡可能避免破壞性變更。以下列舉一些常見的重大變更：
    • 從結構定義中移除欄位
    • 將架構中的可為空值欄位設為不可為空值 (即 Int -> Int!)
    • 重新命名結構定義中的欄位。
  • 如果確實需要從結構定義中移除欄位，請考慮將結構定義分成幾個部署作業，盡量減少影響：
    • 請先移除連接器中對該欄位的所有參照，然後部署變更。
    • 接著，請更新應用程式，改用新產生的 SDK。
    • 最後，請移除結構定義 .gql 檔案中的欄位、遷移 SQL 結構定義，然後再次部署。

處理新資料庫時使用嚴格模式

如果您使用 SQL Connect 搭配新資料庫，並積極開發應用程式結構定義，且想確保資料庫結構定義與應用程式結構定義完全一致，可以在 dataconnect.yaml 中指定 schemaValidation: "STRICT"。

這樣系統也會套用選用變更。

資料庫中有實際工作環境資料時，請使用相容模式

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

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

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

後續步驟