Fabric Data Warehouse (プレビュー) のデプロイ前およびデプロイ後のスクリプト

適用対象:✅ Warehouse in Microsoft Fabric

デプロイ前スクリプトとデプロイ後スクリプトを使用すると、Fabricにウェアハウスをデプロイする一環として、カスタム Transact-SQL コマンドを実行できます。 デプロイ前およびデプロイ後のスクリプトを使用して、データのクリーンアップ、参照データのシード処理、またはウェアハウスのスキーマで表されていない SQL セキュリティの適用を行います。

Fabric Data Warehouseでは、デプロイ前または配置後のスクリプトは共有 SQL クエリです。 これらのスクリプトは、SQL データベース プロジェクトで作成し、Fabric ポータルから指定できます。 この指定は、ウェアハウス レベルのメタデータとして格納され、ウェアハウスの .sqlproj ファイルの一部としてソース管理にコミットされるため、手動で再適用することなく、Git とデプロイ パイプラインをラウンドトリップします。

この記事では、デプロイ前およびデプロイ後のスクリプトの概要、Fabric ポータルでスクリプトを構成する方法、ソース管理パイプラインとデプロイ パイプラインでの動作方法、および Visual Studio Code および SQL Server Management Studio (SSMS) でそれらを作成する方法について説明します。

デプロイ前スクリプトと配置後スクリプトとは

ワークスペースをソース管理に接続すると、各ウェアハウスは SQL データベース プロジェクトとして表されます。これは、ウェアハウス スキーマ (テーブル、ビュー、ストアド プロシージャ、関数) を構成する SQL オブジェクトのソース管理スクリプトです。 各オブジェクトは、.sqlなどのデータ定義言語 (DDL) 構文を含むCREATE TABLE ファイルとして格納されます。 オブジェクトはスキーマの 目的の状態 を記述し、配置プロセスはその目的の状態をターゲット ウェアハウスと比較し、ターゲットがプロジェクトと一致するようにオブジェクトを作成、変更、または削除する差分 T-SQL スクリプトを生成します。

デプロイ前スクリプトとデプロイ後スクリプトは、スキーマのデプロイを中心に実行される Transact-SQL を使用して、このプロセスを拡張します。

• スキーマ配置計画が適用される前に、デプロイ前スクリプトが実行されます。
• デプロイ後のスクリプトは、スキーマデプロイ計画の完了後に実行されます。

デプロイ前またはデプロイ後のスクリプトは、ウェアハウスの Queries フォルダーに格納されている共有クエリの 1 つです。 1 つのウェアハウスでは、デプロイ前スクリプトとデプロイ後スクリプトが最大 1 つサポートされます。 この指定は、スクリプト コンテンツを複製するのではなく、ウェアハウス レベルのメタデータとして格納されるため、わずかなストレージ オーバーヘッドが追加されます。

指定された各スクリプトは、ウェアハウスがデプロイされるたびに実行されるため、Transact-SQL はべき等になるように作成してください（繰り返し実行しても安全）。

一般的なユース ケース

• 参照および静的データ管理: スキーマのデプロイ後に、参照テーブル、構成テーブル、または参照テーブルから行を挿入、更新、または削除します。
• データのクリーンアップ: スキーマの変更が適用される前または後に、古いデータまたは一時データを削除します。
• 環境のセットアップ: 開発環境、テスト環境、運用環境で異なる設定を適用するか、状態を初期化します。
• メタデータドリブン パイプラインの初期化: ダウンストリーム パイプラインの手順で必要なウェアハウスの状態を準備します。
• SQL セキュリティ: ロール、ユーザー、 GRANT/DENY のアクセス許可などのウェアハウス テーブル データと SQL セキュリティ機能は、SQL データベース プロジェクトには含まれません。 デプロイ後のスクリプトを使用して、テスト環境と運用環境の違いなど、デプロイ後にこれらのオブジェクトを再作成します。 例については、 SQL セキュリティのデプロイ後スクリプトの例を参照してください。

SQL プロジェクト ファイルの構造と構文

ウェアハウス SQL プロジェクトは、プロジェクト ファイル (.sqlproj) 内の配置前スクリプトと配置後スクリプトを、 PreDeploy と PostDeploy 項目の種類と共に参照します。 各エントリは、プロジェクト内の 1 つの共有クエリ ファイルを指します。

次の例では、 pre-deployment.sql をデプロイ前スクリプトとして指定し、 post-deployment.sql を配置後スクリプトとして指定します。

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

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

Fabric ポータルでデプロイ前と配置後のスクリプトを構成する

Fabric ポータルで、既存の共有クエリをデプロイ前または配置後スクリプトとして指定します。 これは、オブジェクト エクスプローラーまたは倉庫アイテムの設定から行うことができます。

共有クエリをデプロイ前スクリプトと配置後スクリプトの両方として同時に指定することはできません。

オブジェクト エクスプローラーから

1. ウェアハウス エディターで、オブジェクト エクスプローラーの [クエリ] フォルダーを展開します。
2. 使用する共有クエリを右クリックします。
3. [ デプロイ スクリプトの設定] を選択します。 この操作により、アイテム設定ウィンドウに移動します。

アイテムの設定から

1. 倉庫の 品目設定を開きます。
2. CI-CD セクションに移動します。
3. デプロイ前スクリプトと配置後スクリプトのドロップダウンを使用して、それぞれに対する共有クエリを選択します。 各ドロップダウンには、ウェアハウス内のすべての共有クエリと、指定を未設定のままにする (なし) オプションが一覧表示されます。

選択した内容は、倉庫レベルのメタデータとして保存され、オブジェクト エクスプローラーと項目の設定の間で同期されます。

デプロイ前スクリプトと配置後スクリプトのデプロイでの動作

Git 統合を使用する

ワークスペースを Git リポジトリに接続すると、デプロイ前とデプロイ後の指定がコミット時にウェアハウスの .sqlproj ファイルにシリアル化されます。 Git からウェアハウスを更新すると、Fabricは変更をライブ ウェアハウスに適用し、次の順序でスクリプトを実行します。

1. デプロイ前スクリプトは、スキーマの変更が適用される前に実行されます。
2. スキーマ展開計画が適用されます。
3. デプロイ後スクリプトは、スキーマの変更が完了した後に実行されます。

Git を使用したラウンドトリップの指定: ポータルでスクリプトを構成してコミットするか、 .sqlproj で作成してワークスペースを更新すると、一貫した結果が得られます。 コミットと更新を繰り返しても、構成が重複したり失われることはありません。 許可されるデプロイ前スクリプトとデプロイ後スクリプトは 1 つだけであるため、Git で作成された構成によって、更新時にウェアハウス内の既存の指定が置き換えられます。

デプロイ パイプラインを使用する

デプロイ パイプラインは、 開発、 テスト、 運用 の各段階で倉庫を昇格する際に、デプロイ前とデプロイ後の指定を行います。 指定されたスクリプトは、各ターゲット環境で確定的に実行されるため、それらを使用して環境のセットアップを適用したり、コンテンツがステージ間を移動するときに SQL セキュリティを再適用したりできます。

ソース管理のないワークスペース内

ウェアハウス項目定義には、ワークスペースがソース管理に接続されていない場合でも、デプロイ前とデプロイ後の指定が含まれます。 ウェアハウスのエクスポートには構成が含まれており、インポートすると構成はそのまま復元されます。

SQL データベース プロジェクトで配置前スクリプトと配置後スクリプトを作成する

Fabric ポータルの代わりに、Visual Studio Codeの SQL Database Projects 拡張機能または SQL Server Management Studio の統合 SQL プロジェクト エクスペリエンスを使用して、ウェアハウスの SQL データベース プロジェクトに配置前および配置後のスクリプトを直接作成できます。 構成は、Fabric ポータル (オブジェクト エクスプローラー と項目の設定の両方) で、次の Git 更新の後に表示されます。

Visual Studio Code

1. Visual Studio Codeに SQL Database Projects 拡張機能をインストールします。
2. ウェアハウスの SQL データベース プロジェクトを開きます。 ワークスペースが Git に接続されている場合は、リポジトリを複製してから、ウェアハウス プロジェクト フォルダーを開きます。
3. [ データベース プロジェクト] ビューで、プロジェクト ノードを右クリックし、[ 配置前スクリプトの追加] または [ 配置後スクリプトの追加] を選択します。
4. ファイル拡張子を付けずにスクリプト名を指定します。 スクリプト ファイルがプロジェクトに追加され、エディターで開かれます。
5. スクリプトに Transact-SQL を追加し、ファイルを保存します。 次の Git 更新プログラムの .sharedqueries フォルダーにファイルが保存されていることを確認します。
6. 変更をコミットして Git リポジトリにプッシュし、ソース管理からワークスペースを更新して構成を適用します。

SQL Server Management Studio

1. SQL Database プロジェクト エクスペリエンスを含む、SQL Server Management Studio 22 以降を使用します。
2. ウェアハウスの SQL データベース プロジェクトを開きます。
3. ソリューション エクスプローラーで、プロジェクト ノードを右クリックし、[追加>Script] を選択します。 [配置前スクリプト] または [配置後スクリプト] を選択します。
4. スクリプト ファイルがプロジェクトに追加され、クエリ エディターで開かれます。
5. スクリプトに Transact-SQL を追加し、ファイルを保存します。 次の Git 更新プログラムの .sharedqueries フォルダーにファイルを保存してください。
6. 変更をコミットして Git リポジトリにプッシュし、ソース管理からワークスペースを更新して構成を適用します。

プロジェクト ファイルを直接編集する

どのツールでも、 .sqlproj ファイルを編集し、単一の PreDeploy または PostDeploy 項目を ItemGroupに追加することで、スクリプトを指定できます。

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

既存の SQL プロジェクトから移行する

.sqlprojを SQL Server Data Tools (SSDT) または既に<PreDeploy>エントリと<PostDeploy>エントリが含まれているVisual Studioから移行する場合、Git を使用してプロジェクトをインポートすると、それらのエントリが認識され、Fabricの配置前および配置後の構成にマップされます。 Fabricではデプロイ前スクリプトと配置後スクリプトが 1 つしかサポートされないため、インポートする前に、プロジェクトに各種類のエントリが最大 1 つ含まれていることを確認します。

考慮事項と制限事項

• 1 つのウェアハウスでサポートされるデプロイ前スクリプトは 1 つだけで、デプロイ後のスクリプトは 1 つだけです。 スクリプトごとに複数のファイルをサポートしていません。
• デプロイ前スクリプトと配置後スクリプトの両方と同じ共有クエリを指定することはできません。
• 配置前または配置後スクリプトとして指定されている共有クエリを削除すると、対応する指定が自動的にクリアされます。
• デプロイ前または配置後のスクリプトとして指定された共有クエリをユーザー クエリに変更すると、対応する指定が自動的にクリアされます。
• デプロイ前およびデプロイ後のスクリプトは、すべてのウェアハウスデプロイで実行されます。 Transact-SQL スクリプトは、繰り返し実行しても失敗したり重複するオブジェクトを作成したりしないよう、冪等である必要があります。
• デプロイ前および配置後のスクリプトは、ビルド時にデータベース モデルに対して検証されません。 スクリプトのエラーはデプロイ時に表示され、スクリプトエラーによってデプロイが停止します。
• Fabric Data Warehouse でサポートされているTransact-SQL のみを使用できます。
• デプロイを実行する ID には、スクリプト コンテンツを実行するために必要なアクセス許可が必要です。

関連するコンテンツ

• 開発とデプロイのワークフロー
• クロスウェアハウス依存関係の開発とデプロイ
• Fabric デプロイ パイプラインの使用を開始する