SQL Server ユーティリティ オブジェクトスクリプトリファレンス

コンポーネント、パラメーター、トラブルシューティングなど、SQL Server ユーティリティ オブジェクト スクリプトのリファレンス 資料にアクセスします。

概要

このスクリプトは、バージョン管理されたユーティリティ ストアド プロシージャと関数をインストールして、Lakeflow Connect でのインジェスト用に SQL Server データベースを設定します。 セットアップ タスクは次のとおりです。

• アクセス許可の管理
• 変更追跡 (CT) のセットアップ
• 変更データ キャプチャ (CDC) の設定
• プラットフォームの検出
• DDL では、スキーマ変更の追跡のためのオブジェクトの作成がサポートされます

バージョン情報

• 現在のバージョン: 1.1
• メジャー バージョン: 1
• マイナー バージョン: 1
• バージョン関数: lakeflowUtilityVersion_1_1()

主なコンポーネント

Functions

lakeflowDetectPlatform()

SQL Server プラットフォームの種類を検出します。

戻り値: 'AZURE_SQL_DATABASE'、 'AZURE_SQL_MANAGED_INSTANCE'、 'AMAZON_RDS'、 'ON_PREMISES'、または 'UNKNOWN'

lakeflowUtilityVersion_1_1()

ユーティリティ オブジェクトのバージョンを検出します。

戻り値: '1.1'

ストアド プロシージャ

lakeflowFixPermissions

インジェスト操作に必要なアクセス許可をユーザーに付与します。

Parameters:

@Tables パラメーター オプション:

実行内容:

• 必要なシステム ビュー (SELECT、sys.objects、sys.tablesなど) にsys.columnsを付与します。
• システム ストアド プロシージャ (EXECUTE、sp_tables など) のsp_columns_100を許可します。
• 必要に応じて、SELECT パラメーターに基づいてユーザー テーブルに@Tablesを許可します
• プラットフォーム固有の違い (Azure SQL Database、Managed Instance、RDS、オンプレミス) を処理します

lakeflowSetupChangeTracking

DDL サポートを使用して、データベース レベルとテーブル レベルで変更の追跡を有効にします。

Parameters:

@Tables パラメーター オプション:

実行内容:

• まだ有効になっていない場合は、データベース レベルで変更の追跡を有効にします
• バージョン管理された DDL 監査テーブルを作成します (lakeflowDdlAudit_1_2)
• スキーマの変更をキャプチャする DDL 監査トリガーを作成します
• 指定したテーブルに対して CT を有効にします (主キーのないテーブルをスキップします)
• 指定したユーザー VIEW CHANGE TRACKING アクセス許可を付与します
• CLEANUP モード: DDL サポートオブジェクトを削除します

重要な動作:

• 主キーのないテーブルを自動的にスキップします (これらには CDC をお勧めします)
• 'ALL' パラメーターを使用したスマート検出
• 冪等性: 複数回実行しても結果が変わらず安全

lakeflowSetupChangeDataCapture

DDL サポートとキャプチャ インスタンス管理を使用して、データベースレベルとテーブル レベルで CDC を有効にします。

Parameters:

@Tables パラメーター オプション:

実行内容:

• まだ有効になっていない場合は、データベース レベルで CDC を有効にします
• キャプチャ インスタンス追跡テーブルを作成します (lakeflowCaptureInstanceInfo_1_2)
• キャプチャ インスタンス管理用のヘルパー プロシージャを作成します。
  • lakeflowDisableOldCaptureInstance_1_2
  • lakeflowMergeCaptureInstances_1_2
  • lakeflowRefreshCaptureInstance_1_2
• スキーマ変更の自動処理用の ALTER TABLE トリガーを作成します
• 指定したテーブルで CDC を有効にします
• 指定したユーザーに必要な CDC アクセス許可を付与します
• CLEANUP モード: すべての CDC DDL サポート オブジェクトを削除します

重要な動作:

• 主キーの有無に関係なくテーブルを利用できます
• スキーマの変更時にキャプチャ インスタンスのローテーションを自動的に処理する
• 冪等性: 複数回実行しても結果が変わらず安全

プラットフォームのサポート

• オンプレミスの SQL Server (EngineEdition 1-4)
• Azure SQL Database (EngineEdition 5)
• Azure SQL Managed Instance (EngineEdition 8)
• Amazon RDS for SQL Server (サーバー名パターンによって検出)

[前提条件]

• スクリプトを実行するユーザーは、 db_owner ロールのメンバーである必要があります
• CTセットアップのためには、変更追跡機能がプラットフォームで利用可能である必要があります。
• CDC セットアップの場合: 変更データ キャプチャはプラットフォームで使用できる必要があります

インストール手順

スクリプトをダウンロードして実行する

1. スクリプトのダウンロード: utility_script.sql

2. スクリプトを実行する

   • ダウンロードしたスクリプトを SQL Server Management Studio (SSMS)、Azure Data Studio、または任意の SQL クライアントで開きます。
   • SQL Server インスタンスに接続します。
   • ユーティリティ オブジェクトをインストールするターゲット データベースに接続されていることを確認します。
   • スクリプトを実行します。

3. インストールの確認

   -- Verify installation
   SELECT dbo.lakeflowUtilityVersion_1_1() AS UtilityVersion;
   SELECT dbo.lakeflowDetectPlatform() AS Platform;
   

別の方法: コマンド ラインを使用して実行する

sqlcmdを使用する場合:

sqlcmd -S YourServerName -d YourDatabase -E -i lakeflow_utility_objects.sql

例: アクセス許可を修正する (システムのみ)

-- Grant system permissions only
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser';

例: アクセス許可を修正する (テーブル アクセスを使用)

-- Grant system permissions plus access to all tables
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser',
    @Tables = 'ALL';

-- Grant permissions for specific schemas
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser',
    @Tables = 'SCHEMAS:Sales,HR,Production';

-- Grant permissions for specific tables
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser',
    @Tables = 'Sales.Orders,HR.Employees';

例: 変更追跡の設定

データベース レベルのみ

-- Setup CT infrastructure without enabling on tables
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = NULL,
    @User = 'myuser';

すべてのテーブルで有効にする

-- Enable CT on all user tables with primary keys
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'ALL',
    @User = 'myuser';

スキーマ ベースのセットアップ

-- Enable CT on all tables in specific schemas
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'SCHEMAS:Sales,HR',
    @User = 'myuser',
    @Retention = '3 DAYS';

特定のテーブル

-- Enable CT on specific tables
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'dbo.Table1,Sales.Orders,HR.Employees',
    @User = 'myuser';

例: CDC のセットアップ

データベース レベルのみ

-- Setup CDC infrastructure without enabling on tables
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = NULL,
    @User = 'myuser';

すべてのテーブルで有効にする

-- Enable CDC on all user tables
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'ALL',
    @User = 'myuser';

特定のテーブル

-- Enable CDC on specific tables
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'dbo.Table1,Sales.Orders',
    @User = 'myuser';

例: ハイブリッドアプローチ

-- Step 1: Enable CT on tables with primary keys
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'ALL',
    @User = 'myuser';

-- Step 2: Enable CDC on remaining tables (without primary keys)
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'ALL',
    @User = 'myuser';

例: クリーンアップ

-- Remove CT DDL support objects
EXEC dbo.lakeflowSetupChangeTracking
    @Mode = 'CLEANUP';

-- Remove CDC DDL support objects
EXEC dbo.lakeflowSetupChangeDataCapture
    @Mode = 'CLEANUP';

作成された DDL サポート オブジェクト

変更の追跡と CDC のどちらを使用するかに応じて、次の DDL サポート オブジェクトが作成されます。

変更追跡のために

CDC の場合

変更の追跡の制限事項

• 主キーが必要です。主キーのないテーブルでは、変更の追跡を使用できません。
• このスクリプトは、PK（プライマリーキー）がないテーブルを自動的にスキップし、代わりに CDC を使用することをお勧めします。

プラットフォーム固有の動作

• Azure SQL Database: システム ストアド プロシージャには既定でアクセスできます ( EXECUTE 許可は必要ありません)。
• サーバー スコープ ビュー: sys.change_tracking_databasesなどのビューに対する Azure SQL Database の制限付きアクセス。

アップグレード経路

• スクリプトは、実行時に以前のすべてのバージョンを自動的に削除します。
• バージョン管理スキーム: objectName_majorVersion_minorVersion
• 現在のオブジェクトは、バージョン追跡 _1_1 サフィックスを使用します。

ベスト プラクティス

• 常に、 db_owner または同等の特権を持つユーザーとして実行します。
• 最初に非運用データベースでテストします。
• 包括的な適用範囲を実現するために、ハイブリッドアプローチを使用します。
• セットアップ後に lakeflowFixPermissions を実行して、適切なユーザー アクセスを確保します。
• インジェストの頻度に基づいて保持期間を検討してください。

トラブルシューティング

"このスクリプトを実行するユーザーは 'db_owner' ロール メンバーではありません"

解決策: db_owner ロールを持つユーザーとして実行する

"カタログで変更の追跡が有効になっていません"

解決策: データベース レベルで CT を有効にするか、プロシージャで自動的に処理させる

"Change data capture is not enabled on catalog" (変更データ キャプチャがカタログで有効になっていません)

解決策: データベース レベルで CDC を有効にするか、プロシージャで自動的に処理させる

"主キーがないためにスキップされたテーブル"

解決策: 代わりにこれらのテーブルに lakeflowSetupChangeDataCapture を使用する

検証の統合

次のユーティリティ オブジェクトは、Java 検証フレームワークによって検証されます。

移行のメモ

古いバージョンの DDL サポートオブジェクト（ユーティリティ導入前のオブジェクト）からアップグレードする場合:

• スクリプトは、レガシ オブジェクトを自動的にクリーンアップします。
• 手動クリーンアップは必要ありません。
• バージョン 1.1 では、すべての機能が統合された手順に統合されています。

その他のリソース

• ユーティリティ オブジェクト スクリプトを使用して SQL Server をインジェスト用に準備する
• Azure Databricks への取り込み用に Microsoft SQL Server を構成する
• Microsoft SQL Server データベースのユーザー要件
• SQL Server ドキュメントのデータ変更の追跡 ( SQL Server)
• SQL Server ドキュメントの変更追跡 (SQL Server) について
• 変更データ キャプチャ (CDC) とは SQL Server のドキュメント