Fabric Data Warehouse 的部署前與部署後腳本（預覽版）

適用於：Microsoft Fabric 中的✅ 資料庫

Important

這項功能目前處於預覽階段。

部署前與部署後的腳本讓您能在Fabric部署倉庫時執行自訂 Transact-SQL 指令。 使用部署前與部署後的指令碼來清理資料、植入參考資料，或套用未在資料倉儲結構描述中表達的 SQL 安全性設定。

在Fabric Data Warehouse中，部署前或部署後腳本是一種共享的 SQL 查詢。 你可以在 SQL 資料庫專案中撰寫這些腳本，並從 Fabric 入口網站指定它們。 此指定會以倉儲層級中繼資料的形式儲存，並作為倉儲 .sqlproj 檔案的一部分提交到原始碼控制，因此可透過 Git 和部署管線來回傳遞，而無須手動重新套用。

本文說明什麼是部署前與部署後腳本，如何在 Fabric 入口中設定它們，它們如何與版本控制及部署管線互動，以及如何在 Visual Studio Code 和 SQL Server Management Studio（SSMS）中撰寫這些腳本。

Important

發佈前務必檢視部署腳本和設定。 先在開發和測試環境中測試，以防止意外的資料遺失。

什麼是部署前和部署後的腳本？

當你將工作區連接到原始碼控制時，每個倉庫會以 SQL 資料庫專案的形式出現：一個由原始碼控制的腳本，包含構成倉庫結構的 SQL 物件（資料表、視圖、儲存程序和函式）。 每個物件都儲存為 .sql 包含其資料定義語言（DDL）語法的檔案，例如 CREATE TABLE。 物件描述 結構的期望狀態 ，部署過程會將該期望狀態與目標倉儲比較，並產生差異化的 T-SQL 腳本，建立、修改或丟棄物件，使目標與專案相符。

部署前與部署後腳本會以圍繞結構部署的 Transact-SQL 來擴展此流程：

  • 在套用架構部署計畫之前，會先執行一個預部署腳本。
  • 部署後的腳本會在結構部署計畫完成後執行。

部署前或部署後腳本是儲存在倉庫 Queries 資料夾下的共享查詢之一。 倉庫最多支援一個部署前腳本和一個部署後腳本。 指定以倉庫層級的元資料形式儲存，而非重複腳本內容，因此對儲存負擔幾乎可以忽略不計。

因為每個指定的腳本每次倉庫部署時都會執行，請將 Transact-SQL 設計成冪元（安全可反覆執行）。

Tip

當指令碼是冪等的時候，你可以多次執行它，也不會造成問題。 你可以部署到多個資料庫，無需預先設定它們的狀態。

常見使用案例

  • 參考與靜態資料管理：架構部署後，從查找、設定或參考表中插入、更新或刪除資料列。
  • 資料清理：在套用結構變更前後移除過時或暫時的資料。
  • 環境設定：套用設定或初始化狀態，使其在開發、測試與生產環境間有所不同。
  • 中繼資料驅動的管線初始化：準備下游管線步驟所需的資料倉儲狀態。
  • SQL 安全性：儲存資料表資料及 SQL 安全功能如角色、使用者與 GRANT/DENY 權限未包含在 SQL 資料庫專案中。 部署後使用後置腳本重新建立這些物件，包括測試環境與生產環境的差異。 範例請參見 SQL 安全性的部署後腳本範例。

SQL 專案檔案結構與語法

倉庫 SQL 專案會參考專案檔案中的.sqlproj部署前與部署後腳本（），透過使用 PreDeploy 和 PostDeploy 項目類型。 每個條目指向專案中單一共享的查詢檔。

以下範例分別 pre-deployment.sql 標示為部署前腳本及 post-deployment.sql 部署後腳本：

<ItemGroup>
  <PreDeploy Include="pre-deployment.sql" />
  <PostDeploy Include="post-deployment.sql" />
</ItemGroup>

Important

Fabric Data Warehouse 僅支援一個檔案用於部署前腳本，一個檔案用於部署後腳本。 不支援從多個檔案組合腳本——例如使用 SQLCMD :r 指令來參考其他檔案——。 如果 包含 .sqlproj 多個部署前或部署後的項目，Git 更新將失敗。

SQL 安全性的部署後指令碼範例

由於 SQL 安全功能未被 SQL 資料庫專案捕捉，部署後的腳本是倉庫部署後重建安全功能的常見方式。 寫腳本讓它能在每次部署中執行。

以下範例會建立一個名為 DataReaders 的自訂資料庫角色，並將 SELECT 權限授與 dbo 結構描述。

-- post-deployment.sql
-- Recreate a role and grant permissions after deployment.
IF NOT EXISTS (SELECT 1 FROM sys.database_principals WHERE name = N'DataReaders')
BEGIN
    CREATE ROLE DataReaders;
END;
GO

GRANT SELECT ON SCHEMA::dbo TO DataReaders;
GO

Note

Fabric Data Warehouse 並不支援 SQL Server 中所有可用的Transact-SQL 語句。 確保你腳本中的陳述有Fabric Data Warehouse支持。

在 Fabric 入口網站中設定部署前與部署後的腳本

在 Fabric 入口網站中，將現有的共享查詢指定為部署前或部署後的腳本。 你可以從 物件總管 或倉庫物品的設定中操作。

你不能同時指定一個共享查詢作為部署前和部署後的腳本。

摘自 物件總管

  1. 在倉庫編輯器中，展開 物件總管 中的 Queries 資料夾。
  2. 右鍵點擊你想使用的共享查詢。
    • 如有必要，將查詢從 「我的查詢 」移到共享查詢。
  3. 選擇 設定部署腳本。 這個動作會帶你進入物品設定欄。
  4. 在 部署前腳本 與 部署後腳本 欄位中，選擇 「選擇腳本」。
  5. 選擇「 設定查詢作為部署前後的腳本 」選項，然後為每個腳本選擇共用查詢。 每個下拉選單都會列出倉庫中所有共用的查詢。

來自物品設定

  1. 打開倉庫 的設定。
  2. 請前往 CI/CD 區塊。
  3. 在 部署前腳本 與 部署後腳本 欄位中，選擇 「選擇腳本」。
  4. 選擇「 設定查詢作為部署前後的腳本 」選項，然後為每個腳本選擇共用查詢。 每個下拉選單都會列出倉庫中所有共用的查詢。

你所做的選擇會以倉庫層級的元資料儲存，並且在 物件總管 與項目設定之間同步。

部署前與部署後指令碼在部署期間的行為

與 Git 整合

當你將工作空間連接到 Git 倉庫時，部署前與部署後的指定會在提交時序列化到倉庫 .sqlproj 檔案中。 當你從 Git 更新倉庫時，Fabric 會將變更套用到現場倉庫，並依序執行腳本：

  1. 部署前腳本會在架構變更被套用前執行。
  2. 架構部署計畫會被套用。
  3. 部署後的腳本會在結構變更完成後執行。

定義可透過 Git 來回同步：在入口網站中設定腳本並將其提交，或在 .sqlproj 中撰寫並更新工作區，都會得到一致的結果。 重複提交和更新不會重複或遺失設定。 由於只允許一個部署前腳本和一個部署後腳本，因此在更新時，Git 所撰寫的設定會替換倉庫中現有的指定。

Note

部署前與部署後的腳本需要最新的版本控制經驗，才能完整支援 Git 工作流程。 在尚未升級的工作區中，部署腳本的元資料不會與原始碼控制同步，部署腳本也不會參與基於 Git 的工作流程。

此限制僅適用於 Git 工作流程，並非部署流程（ALM）的前提條件。

搭配部署管線

部署管線在將倉儲提升至 開發、測試 和 生產 階段時，會使用部署前和部署後標示。 指定的腳本會在每個目標環境中以確定性方式執行，因此你可以用它們來套用環境設定，或在內容在各階段間移動時重新套用 SQL 安全性。

在沒有來源控制的工作區中

倉儲項目定義包含部署前和部署後的標示，即使工作區未連線到來源控制也是如此。 匯出倉庫會包含設定，匯入則會完整還原設定。

在 SQL 資料庫專案中撰寫部署前與部署後的腳本

你可以不使用 Fabric 入口網站，而是透過 Visual Studio Code 的 SQL Database Projects 擴充功能，或 SQL Server Management Studio 中的整合式 SQL 專案體驗，直接在倉庫的 SQL 資料庫專案中撰寫部署前與部署後指令碼。 設定會在下一次 Git 更新後，出現在 Fabric 入口網站的 物件總管 和物品設定中。

Visual Studio Code

  1. 在 Visual Studio Code 安裝 SQL 資料庫專案擴充功能。
  2. 打開你倉庫的 SQL 資料庫專案。 如果你的工作區已連接至 Git，請先複製儲存庫，然後開啟 Warehouse 專案資料夾。
  3. 在 資料庫專案 檢視中，右鍵點擊專案節點，選擇 「新增部署前腳本 」或 「新增部署後腳本」。
  4. 提供不含副檔名的指令碼名稱。 腳本檔案會被加入專案並在編輯器中開啟。
  5. 把你的 Transact-SQL 加入腳本並儲存檔案。 確保檔案已儲存在下一次 Git 更新時的 .sharedqueries 資料夾中。
  6. 提交並推送變更到你的 Git 倉庫，然後從原始碼控制更新工作區來套用設定。

SQL Server Management Studio

  1. 使用 SQL Server Management Studio 22 或更新版本，其中包含 SQL 資料庫專案體驗。
  2. 打開你倉庫的 SQL 資料庫專案。
  3. 在 方案總管 中，右鍵點擊專案節點並選擇新增>腳本。 選取 [預先部署指令碼] 或 [部署後指令碼]。
  4. 腳本檔案會被加入專案，並在查詢編輯器中開啟。
  5. 把你的 Transact-SQL 加入腳本並儲存檔案。 記得把檔案存到 .sharedqueries 資料夾裡，等下次 Git 更新時再用。
  6. 提交並推送變更到你的 Git 倉庫，然後從原始碼控制更新工作區來套用設定。

直接編輯專案檔案

在任何工具中，你都可以藉由編輯 .sqlproj 檔案，並將單一 PreDeploy 或 PostDeploy 項目新增至 ItemGroup，來指定指令碼：

<ItemGroup>
  <PreDeploy Include="./sharedqueries/pre-deployment.sql" />
  <PostDeploy Include="./sharedqueries/post-deployment.sql" />
</ItemGroup>

從現有 SQL 專案遷移

如果您從 SQL Server Data Tools (SSDT) 或 Visual Studio 移轉已包含 <PostDeploy> 和 .sqlproj 項目的 <PreDeploy>，匯入程序會辨識這些項目，並將其對應至 Fabric 的部署前與部署後組態。 由於 Fabric 只支援一個部署前腳本和一個部署後腳本，請確保專案在匯入前最多包含每種類型的一個項目。

考慮事項與限制條件

  • 倉庫僅支援一個部署前腳本和一個部署後腳本。 它不支援每個腳本對應多個檔案。
  • 你不能同時指定同一個共享查詢作為部署前和部署後的腳本。
  • 如果你刪除被指定為部署前或部署後腳本的共享查詢，該指定會自動被清除。
  • 如果你將一個被指定為部署前或部署後腳本的共享查詢改成使用者查詢，對應的指定會自動被清除。
  • 每次進行倉儲部署時，都會執行部署前與部署後的指令碼。 Transact-SQL 腳本應該是冪等的，這樣重複執行時才不會失敗或產生重複物件。
  • 部署前和部署後的腳本在建置時不會與資料庫模型進行驗證。 腳本錯誤會在部署時出現，若腳本失敗，部署會中止。
  • 你只能使用Fabric Data Warehouse支援的Transact-SQL。
  • 執行部署的身份必須擁有執行腳本內容所需的權限。

相關內容

  • Last updated on