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

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

概要

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

• 権限管理
• 変更追跡（CT）の設定
• データキャプチャ ( CDC ) 設定の変更
• プラットフォーム検出
• DDL はスキーマ変更追跡用のオブジェクト作成をサポートします

バージョン情報

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

主要コンポーネント

機能

lakeflowDetectPlatform()

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

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

lakeflowUtilityVersion_1_1()

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

戻り値: '1.1'

ストアドプロシージャ

lakeflowFixPermissions

取り込み操作に必要な権限をユーザーに付与します。

パラメーター:

パラメーター	説明
@User (NVARCHAR(128))	必須。権限を付与するユーザー名
@Tables (NVARCHAR(MAX))	オプション。テーブルレベルの権限スコープを制御します

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

オプション	説明
NULL	システムレベルの権限のみを付与する（デフォルト）
'ALL'	データベース内のすべてのユーザーテーブルに権限を付与する
'SCHEMAS:Schema1,Schema2'	指定されたスキーマ内のすべてのテーブルに対する権限を付与する
'Schema.Table1,Schema.Table2'	特定のテーブルに対する権限を付与する
ワイルドカードのサポート	例： 'Sales.*,HR.Employees'

機能:

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

lakeflowSetupChangeTracking

DDL サポートにより、データベース レベルおよびテーブル レベルでの変更追跡が可能になります。

パラメーター:

パラメーター	説明
@Tables (NVARCHAR(MAX))	オプション。CTを有効にするテーブル
@User (NVARCHAR(128))	オプション。権限を付与するユーザー
@Retention (NVARCHAR(50))	オプション。CT 保持期間 (デフォルト: '2 DAYS' )
@Mode (NVARCHAR(10))	オプション。'INSTALL' (デフォルト) または 'CLEANUP'

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

オプション	説明
NULL	データベース レベルの CT と DDL サポートのみをセットアップします (テーブルの有効化は行いません)
'ALL'	主キーを持つすべてのユーザーテーブルでCTを有効にする
'SCHEMAS:Schema1,Schema2'	指定されたスキーマ内のテーブルで CT を有効にする
'Schema.Table1,Schema.Table2'	特定のテーブルでCTを有効にする
ワイルドカードのサポート	例： 'Sales.*,HR.Employees'

機能:

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

重要な行動:

• 主キーのないテーブルを自動的にスキップします（これらのテーブルには CDC が推奨されます）
• 'ALL'パラメーターによるスマートな検出
• べき等性: 複数回実行しても安全

lakeflowSetupChangeDataCapture

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

パラメーター:

パラメーター	説明
@Tables (NVARCHAR(MAX))	オプション。CDCを有効にするテーブル
@User (NVARCHAR(128))	オプション。権限を付与するユーザー
@Mode (NVARCHAR(10))	オプション。'INSTALL' (デフォルト) または 'CLEANUP'

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

オプション	説明
NULL	データベースレベルのCDCとDDLのサポートのみを設定する
'ALL'	すべてのユーザーテーブルでCDCを有効にする
'SCHEMAS:Schema1,Schema2'	指定されたスキーマ内のテーブルで CDC を有効にする
'Schema.Table1,Schema.Table2'	特定のテーブルでCDCを有効にする

機能:

• まだ有効になっていない場合は、データベース レベルで 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 データベース (エンジン エディション 5)
• Azure SQL マネージドインスタンス (エンジンエディション 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. インストールを確認する

   SQL

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

代替案: コマンドラインを使用して実行する

sqlcmd使用する場合:

Bash

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

注記

YourServerNameとYourDatabase実際のサーバー名とデータベース名に置き換えます。Windows 認証を使用していない場合は、 -Eではなく-U username -P passwordを使用します。

例: 権限の修正 (システムのみ)

SQL

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

例: 権限を修正する (テーブルアクセスを含む)

SQL

-- 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';

例: 変更追跡の設定

データベースレベルのみ

SQL

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

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

SQL

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

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

SQL

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

特定のテーブル

SQL

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

例: CDCの設定

データベースレベルのみ

SQL

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

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

SQL

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

特定のテーブル

SQL

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

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

SQL

-- 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';

例: クリーンアップ

SQL

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

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

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

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

変更追跡用

オブジェクトタイプ	名前	説明
テーブル	lakeflowDdlAudit_1_2	DDLの変更履歴を保存します
トリガー	lakeflowDdlAuditTrigger_1_2	ALTER TABLEイベントをキャプチャします

CDC向け

オブジェクトタイプ	名前	説明
テーブル	lakeflowCaptureInstanceInfo_1_2	トラックキャプチャインスタンス
手順	lakeflowDisableOldCaptureInstance_1_2	古いキャプチャインスタンスを削除します
手順	lakeflowMergeCaptureInstances_1_2	インスタンス間でデータを結合する
手順	lakeflowRefreshCaptureInstance_1_2	新しいキャプチャインスタンスを作成します
トリガー	lakeflowAlterTableTrigger_1_2	スキーマの変更を処理する

変更追跡の制限

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

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

• Azure SQLデータベース: システム ストアド プロシージャには、デフォルトでアクセスできます ( EXECUTE権限は必要ありません)。
• サーバー スコープのビュー: sys.change_tracking_databasesなどのビューに対する Azure SQL Database のアクセスが制限されています。

アップグレードパス

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

ベストプラクティス

• 常にdb_ownerまたは同等の権限を持つユーザーとして実行します。
• まず本番以外の運用データベースでテストしてください。
• 包括的なカバレッジを実現するには、ハイブリッド アプローチを使用します。
• 適切なユーザー アクセスを確保するには、セットアップ後にlakeflowFixPermissionsを実行します。
• 取り込み頻度に基づいて保持期間を考慮してください。

トラブルシューティング

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

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

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

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

「カタログでは変更データキャプチャが有効になっていません」

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

「主キーが見つからないためテーブルはスキップされました」

解決策 : これらのテーブルには代わりにlakeflowSetupChangeDataCaptureを使用してください

検証統合

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

オブジェクト	説明
SqlServerUtilityObjectsSetupValidator	ユーティリティオブジェクトのインストールを検証します
SqlServerChangeDataManagementSetupValidator	CT/CDC セットアップを検証します
SqlServerDdlSupportObjectsSetupValidator	DDLサポートオブジェクトを検証する
SqlServerPermissionsSetupValidator	権限を検証する

移行に関する注意事項

以前のバージョンの DDL サポート オブジェクト (ユーティリティ オブジェクト以前の時代) からアップグレードする場合:

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

その他のリソース

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