sys.sp_cdc_enable_table (Transact-SQL)

適用対象: SQL Server

現在のデータベース内の指定したソース テーブルを対象に変更データ キャプチャを有効にします。 テーブルで変更データ キャプチャが有効になっている場合、テーブルに適用された各データ操作言語 (DML) 操作のレコードがトランザクション ログに書き込まれます。 変更データ キャプチャ プロセスは、ログからこの情報を取得し、一連の関数を使用してアクセスされる変更テーブルに書き込みます。

変更データ キャプチャは、SQL Server のすべてのエディションで使用できるわけではありません。 SQL Server の各エディションでサポートされる機能の一覧については、「SQL Server 2022 の各エディションとサポートされている機能」を参照してください。

Transact-SQL 構文表記規則

構文

sys.sp_cdc_enable_table
    [ @source_schema = ] 'source_schema'
      , [ @source_name = ] 'source_name'
    [ , [ @capture_instance = ] 'capture_instance' ]
    [ , [ @supports_net_changes = ] supports_net_changes ]
      , [ @role_name = ] 'role_name'
    [ , [ @index_name = ] 'index_name' ]
    [ , [ @captured_column_list = ] N'captured_column_list' ]
    [ , [ @filegroup_name = ] 'filegroup_name' ]
    [ , [ @allow_partition_switch = ] 'allow_partition_switch' ]
[ ; ]

引数

[ @source_schema = ] 'source_schema'

ソース テーブルが属するスキーマの名前。 @source_schema は既定 sysnameであり、 NULLすることはできません。

[ @source_name = ] 'source_name'

変更データ キャプチャを有効にするソース テーブルの名前。 @source_name は既定 sysnameであり、 NULLすることはできません。

source_name は、現在のデータベースに存在する必要があります。 cdc スキーマ内のテーブルを変更データ キャプチャに対して有効にすることはできません。

[ @role_name = ] 'role_name'

変更データへのアクセスをゲートするために使用するデータベース ロールの名前。 @role_name は sysname 指定する必要があります。 明示的に NULL に設定されている場合、変更データへのアクセスを制限するためにゲーティング ロールは使用されません。

ロールが現在存在する場合は、そのロールが使用されます。 ロールが存在しない場合は、指定した名前のデータベース ロールの作成が試行されます。 ロール名は、ロールの作成を試みる前に、文字列の右側にある空白文字でトリミングされます。 呼び出し元がデータベース内にロールを作成する権限がない場合、ストアド プロシージャの操作は失敗します。

[ @capture_instance = ] 'capture_instance'

インスタンス固有の変更データ キャプチャ オブジェクトを識別するために使用されるキャプチャ インスタンスの名前です。 @capture_instanceは sysname でありNULLすることはできません。

指定しない場合、ソース スキーマ名とソース テーブル名に基づき、 <schemaname>_<sourcename>形式の名前が付けられます。 @capture_instance 100 文字を超えることはできません。また、データベース内で一意である必要があります。 指定した場合でも派生した場合でも、 @capture_instance は文字列の右側にある空白でトリミングされます。

ソース テーブルには、最大 2 つのキャプチャ インスタンスを含めることができます。 詳細については、「 sys.sp_cdc_help_change_data_capture」を参照してください。

[ @supports_net_changes = ] supports_net_changes

差分変更クエリのサポートをこのキャプチャ インスタンスで有効にするかどうかを示します。 @supports_net_changesはビットですテーブルに主キーがある場合、またはテーブルに @index_name パラメーターを使用して識別された一意のインデックスがある場合、既定値は 1 です。 それ以外の場合、パラメーターは既定で 0されます。

• 0場合、すべての変更を照会するサポート関数のみが生成されます。
• 1場合、ネット変更のクエリに必要な関数も生成されます。

@supports_net_changesが 1 に設定されている場合は、@index_nameを指定するか、ソース テーブルに主キーが定義されている必要があります。

@supports_net_changesを 1 に設定すると、変更テーブルに追加の非クラスター化インデックスが作成され、net changes クエリ関数が作成されます。 このインデックスを維持する必要があるため、ネット変更を有効にすると CDC のパフォーマンスに悪影響を及ぼす可能性があります。

[ @index_name = ] 'index_name'

ソース テーブル内の行を一意に識別するために使用する、一意のインデックスの名前を指定します。 @index_nameは sysname でありNULLできます。 指定する場合、 @index_name はソース テーブルの有効な一意のインデックスである必要があります。 @index_nameが指定されている場合、識別されたインデックス列は、テーブルの一意の行識別子として、定義されている主キー列よりも優先されます。

[ @captured_column_list = ] N'captured_column_list'

変更テーブルに含めるソース テーブルの列を識別します。 @captured_column_list は nvarchar(max) であり、 NULLできます。 NULL場合、すべての列が変更テーブルに含まれます。

列名は、ソース テーブル内の有効な列である必要があります。 主キー インデックスで定義されている列、または @index_name によって参照されるインデックスで定義されている列を含む必要があります。

@captured_column_list は、列名のコンマ区切りのリストです。 リスト内の個々の列名は、必要に応じて、二重引用符 ("") または角かっこ ([]) を使用して引用符で囲むことができます。 列名にコンマが埋め込まれている場合は、列名を引用符で囲む必要があります。

@captured_column_list 、 __$start_lsn、 __$end_lsn、 __$seqval、 __$operation、および __$update_maskの予約列名を含めることはできません。

[ @filegroup_name = ] 'filegroup_name'

キャプチャ インスタンス用に作成された変更テーブルに使用するファイル グループ。 @filegroup_name は sysname で、 NULLできます。 指定した場合、 @filegroup_name は現在のデータベースに対して定義する必要があります。 NULL場合は、既定のファイル グループが使用されます。

変更データ キャプチャの変更テーブル用に、別個のファイル グループを作成することをお勧めします。

[ @allow_partition_switch = ] 'allow_partition_switch'

変更データ キャプチャが有効であるテーブルに対して ALTER TABLE の SWITCH PARTITION コマンドを実行できるかどうかを指定します。 @allow_partition_switch は bit で、既定値は 1 です。

パーティション分割されていないテーブルの場合、スイッチの設定は常に 1 になり、実際の設定は無視されます。 パーティション分割されていないテーブルに対してスイッチが明示的に 0 に設定されている場合は、スイッチ設定が無視されたことを示す警告 22857 が発行されます。 切り替えがパーティション テーブルの 0 に明示的に設定されている場合、ソース テーブルに対するパーティション 切り替え操作が許可されていないことを示す警告 22356 が発行されます。 最後に、スイッチ設定が明示的に 1 に設定されているか、既定で 1 に許可されていて、有効なテーブルがパーティション分割されている場合は、パーティション スイッチがブロックされていないことを示す警告 22855 が発行されます。 パーティション の切り替えが発生した場合、変更データ キャプチャはスイッチの結果の変更を追跡しません。 これにより、変更データが使用されるときにデータの不整合が発生します。

SWITCH PARTITION はメタデータ操作ですが、データの変更が発生します。 この操作に関連付けられているデータ変更は、変更データ キャプチャ変更テーブルにはキャプチャされません。 3 つのパーティションを持つテーブルについて考えてみます。このテーブルに変更が加えられます。 キャプチャ プロセスは、テーブルに対して実行されるユーザーの挿入、更新、および削除操作を追跡します。 ただし、パーティションが別のテーブルに切り替えられた場合 (たとえば、一括削除を実行する場合)、この操作の一環として移動された行は、変更テーブルの削除された行としてキャプチャされません。 同様に、事前設定された行を含む新しいパーティションがテーブルに追加された場合、これらの行は変更テーブルに反映されません。 このため、変更がアプリケーションで使用され、変更先に適用されると、データの不整合が生じる可能性があります。

SQL Server でパーティションの切り替えを有効にした場合、近い将来に分割操作とマージ操作が必要になる場合もあります。 レプリケートテーブルまたは CDC 対応テーブルに対して分割またはマージ操作を実行する前に、対象のパーティションに保留中のレプリケートコマンドがないことを確認してください。 分割操作とマージ操作中にパーティションで DML 操作が実行されないようにする必要もあります。 ログ リーダーまたは CDC キャプチャ ジョブが処理されていないトランザクションがある場合、または分割またはマージ操作の実行中にレプリケートテーブルまたは CDC 対応テーブルのパーティションに対して DML 操作が実行された場合 (同じパーティションを含む)、ログ リーダー エージェントまたは CDC キャプチャ ジョブで処理エラー (エラー 608 - パーティション ID のカタログ エントリが見つかりません) が発生する可能性があります。 このエラーを修正するには、サブスクリプションを再初期化するまたはそのテーブルまたはデータベース上で CDC を無効にすることが必要になる場合があります。

リターン コードの値

0 (成功) または 1 (失敗)。

結果セット

ありません。

解説

変更データ キャプチャのテーブルを有効にする前に、データベースを有効にする必要があります。 データベースで変更データ キャプチャが有効になっているかどうかを確認するには、sys.databases カタログ ビューのis_cdc_enabled列に対してクエリを実行します。 データベースを有効にするには、 sys.sp_cdc_enable_db ストアド プロシージャを使用します。

テーブルに対して変更データ キャプチャを有効にすると、変更テーブルと 1 つまたは 2 つのクエリ関数が生成されます。 変更テーブルは、キャプチャ プロセスによってトランザクション ログから抽出されたソース テーブルの変更に関するリポジトリとして機能します。 クエリ関数は、変更テーブルからデータを抽出するために使用されます。 これらの関数の名前は、次の方法で @capture_instance パラメーターから派生します。

• すべての変更関数: cdc.fn_cdc_get_all_changes_<capture_instance>
• Net changes 関数: cdc.fn_cdc_get_net_changes_<capture_instance>

sys.sp_cdc_enable_table また、ソース テーブルがデータベースの最初のテーブルで変更データ キャプチャを有効にしていて、データベースにトランザクション パブリケーションが存在しない場合は、データベースのキャプチャ ジョブとクリーンアップ ジョブも作成します。 sys.tables カタログ ビューのis_tracked_by_cdc列を1に設定します。

テーブルに対して CDC が有効になっている場合、SQL Server エージェントを実行する必要はありません。 ただし、SQL Server エージェントが実行されていない限り、キャプチャ プロセスはトランザクション ログを処理し、エントリを変更テーブルに書き込むことはありません。

アクセス許可

db_owner 固定データベース ロール内でメンバーシップが必要です。

例

A. 必要なパラメーターのみを指定して変更データ キャプチャを有効にする

次の例では、 HumanResources.Employee テーブルの変更データ キャプチャを有効にします。 必要なパラメーターのみが指定されます。

USE AdventureWorks2022;
GO

EXECUTE sys.sp_cdc_enable_table
    @source_schema = N'HumanResources',
    @source_name = N'Employee',
    @role_name = N'cdc_Admin';
GO

B. 追加の省略可能なパラメーターを指定して変更データ キャプチャを有効にする

次の例では、 HumanResources.Department テーブルの変更データ キャプチャを有効にします。 @allow_partition_switchを除くすべてのパラメーターが指定されます。

USE AdventureWorks2022;
GO

EXEC sys.sp_cdc_enable_table
    @source_schema = N'HumanResources',
    @source_name = N'Department',
    @role_name = N'cdc_admin',
    @capture_instance = N'HR_Department',
    @supports_net_changes = 1,
    @index_name = N'AK_Department_Name',
    @captured_column_list = N'DepartmentID, Name, GroupName',
    @filegroup_name = N'PRIMARY';
GO

関連するコンテンツ

• sys.sp_cdc_disable_table (Transact-SQL)
• sys.sp_cdc_help_change_data_capture (Transact-SQL)
• cdc.fn_cdc_get_all_changes_<capture_instance> (Transact-SQL)
• cdc.fn_cdc_get_net_changes_<capture_instance> (Transact-SQL)
• sys.sp_cdc_help_jobs (Transact-SQL)