8.4.2. Debezium SQL Server コネクター設定プロパティーの説明

name

コネクターの一意名。同じ名前で再登録を試みると失敗します。(このプロパティーはすべての Kafka Connect コネクターに必要です)

connector.class

コネクターの Java クラスの名前。SQL Server コネクターには、常に io.debezium.connector.sqlserver.SqlServerConnector の値を使用します。

tasks.max

1

このコネクターのために作成する必要のあるタスクの最大数。SQL Server コネクターは常に単一のタスクを使用するため、この値を使用しません。そのため、デフォルト値は常に許容されます。

database.hostname

SQL Server データベースサーバーの IP アドレスまたはホスト名。

database.port

1433

SQL Server データベースサーバーのポート番号 (整数)。

database.user

SQL Server データベースサーバーへの接続時に使用するユーザー名。

database.password

SQL Server データベースサーバーへの接続時に使用するパスワード。

database.dbname

変更をストリーミングする SQL Server データベースの名前。

database.server.name

Debezium がキャプチャーする SQL Server データベースサーバーの namespace を識別および提供する論理名。論理名は、他のコネクター全体で一意となる必要があります。これは、このコネクターから生成されるすべての Kafka トピック名のプレフィックスとして使用されるためです。英数字とアンダースコアのみを使用する必要があります。

table.include.list

Debezium がキャプチャーするテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト（任意）。table. include.list に含まれていないテーブルはキャプチャーから除外されます。各識別子の形式は schemaName.tableName です。デフォルトでは、コネクターは指定のスキーマのシステム以外のテーブルをすべてキャプチャーします。table.exclude.list と併用しないでください。

table.exclude.list

キャプチャーから除外するテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト（任意）。Debezium は table. exclude.list に含まれていないテーブルをすべてキャプチャーします。各識別子の形式は schemaName.tableName です。table.include.list と併用しないでください。

column.include.list

空の文字列

変更イベントメッセージの値に含まれる必要がある列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は schemaName.tableName.columnName です。プライマリーキー列は、値に含まれていない場合でもイベントのキーに常に含まれることに注意してください。column.exclude.list プロパティーを設定しないでください。

column.exclude.list

空の文字列

変更イベントメッセージの値から除外される必要がある列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は schemaName.tableName.columnName です。プライマリーキー列は、値から除外される場合でもイベントのキーに常に含まれることに注意してください。column.include.list プロパティーを設定しないでください。

column.mask.hash.hashAlgorithm.with.salt.salt

該当なし

文字ベースの列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は schemaName.tableName.columnName です。生成される変更イベントレコードでは、指定された列の値は仮名に置き換えられます。

仮名は、指定された hashAlgorithm と salt を適用すると得られるハッシュ化された値で構成されます。使用されるハッシュ関数に基づいて、参照整合性は維持され、列値は仮名に置き換えられます。サポートされるハッシュ関数は、Java Cryptography Architecture Standard Algorithm Name Documentationの MessageDigest section に説明されています。

以下の例では、CzQMA0cB5K が無作為に選択された salt になります。

column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName

必要な場合は、仮名は自動的に列の長さに短縮されます。コネクター設定には、異なるハッシュアルゴリズムと salt を指定する複数のプロパティーを含めることができます。

使用される hashAlgorithm、選択された salt、および実際のデータセットによっては、結果として得られるデータセットが完全にマスクされないことがあります。

time.precision.mode

adaptive

時間、日付、およびタイムスタンプは、異なる精度の種類で表すことができます。これには、適合性 （ デフォルト値）は、データベース列の型を基にして、ミリ秒、マイクロ秒、またはナノ秒の精度値のいずれかを使用してデータベースの値と全く同じ時間とタイムスタンプをキャプチャーします。もしくは connect は、Kafka Connect の Time、Date、および Timestamp の組み込み表現を使用して、常に時間とタイムスタンプ値を表し、データベース列の精度に関わらず、ミリ秒の精度を使用します。「 時間値 」を参照してください。

decimal.handling.mode

正確性

コネクターによる DECIMAL および NUMERIC 列の値の処理方法を指定します。

precise (デフォルト) はバイナリー形式で変更イベントに表される java.math.BigDecimal 値を使用して正確に表します。

double は double値を使用して表します。精度が失われる可能性はありますが、簡単に使用できます。

string は値をフォーマットされた文字列としてエンコードします。簡単に使用できますが、本来の型に関するセマンティック情報は失われます。

include.schema.changes

true

コネクターがデータベーススキーマの変更を、データベースサーバー ID と同じ名前の Kafka トピックに公開するかどうかを指定するブール値。各スキーマの変更は、データベース名が含まれるキーと、スキーマ更新を記述する JSON 構造である値で記録されます。これは、コネクターがデータベース履歴を内部で記録する方法には依存しません。デフォルトは true です。

tombstones.on.delete

true

削除 イベントの後に廃棄 (tombstone) イベントが続くかどうかを制御します。

true: 削除操作は、削除 イベントと後続の破棄 (tombstone) イベントで表されます。

false: 削除イベントのみ出力されます。

log compaction がトピックで有効になっている場合には、ソースレコードの削除後に廃棄 (tombstone) イベントを出力すると (デフォルト動作)、Kafka は削除された行のキーに関連するすべてのイベントを完全に削除できます。

column.truncate.to._length_.chars

該当なし

フィールド値が指定された文字数より長い場合に、変更イベントメッセージ値で値を省略する必要がある文字ベースの列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。長さが異なる複数のプロパティーを単一の設定で使用できますが、それぞれの長さは正の整数である必要があります。列の完全修飾名の形式は schemaName.tableName.columnName です。

column.mask.with._length_.chars

該当なし

変更イベントメッセージで、指定された数のアスタリスク(*)文字で構成されるフィールド値に値を置き換える必要のある文字ベースの列の完全修飾名と一致する正規表現のコンマ区切りリスト（任意）。長さが異なる複数のプロパティーを単一の設定で使用できますが、それぞれの長さは正の整数またはゼロである必要があります。列の完全修飾名の形式は schemaName.tableName.columnName です。

column.propagate.source.type

該当なし

出力された変更メッセージの該当するフィールドスキーマに元の型および長さをパラメーターとして追加する必要がある列の完全修飾名と一致する、正規表現のコンマ区切りリスト (任意)。スキーマパラメーター __debezium.source.column.type,__debezium.source.column.length および __debezium.source.column.scale は、それぞれ元の型名と長さ（variable-width タイプの場合）を伝播するために使用されます。シンクデータベースの対応する列を適切にサイズ調整するのに便利です。列の完全修飾名の形式は schemaName.tableName.columnName です。

datatype.propagate.source.type+

該当なし

出力された変更メッセージフィールドスキーマに元の型および長さをパラメーターとして追加する必要がある列のデータベース固有のデータ型名と一致する、正規表現のコンマ区切りリスト (任意)。スキーマパラメーター __debezium.source.column.type,__debezium.source.column.length および __debezium.source.column.scale は、それぞれ元の型名と長さ（可変幅型）を伝播するために使用されます。シンクデータベースの対応する列を適切にサイズ調整するのに便利です。完全修飾データ型名の形式は schemaName.tableName.typeName です。SQL Server 固有のデータ型 のリストは、「SQL Server データ型」を参照してください。

message.key.columns

該当なし

プライマリーキーをマップする完全修飾テーブルおよび列と一致する正規表現のセミコロン区切りリスト。
各項目（正規表現）は、カスタムキーを表すコラムの カンマ区切りの <fully-qualified table>:<a comma-separated list と一致する必要があります。
完全修飾テーブルは schemaName.tableName として定義できます。

binary.handling.mode

bytes

バイナリー （バイナリー、varbinary）列を変更イベントで表す方法を指定します。たとえば、バイトは バイナリーデータをバイト配列（デフォルト）で表します。base 64 はバイナリーデータを base64 でエンコードされた文字列として表します。hex はバイナリーデータを 16 進エンコード(base16)文字列として表します。

snapshot.mode

Initial

キャプチャーされたテーブルの構造 (および必要に応じてデータ) の最初のスナップショットを作成するモード。スナップショットが完了すると、コネクターはデータベースのやり直し (redo) ログから変更イベントの読み取りを続行します。以下の値がサポートされています。

snapshot.include.collection.list

table.include.listに指定したすべてのテーブル

スナップショットの作成 に使用する table. include.list に含まれる 完全修飾テーブル 名(<db-name>.<schema-name>.<name>)の名前と一致する正規表現のコンマ区切りリスト（任意）。

snapshot.isolation.mode

repeatable_read

使用されるトランザクション分離レベルと、キャプチャー用に指定されたテーブルをコネクターがロックする期間を制御するモード。以下の値がサポートされています。

スナップショット、read_committed モード、および read_uncommitted モードは、最初のスナップショットの実行中に他のトランザクションによるテーブル行の更新を阻止しません。exclusive および repeatable _read モードは、同時更新を阻止します。

モードの選択は、データの整合性にも影響します。排他的 スナップショット およびスナップショットモードは、完全な整合性を保証します。つまり、最初のスナップショットとログのストリーミングが履歴の線形を構成します。repeatable _read モードおよび read_committed モードの場合、たとえば、追加されたレコードが最初のスナップショットで 1 回、ストリーミングフェーズで 1 回表示される可能性があります。しかし、この整合性レベルはデータのミラーリングであれば問題ないはずです。read_uncommitted には、データの整合性の保証が全くありません（一部のデータは損失または破損する可能性があります）。

event.processing.failure.handling.mode

fail

イベントの処理中にコネクターが例外に対応する方法を指定します。fail は例外 (問題のあるイベントのオフセットを示す) を伝達するため、コネクターが停止します。
warn を指定すると問題のあるイベントがスキップされ、問題のあるイベントのオフセットがログに記録されます。
skip を指定すると、問題のあるイベントがスキップされます。

poll.interval.ms

1000

各反復処理の実行中に新しい変更イベントが表示されるまでコネクターが待機する時間 (ミリ秒単位) を指定する正の整数値。デフォルトは 1000 ミリ秒 (1 秒) です。

max.queue.size

8192

データベースログから読み取られた変更イベントが Kafka に書き込まれる前に配置される、ブロッキングキューの最大サイズを指定する正の整数値。このキューは、Kafka への書き込みが遅い場合や Kafka が利用できない場合などに、CDC テーブルリーダーにバックプレシャーを提供できます。キューに発生するイベントは、このコネクターによって定期的に記録されるオフセットには含まれません。デフォルトは 8192 で、max. batch.size プロパティーで指定される最大バッチサイズよりも常に大きくする必要があります。

max.batch.size

2048

このコネクターの反復処理中に処理される必要があるイベントの各バッチの最大サイズを指定する正の整数値。デフォルトは 2048 です。

heartbeat.interval.ms

0

ハートビートメッセージが送信される頻度を制御します。
このプロパティーには、コネクターがメッセージをハートビートトピックに送信する頻度を定義する間隔 (ミリ秒単位) が含まれます。このプロパティーは、コネクターがデータベースから変更イベントを受信しているかどうかを確認するために使用できます。また、長期に渡り変更されるのはキャプチャーされていないテーブルのレコードのみである場合は、ハートビートメッセージを利用する必要があります。このような場合、コネクターはデータベースからログの読み取りを続行しますが、変更メッセージを Kafka に出力しないため、オフセットの更新が Kafka にコミットされません。これにより、コネクターの再起動後に再送信される変更イベントが増える可能性があります。ハートビートメッセージを送信しない場合は、このパラメーターを 0 に設定します。
デフォルトでは無効にされています。

heartbeat.topics.prefix

__debezium-heartbeat

ハートビートメッセージが送信されるトピックの命名を制御します。
トピックの名前は、<heartbeat.topics.prefix>.<server.name> パターンに従って名前が付けられます。

snapshot.delay.ms

コネクターの起動後、スナップショットを取得するまで待機する間隔 (ミリ秒単位)。
クラスター内で複数のコネクターを開始する際に スナップショットが中断されないようにするために使用でき、コネクターのリバランスが実行される可能性があります。

snapshot.fetch.size

2000

スナップショットの実行中に各テーブルから 1 度に読み取る必要がある行の最大数を指定します。コネクターは、このサイズの複数のバッチでテーブルの内容を読み取ります。デフォルトは 2000 です。

query.fetch.size

指定のクエリーのデータベースのラウンドトリップごとにフェッチされる行の数を指定します。デフォルトは、JDBC ドライバーのデフォルトのフェッチサイズです。

snapshot.lock.timeout.ms

10000

スナップショットの実行時に、テーブルロックを取得するまで待つ最大時間 (ミリ秒単位) を指定する整数値。この時間間隔でテーブルロックを取得できないと、スナップショットは失敗します（ スナップショットも参照）。
0 に設定すると、ロックを取得できないとコネクターが即座に失敗します。値 -1 は無限の待機を示します。

snapshot.select.statement.overrides

テーブルのどの行がスナップショットに含まれるかを制御します。
このプロパティーには、完全修飾テーブル (SCHEMA_NAME.TABLE_NAME) のコンマ区切りリストが含まれます。各テーブルの select ステートメントは、id snapshot.select.statement.overrides.[SCHEMA_NAME].[TABLE_NAME] で識別される追加の設定プロパティーで指定されています。これらのプロパティーの値は、スナップショットの実行中に特定のテーブルからデータを取得するときに使用する SELECT ステートメントです。大規模な追加専用テーブルで可能なユースケースとしては、前のスナップショットが中断された場合にスナップショットの開始 (再開) 点を設定することが挙げられます。
注記: この設定はスナップショットにのみ影響します。ログの読み取り中にキャプチャーされたイベントは影響を受けません。

sanitize.field.names

コネクター設定 が key.converter または value を明示的に指定する場合は True。Avro を使用するパラメーターは、すべて false です。

Avro の命名要件に準拠するためにフィールド名がサニタイズされるかどうか。

database.server.timezone

サーバーのタイムゾーン。

このプロパティーは、サーバー（実際にはゾーン化されていない）から取得したトランザクションのタイムスタンプ(ts_ms)のタイムゾーンを定義します。デフォルトでは、この値は設定されません。SQL Server 2014 以前のバージョンで実行する場合にのみ、プロパティーの値を設定し、Debezium コネクターを実行しているデータベースサーバーと JVM は異なるタイムゾーンを使用します。

設定しない場合、デフォルトでは Debezium コネクターを実行する仮想マシンのタイムゾーンを使用します。この場合、SQL Server 2014 以前のバージョンで実行し、サーバーとコネクターが異なるタイムゾーンを使用する場合、正しくない ts_ms 値が生成されることがあります。
使用できる値には、「Z」、「UTC」、「+02:00」などのオフセット値、「CET」などの短いゾーン ID、および 「Europe/Paris」などの長いゾーン ID が含まれます。

provide.transaction.metadata

false

true に設定すると、Debezium はトランザクション境界でイベントを生成し、トランザクションメタデータでデータイベントエンベロープを強化します。

詳細は、「 トランザクションメタデータ 」を参照してください。

retriable.restart.connector.wait.ms

10000 (10 秒)

再試行可能なエラーが発生した後にコネクターを再起動するまで待機する時間 (ミリ秒単位)。

database.history.kafka.topic

コネクターがデータベーススキーマの履歴を保存する Kafka トピックの完全名。

database.history.kafka.bootstrap.servers

Kafka クラスターへの最初の接続を確立するために コネクターが使用するホストとポートのペアの一覧。このコネクションは、コネクターによって以前に保存されたデータベーススキーマ履歴の取得や、ソースデータベースから読み取られる各 DDL ステートメントの書き込みに使用されます。各ペアは、Kafka Connect プロセスによって使用される同じ Kafka クラスターを示す必要があります。

database.history.kafka.recovery.poll.interval.ms

100

永続化されたデータのポーリングが行われている間にコネクターが起動/回復を待つ最大時間 (ミリ秒単位) を指定する整数値。デフォルトは 100 ミリ秒です。

database.history.kafka.recovery.attempts

4

エラーでコネクターのリカバリーが失敗する前に、コネクターが永続化された履歴データの読み取りを試行する最大回数。データを受信しなかった後に待機する最大時間は recovery. attempts x recovery. poll.interval.ms です。

database.history.skip.unparseable.ddl

false

コネクターが不正または不明なデータベースのステートメントを無視するかどうか、または人が問題を修正するために処理を停止するかどうかを指定するブール値。安全なデフォルトは false です。スキップは、binlog の処理中にデータの損失や分割を引き起こす可能性があるため、必ず注意して使用する必要があります。

database.history.store.only.monitored.tables.ddl

今後のリリースで削除される予定です 。代わりに database.history.store.only.captured.tables.ddl を使用してください。

false

コネクターがすべての DDL ステートメントを記録するかどうかを指定するブール値。

True は、変更が Debezium によってキャプチャーされるテーブルに関連する DDL ステートメントのみを記録します。変更がキャプチャーされるテーブルを変更すると、不足しているデータが必要になる可能性があるため、不足しているデータが必要になる可能性があるため、注意して true に設定します。

安全なデフォルトは false です。

database.history.store.only.captured.tables.ddl

false

コネクターがすべての DDL ステートメントを記録するかどうかを指定するブール値。

True は、変更が Debezium によってキャプチャーされるテーブルに関連する DDL ステートメントのみを記録します。変更がキャプチャーされるテーブルを変更すると、不足しているデータが必要になる可能性があるため、不足しているデータが必要になる可能性があるため、注意して true に設定します。

安全なデフォルトは false です。