SQL Server ユーティリティ オブジェクト スクリプト リファレンス
コンポーネント、パラメーター、トラブルシューティングなど、SQL Server ユーティリティ オブジェクト スクリプトのリファレンス マテリアルにアクセスします。
概要
このスクリプトは、バージョン管理されたユーティリティ ストアド プロシージャと関数をインストールして、 Lakeflow Connectで取り込めるようにSQL Serverデータベースを設定します。 セットアップ タスクには次のものが含まれます。
- 権限管理
- 変更追跡（CT）の設定
- データキャプチャ ( CDC ) 設定の変更
- プラットフォーム検出
- DDL はスキーマ変更追跡用のオブジェクト作成をサポートします
バージョン情報
- 現在のバージョン：1.7
- メジャーバージョン: 1
- マイナー バージョン: 7
- バージョン機能:
lakeflowUtilityVersion()
バージョン 1.7 の新機能
ハイライト
- スキーマ進化におけるデータ損失のバグを修正します。 In earlier versions, adding a column to a table that also has a pre-existing (non-Lakeflow) capture instance could ingest the new column as
NULL.This is fixed, along with several related スキーマ進化 failures (see Bug fixes). - 変更追跡において、DDL サポートオブジェクトはオプションになりました。 自動スキーマ進化において、DDL 監査テーブルとTriggerは不要になり、defaultで無効になっています。引き続き必要な場合にのみ、
lakeflowSetupChangeTrackingに@CreateDdlSupportingObjects = 1を設定します。 - より信頼性の高いスキーマ進化。 制約の変更は、外部キーなどの破壊的ではない変更が不要なフル更新をTriggerしないように分類されます。
バグ修正
- 動的データマスキング、大文字と小文字の区別やバイナリの照合順序を使用するテーブル、および既存のキャプチャインスタンスが存在する場合の再初期化ループや中断された取り込みなど、いくつかの
ADD COLUMNスキーマ進化の失敗を修正しました。 - default以外のサーバー照合順序を使用するデータベースにおける照合順序の競合エラーを修正しました。
- non-default
SETオプションを持つセッションから実行された場合に失敗する可能性があった DDL Trigger を修正しました。 - マスターデータベースから必要なサーバーレベルの権限を付与するように
lakeflowFixPermissionsを修正しました。 - アンインストール（
CLEANUPモード）を修正し、ALTER TABLEをブロックする可能性のある孤立した DDL Trigger を残しました。
その他の変更
lakeflowSetupChangeDataCaptureに@AllowDisablePreExistingCaptureInstancesが追加されました。Lakeflow Connect に引き継がせて、テーブルの既存の (Lakeflow 以外の) CDC キャプチャインスタンスをそのまま残すのではなく管理させるには、これを1に設定します。
主要コンポーネント
機能
lakeflowDetectPlatform()
SQL Server プラットフォームの種類を検出します。
戻り値: 'AZURE_SQL_DATABASE' 、 'AZURE_SQL_MANAGED_INSTANCE' 、 'AMAZON_RDS' 、 'ON_PREMISES' 、または 'UNKNOWN'
lakeflowUtilityVersion()
ユーティリティ オブジェクトのバージョンを検出します。
戻り値: '1.7'
ストアドプロシージャ
lakeflowFixPermissions
取り込み操作に必要な権限をユーザーに付与します。
パラメーター:
パラメーター | 説明 |
|---|---|
| 必須。権限を付与するユーザー名 |
| オプション。テーブルレベルの権限スコープを制御します |
@Tables パラメーターのオプション:
オプション | 説明 |
|---|---|
| システムレベルの権限のみを付与する（デフォルト） |
| データベース内のすべてのユーザーテーブルに権限を付与する |
| 指定されたスキーマ内のすべてのテーブルに対する権限を付与する |
| 特定のテーブルに対する権限を付与する |
ワイルドカードのサポート | 例： |
機能:
- 必要なシステム ビュー (
sys.objects、sys.tables、sys.columnsなど) に対するSELECTを付与します。 - システム ストアド プロシージャ (
sp_tables、sp_columns_100など) にEXECUTEを付与します - オプションで、
@Tablesパラメーターに基づいてユーザー テーブルにSELECTを付与します。 - プラットフォーム固有の違いを処理します (Azure SQL Database、マネージドインスタンス、RDS、オンプレミス)
lakeflowSetupChangeTracking
オプションの DDL サポート（オプトイン）により、データベースレベルおよびテーブルレベルでの変更追跡を有効にします。
パラメーター:
パラメーター | 説明 |
|---|---|
| オプション。CTを有効にするテーブル |
| オプション。権限を付与するユーザー |
| オプション。CT 保持期間 (デフォルト: |
| オプション。 |
| オプション。default |
@Tables パラメーターのオプション:
オプション | 説明 |
|---|---|
| Set up database-level CT only, no table enablement (also creates DDL support objects when |
| 主キーを持つすべてのユーザーテーブルでCTを有効にする |
| 指定されたスキーマ内のテーブルで CT を有効にする |
| 特定のテーブルでCTを有効にする |
ワイルドカードのサポート | 例： |
機能:
- データベース レベルでの変更追跡が有効になっていない場合は有効にします。
@CreateDdlSupportingObjects = 1の場合、バージョン管理されたDDL監査テーブル（lakeflowDdlAudit_1_7）と、スキーマの変更をキャプチャするTriggerを作成します- 指定されたテーブルで CT を有効にします (主キーのないテーブルはスキップします)
- 指定されたユーザーに
VIEW CHANGE TRACKING権限を付与します CLEANUPモード: DDLサポートオブジェクトを削除します
重要な行動:
- 主キーのないテーブルを自動的にスキップします（これらのテーブルには CDC が推奨されます）
'ALL'パラメーターによるスマートな検出- べき等性: 複数回実行しても安全
lakeflowSetupChangeDataCapture
DDL サポートとキャプチャ インスタンス管理により、データベース レベルおよびテーブル レベルで CDC を有効にします。
パラメーター:
パラメーター | 説明 |
|---|---|
| オプション。CDCを有効にするテーブル |
| オプション。権限を付与するユーザー |
| オプション。 |
| オプション。 |
@Tables パラメーターのオプション:
オプション | 説明 |
|---|---|
| データベースレベルのCDCとDDLのサポートのみを設定する |
| すべてのユーザーテーブルでCDCを有効にする |
| 指定されたスキーマ内のテーブルで CDC を有効にする |
| 特定のテーブルでCDCを有効にする |
機能:
-
まだ有効になっていない場合は、データベース レベルで CDC を有効にします。
-
キャプチャインスタンス追跡テーブル（
lakeflowCaptureInstanceInfo_1_7）を作成します -
キャプチャインスタンス管理用のヘルパー プロシージャを作成します。
lakeflowDisableOldCaptureInstance_1_7lakeflowMergeCaptureInstances_1_7lakeflowRefreshCaptureInstance_1_7
-
自動スキーマ変更処理用の
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セットアップの場合: プラットフォームで変更データ キャプチャが利用可能である必要があります
インストール手順
スクリプトをダウンロードして実行する
- スクリプトの最新バージョンをdownloadしてください。
-
スクリプトを実行します：
- ダウンロードしたスクリプトを SQL Server Management Studio (SSMS)、Azure Data Studio、またはお好みの SQL クライアントで開きます。
- SQL Server インスタンスに接続します。
- ユーティリティ オブジェクトをインストールするターゲット データベースに接続していることを確認します。
- スクリプトを実行します。
-
インストールを確認します：
SQL-- Verify installation
SELECT dbo.lakeflowUtilityVersion() AS UtilityVersion;
SELECT dbo.lakeflowDetectPlatform() AS Platform;
代替案: コマンドラインを使用して実行する
sqlcmd使用する場合:
sqlcmd -S YourServerName -d YourDatabase -E -i utility_script.sql
YourServerNameとYourDatabase実際のサーバー名とデータベース名に置き換えます。Windows 認証を使用していない場合は、 -Eではなく-U username -P passwordを使用します。
例: 権限の修正 (システムのみ)
-- 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';
DDL サポート オブジェクトを作成する
-- Enable CT and create the DDL audit table and trigger for schema-change capture
EXEC dbo.lakeflowSetupChangeTracking
@Tables = 'ALL',
@User = 'myuser',
@CreateDdlSupportingObjects = 1;
例: 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';
既存のキャプチャインスタンスの所有権を取得する
-- Allow Lakeflow to disable pre-existing (non-Lakeflow) capture instances
-- during schema change handling
EXEC dbo.lakeflowSetupChangeDataCapture
@Tables = 'ALL',
@User = 'myuser',
@AllowDisablePreExistingCaptureInstances = 1;
例: ハイブリッドアプローチ
-- 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 サポート オブジェクトが作成されます。
変更追跡用
オブジェクトタイプ | 名前 | 説明 |
|---|---|---|
テーブル |
| DDLの変更履歴を保存します |
トリガー |
|
|
CDC向け
オブジェクトタイプ | 名前 | 説明 |
|---|---|---|
テーブル |
| トラックキャプチャインスタンス |
手順 |
| 古いキャプチャインスタンスを削除します |
手順 |
| インスタンス間でデータを結合する |
手順 |
| 新しいキャプチャインスタンスを作成します |
トリガー |
| スキーマの変更を処理する |
変更追跡の制限
- 主キーが必要: 主キーのないテーブルでは変更追跡を使用できません。
- スクリプトは PK のないテーブルを自動的にスキップし、代わりに CDC を使用することを推奨します。
プラットフォーム固有の動作
- Azure SQLデータベース: システム ストアド プロシージャには、デフォルトでアクセスできます (
EXECUTE権限は必要ありません)。 - サーバー スコープのビュー:
sys.change_tracking_databasesなどのビューに対する Azure SQL Database のアクセスが制限されています。
アップグレードパス
アップグレードするには、ユーティリティオブジェクトスクリプトを再実行してから、セットアップ手順を再実行します。このスクリプトは、ユーティリティ関数を再作成し、以前のリリースからのレガシーな replicant で始まるオブジェクトのみを削除します。既存の Lakeflow DDL サポートオブジェクトはそのまま維持されるため、セットアップ手順を再実行するまで、現在の DDL Trigger によるスキーマ変更のキャプチャが継続されます。手順については、ステップ1: ユーティリティオブジェクトのインストールまたはアップグレードを参照してください。
アップグレード中に何が起こるか:
- スクリプトによって定義されたユーティリティ関数とセットアップ手順は削除され、再作成されます。
- 以前のリリースからのレガシーな
replicantプレフィックス付きオブジェクトは削除されます。 - 既存の Lakeflow DDL サポートオブジェクト（
lakeflowDdlAudit_*、lakeflowDdlAuditTrigger_*、lakeflowCaptureInstanceInfo_*、および関連するプロシージャとTrigger）はそのまま残されます。セットアッププロシージャを再実行すると、新しいバージョンに移行されます。lakeflowSetupChangeDataCaptureを再実行すると、キャプチャインスタンスオブジェクトが移動します。DDL 監査テーブルとTriggerはオプトインであるため、@CreateDdlSupportingObjects = 1を指定してlakeflowSetupChangeTrackingを再実行した場合にのみ移動します。 - 変更追跡と CDC はテーブル上で有効のままになります。アップグレードしてもそれらは無効になりません。
- CDC キャプチャ インスタンスはアップグレード スクリプトの影響を受けません。
アップグレード スクリプトを実行した後、セットアップ手順を再度実行して、新しいバージョンの DDL サポート オブジェクトを再作成します。
lakeflowSetupChangeTracking:@CreateDdlSupportingObjects = 1を使用して、DDL 監査テーブルと Trigger をlakeflowDdlAudit_1_7に引き継ぎます。インストールで DDL スキーマ変更キャプチャを使用する場合（lakeflowDdlAuditテーブルが存在する場合）、またはオブジェクトが古いバージョンのままである場合は、このフラグを渡します。lakeflowSetupChangeDataCapture:lakeflowCaptureInstanceInfo_1_7と関連するプロシージャおよびトリガーを再作成します。
どちらのプロシージャもべき等であり、元のセットアップで安全に再実行できます。
以前のバージョンのユーティリティオブジェクトスクリプトに元に戻すには、Databricks サポートにお問い合わせください。
バージョン管理スキーム: objectName_majorVersion_minorVersion 。現在のオブジェクトは_1_7サフィックスを使用します。
ベストプラクティス
- 常に
db_ownerまたは同等の権限を持つユーザーとして実行します。 - まず本番以外の運用データベースでテストしてください。
- 包括的なカバレッジを実現するには、ハイブリッド アプローチを使用します。
- 適切なユーザー アクセスを確保するには、セットアップ後に
lakeflowFixPermissionsを実行します。 - 取り込み頻度に基づいて保持期間を考慮してください。
トラブルシューティング
「このスクリプトを実行しているユーザーは 'db_owner' ロールのメンバーではありません」
解決策 : db_ownerロールを持つユーザーとして実行します
「カタログで変更追跡が有効になっていません」
解決策 : CT をデータベース レベルで有効にするか、プロシージャで自動的に処理させます。
「カタログでは変更データキャプチャが有効になっていません」
解決策 : データベース レベルでCDC有効にするか、プロシージャで自動的に処理させます。
「主キーが見つからないためテーブルはスキップされました」
解決策 : これらのテーブルには代わりにlakeflowSetupChangeDataCaptureを使用してください
検証統合
次のユーティリティ オブジェクトは、Java 検証フレームワークによって検証されます。
オブジェクト | 説明 |
|---|---|
| ユーティリティオブジェクトのインストールを検証します |
| CT/CDC セットアップを検証します |
| DDLサポートオブジェクトを検証する |
| 権限を検証する |
移行に関する注意事項
以前のバージョンの DDL サポート オブジェクト (ユーティリティ オブジェクト以前の時代) からアップグレードする場合:
- スクリプトはレガシー オブジェクトを自動的にクリーンアップします。
- 手動でのクリーンアップは必要ありません。
- バージョン 1.1 では、すべての機能が統一された手順に統合されます。
その他のリソース
- ユーティリティ オブジェクト スクリプトを使用して SQL Server の取り込みを準備する
- Databricks への取り込み用に Microsoft SQL Server を構成する
- Microsoft SQL Server データベースのユーザー要件
- SQL Server ドキュメントの「データの変更を追跡する (SQL Server)」
- SQL Server ドキュメントの変更の追跡 (SQL Server) について
- チェンジデータキャプチャ( CDC )とは何ですか? SQL Serverドキュメント内