6.6. Debezium Oracle コネクター設定プロパティーの説明

プロパティー

デフォルト

説明

name

デフォルトなし

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

connector.class

デフォルトなし

コネクターの Java クラスの名前。Oracle コネクターには、常に io.debezium.connector.oracle.OracleConnector の値を使用します。

tasks.max

1

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

database.hostname

デフォルトなし

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

database.port

デフォルトなし

Oracle データベースサーバーの整数のポート番号。

database.user

デフォルトなし

コネクターが Oracle データベースサーバーへの接続に使用する Oracle ユーザーアカウントの名前。

database.password

デフォルトなし

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

database.dbname

デフォルトなし

接続先のデータベースの名前。CDB + PDB モデルを使用する場合は、CDB 名である必要があります。

database.url

デフォルトなし

raw データベースの JDBC URL を指定します。このプロパティーを使用すると、そのデータベース接続を柔軟に定義できます。有効な値は、raw TNS 名および RAC 接続文字列などです。

database.pdb.name

デフォルトなし

接続先の Oracle のプラグ可能なデータベースの名前。このプロパティーは、コンテナーデータベース (CDB) のインストールでのみ使用してください。

database.server.name

デフォルトなし

コネクターが変更を取得する Oracle データベース・サーバーの nampespace を特定して提供する論理名。設定した値は、コネクターが出力するすべての Kafka トピック名の接頭辞として使用されます。Debezium 環境のすべてのコネクターで一意の論理名を指定します。英数字、ハイフン、ドットおよびアンダースコアの文字が有効です。

database.connection.adapter

logminer

コネクターがデータベースの変更をストリーミングする際に使用するアダプター実装。以下の値を設定できます。

snapshot.mode

Initial

このコネクターがキャプチャーされたテーブルのスナップショットを取得するために使用するモードを指定します。以下の値を設定できます。

スナップショットの完了後、コネクターはデータベースのやり直し (redo) ログから変更イベントの読み取りを続行します。

snapshot.locking.mode

shared

コネクターがテーブルロックを保持するかどうか、また保持する時間をコントロールします。テーブルロックは、コネクターがスナップショットを実行している間、特定の種類の変更テーブル操作が発生するのを防ぎます。以下の値を設定できます。

snapshot.include.collection.list

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

スナップショットに含めるテーブルの完全修飾名 (<schemaName>.<tableName>) と一致する正規表現のコンマ区切りリスト (任意)。指定する項目は、コネクターの table.include.list プロパティーで名前を付ける必要があります。このプロパティーは、コネクターの snapshot.mode プロパティーが never 以外の値に設定されている場合にのみ有効になります。

このプロパティーは増分スナップショットの動作には影響しません。

snapshot.select.statement.overrides

デフォルトなし

スナップショットに追加するテーブル行を指定します。スナップショットにテーブルの行のサブセットのみを含める場合は、プロパティーを使用します。このプロパティーはスナップショットにのみ影響します。コネクターがログから読み取るイベントには影響しません。

プロパティーには、<schemaName>.<tableName> の形式で完全修飾テーブル名のコンマ区切りリストが含まれます。たとえば、

"snapshot.select.statement.overrides": "inventory.products,customers.orders"

をリスト内の各テーブルに対して、スナップショットを作成する場合には、その他の設定プロパティーを追加して、コネクターがテーブルで実行するように SELECT ステートメントを指定します。指定した SELECT ステートメントは、スナップショットに追加するテーブル行のサブセットを決定します。この SELECT 文のプロパティーの名前を指定するには、次の形式を使用します。

snapshot.select.statement.overrides.<schemaName>.<tableName>

例: snapshot.select.statement.overrides.customers.orders

スナップショットにソフト削除以外のレコードのみを含める場合は、soft-delete 列 (delete_flag ) を含む customers.orders テーブルから、以下のプロパティーを追加します。

"snapshot.select.statement.overrides": "customer.orders",
"snapshot.select.statement.overrides.customer.orders": "SELECT * FROM [customers].[orders] WHERE delete_flag = 0 ORDER BY id DESC"

作成されるスナップショットでは、コネクターには delete_flag = 0 のレコードのみが含まれます。

schema.include.list

デフォルトなし

変更をキャプチャーする対象とするスキーマの名前と一致する正規表現のコンマ区切りリスト (任意)。schema.include.list に含まれていないスキーマ名は、変更をキャプチャーする対象から除外されます。デフォルトでは、システム以外のスキーマはすべて変更がキャプチャーされます。また、schema.exclude.list プロパティーも設定しないでください。LogMiner 実装を使用する環境では、POSIX 正規表現のみを使用する必要があります。

schema.exclude.list

デフォルトなし

変更をキャプチャーする対象としないスキーマの名前と一致する正規表現のコンマ区切りリスト (任意)。システムスキーマ以外で、schema.exclude.list に名前が含まれていないスキーマの変更がキャプチャーされます。また、schema.include.list プロパティーも設定しないでください。LogMiner 実装を使用する環境では、POSIX 正規表現のみを使用する必要があります。

table.include.list

デフォルトなし

監視するテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト (任意)。include リストに含まれていないテーブルは監視から除外されます。各テーブルの識別子は以下の形式を使用します。

<schema_name>.<table_name>

デフォルトでは、コネクターは各監視対象データベースのすべての非システムテーブルを監視します。このプロパティーは table.exclude.list と組み合わせて使用しないでください。LogMiner 実装を使用する場合は、このプロパティーで POSIX 正規表現のみを使用してください。

table.exclude.list

デフォルトなし

監視から除外するテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト (任意)。コネクターは除外リストに指定されていないテーブルからの変更をキャプチャーします。

<schemaName>.<tableName> 形式を使用して、各テーブルの識別子を指定します。

このプロパティーは table.include.list と組み合わせて使用しないでください。LogMiner 実装を使用する場合は、このプロパティーで POSIX 正規表現のみを使用してください。

column.include.list

デフォルトなし

変更イベントメッセージの値に含まれる必要がある列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。カラムの完全修飾名は以下の形式を使用します。+
`<Schema_name>.<table_name>.<column_name>

主キーカラムは、このプロパティーを使ってその値を明示的に含めなくても、常にイベントのキーに含まれます。このプロパティーを設定に含める場合は、column.exclude.list プロパティーを設定しないでください。

column.exclude.list

デフォルトなし

変更イベントメッセージの値から除外される必要がある列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。完全修飾のカラム名は以下の形式を使用します。

<schema_name>.<table_name>.<column_name>

主キーカラムは、このプロパティーを使用してその値を明示的に除外した場合でも、イベントのキーには常に含まれます。このプロパティーを設定に含める場合は、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、および実際のデータセットによっては、結果として得られるデータセットが完全にマスクされないことがあります。

decimal.handling.mode

precise

コネクターが NUMBER、DECIMAL および NUMERIC 列の浮動小数点値を処理する方法を指定します。以下のオプションのいずれかを使用できます。

event.processing.failure.handling.mode

fail

イベントの処理中にコネクターが例外に対応する方法を指定します。以下のオプションのいずれかを使用できます。

max.queue.size

8192

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

max.batch.size

2048

このコネクターの反復処理中に処理するイベントの各バッチの最大サイズを指定する正の整数値。

max.queue.size.in.bytes

0 (無効)

ブロッキングキューの最大サイズ (バイト単位) の long 値。機能を有効にするには、値を正の long データ型に設定します。

poll.interval.ms

1000 (1 秒)

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

tombstones.on.delete

true

削除 イベントの後に廃棄 (tombstone) イベントを行うかどうかを制御します。以下の値が可能です。

ソースレコードを削除すると、廃棄イベント (デフォルトの動作) により、Kafka が log compaction が有効なトピックで削除した列のキーを共有するイベントをすべて完全に削除できるようになります。

message.key.columns

デフォルトなし

指定のテーブルの Kafka トピックに公開する変更イベントレコードのカスタムメッセージキーを形成するためにコネクターが使用する列を指定する式のリスト。

デフォルトでは、Debezium はテーブルのプライマリーキー列を、出力するレコードのメッセージキーとして使用します。デフォルトの代わりに、またはプライマリーキーのないテーブルのキーを指定するには、1 つ以上の列をもとにカスタムメッセージキーを設定できます。
テーブルにカスタムメッセージキーを設定するには、テーブルを列挙した後、メッセージキーとして使用する列を列挙します。各リストエントリーは以下の形式をとります。

<fullyQualifiedTableName>:<keyColumn>,<keyColumn>

テーブルのキーを複数の列名に基づいて設定するには、列名の間にコンマを挿入します。
各完全修飾テーブル名は、以下の形式の正規表現です。

<schemaName>.<tableName>

プロパティーには複数のテーブルのエントリーを含めることができます。セミコロンを使用して、リスト内のテーブルエントリーを区切ります。
以下の例では、テーブル inventory.customers と purchase.orders にメッセージキーを設定しています。

inventory.customers:pk1,pk2;(.*).purchaseorders:pk3,pk4

テーブル inventory.customer では、列 pk1 と pk2 がメッセージキーとして指定されています。どのスキーマの purchaseorders テーブルでも、pk3 とpk4 のカラムがメッセージキーとして使用されます。
カスタムメッセージキーの作成に使用する列の数に制限はありません。ただし、一意の鍵を指定するために必要な最小数を使用することが推奨されます。

column.truncate.to.length.chars

デフォルトなし

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

column.mask.with.length.chars

デフォルトなし

文字をアスタリスク (*) に置き換えることで、変更イベントメッセージの列名をマスクする正規表現のコンマ区切りリスト (任意)。
プロパティー名に置き換える文字の数を指定します (例: column.mask.with.8.chars )。
長さは正の整数またはゼロでなければなりません。次に、マスクを適用する各文字ベースの列名のリストに正規表現を追加します。
<schemaName>.<tableName>.<columnName> の形式を使用して、列の完全修飾名を指定します。

コネクター設定には、異なる長さを指定する複数のプロパティーを含めることができます。

column.propagate.source.type

デフォルトなし

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

列の完全修飾名の形式は <tableName>.<columnName> または <schemaName>.<tableName>.<columnName> です。

datatype.propagate.source.type

デフォルトなし

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

完全修飾データ型名の形式は <tableName>.<typeName> または <schemaName>.<tableName>.<typeName> です。
Oracle 固有のデータ型名のリストを参照してください。

heartbeat.interval.ms

0

コネクターがメッセージをハートビートトピックに送信する頻度を定義する間隔 (ミリ秒単位) を指定します。
このプロパティーを使用して、コネクターがソースデータベースから変更イベントを受信し続けるかどうかを決定します。
コネクターで長期間、キャプチャーしたテーブルで変更イベントが発生しない場合に、このプロパティーを設定すると便利です。
このような場合には、コネクターは redo ログの読み取りを続行しますが、変更イベントメッセージは出力されないため、Kafka トピックのオフセットは変更されません。コネクターはデータベースから読み取る最新のシステム変更番号 (SCN) をフラッシュしないため、データベースは必要以上のログファイルを保持する可能性があります。コネクターが再起動すると、保持期間が延長され、コネクターは一部の変更イベントを重複して送信する可能性があります。
デフォルト値 0 が設定されていると、コネクターでハートビートメッセージが送信されません。

heartbeat.topics.prefix

__debezium-heartbeat

コネクターがハートビートメッセージを送信するトピック名の接頭辞を使用する文字列を指定します。
トピックは、<heartbeat.topics.prefix>.<serverName> パターンに従って名前が付けられます。

snapshot.delay.ms

デフォルトなし

スナップショットを作成する前に、コネクターが起動してから待機する間隔をミリ秒単位で指定します。
このプロパティーを使用して、クラスターで複数の接続を開始するときに (コネクターのリバランスの原因となる可能性がある) スナップショットが中断されないようにします。

snapshot.fetch.size

2000

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

sanitize.field.names

コネクター設定が、Avro を使用するようにkey.converter または value.converter パラメーターを明示的に指定する場合は true です。それ以外の場合のデフォルトは false です。

Avro の命名要件に準拠するためにフィールド名を正規化するかどうかを指定します。詳しい情報は、Avro naming を参照してください。

provide.transaction.metadata

false

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

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

log.mining.strategy

redo_log_catalog

Oracle Log Miner がテーブルとカラムの ID を名前に解決するために、指定されたデータディクショナリーを構築して使用する方法を制御するマイニング戦略を指定します。

redo_log_catalog::データディクショナリーをオンラインの REDO ログに書き込み、時間の経過とともにアーカイブログが多く生成されます。また、キャプチャしたテーブルに対する DDL の変更を追跡することができるので、スキーマが頻繁に変更される場合には理想的な選択です。

online_catalog::データベースの現在のデータ辞書を使用してオブジェクト ID を解決し、オンライン REDO ログに余分な情報を書き込みません。これにより、Log Miner は大幅に速く採掘できるようになりましたが、DDL の変更を追跡できないという代償を払いました。キャプチャしたテーブルのスキーマが頻繁に変更されない、または全く変更されない場合は、この方法が最適です。

log.mining.buffer.type

memory

バッファータイプは、コネクターがトランザクションデータのバッファーリングをどのように管理するかを制御します。

memory- JVM プロセスのヒープを使用してすべてのトランザクションデータをバッファーリングします。コネクターで長時間のトランザクションや大規模なトランザクションの処理を想定していない場合は、このオプションを選択します。このオプションを有効にすると、再起動時にバッファーの状態が保持されません。リスタート後は、現在のオフセットの SCN 値からバッファーを再作成します。

log.mining.batch.size.min

1000

このコネクターが redo/archive ログから読み込もうとする最小 SCN 間隔サイズ。また、必要に応じてコネクターのスループットを調整するために、アクティブバッチサイズをこの量だけ増減させます。

log.mining.batch.size.max

100000

このコネクターが REDO/ARCHIVE ログから読み取るときに使用する最大 SCN インターバルサイズです。

log.mining.batch.size.default

20000

コネクターが REDO/ARCHIVE ログからデータを読み取る際に使用する開始 SCN 間隔サイズ。

log.mining.sleep.time.min.ms

0

redo/archive ログからデータを読み込んだ後、再びデータの読み込みを開始するまでのコネクターのスリープ時間の最小値です。値はミリ秒単位です。

log.mining.sleep.time.max.ms

3000

redo/archive ログからデータを読み込んだ後、再びデータの読み込みを開始するまでのコネクターイルのスリープ時間の最大値。値はミリ秒単位です。

log.mining.sleep.time.default.ms

1000

redo/archive ログからデータを読み込んだ後、再びデータの読み込みを開始するまでのコネクターのスリープ時間の開始値。値はミリ秒単位です。

log.mining.sleep.time.increment.ms

200

logminer からデータを読み取る際に、コネクターが最適なスリープ時間を調整するために使用する時間の最大値を上下させる。値はミリ秒単位です。

log.mining.view.fetch.size

10000

コネクターが LogMiner コンテンツビューからフェッチしたコンテンツレコードの数。

log.mining.archive.log.hours

0

SYSDATE からアーカイブログを採掘するまでの過去の時間数です。デフォルトの設定 (0) を使用すると、コネクターはすべてのアーカイブログを粉砕します。

log.mining.archive.log.only.mode

false

コネクターが変更をアーカイブログだけから挽くのか、オンライン REDO ログとアーカイブログを組み合わせて挽くのか (デフォルト) を制御します。

redo ログは円形のバッファーを使用しており、どの時点でもアーカイブすることができます。オンライン redo ログが頻繁にアーカイブされる環境では、LogMiner のセッションが失敗することがあります。redo ログとは対照的に、アーカイブログは信頼性が保証されています。このオプションを true に設定すると、コネクターはアーカイブログのみをマイニングします。コネクターがアーカイブログのみをマイニングするように設定すると、オペレーションがコミットされてからコネクターが関連する変更イベントを発するまでの待ち時間が長くなることがあります。遅延の程度は、データベースがオンラインの redo ログをアーカイブするように設定されている頻度によって異なります。

log.mining.archive.log.only.scn.poll.interval.ms

10000

開始システムの変更番号がアーカイブ ログにあるかどうかを判断するためのポーリングの間に、コネクターがスリープするミリ秒数です。log.mining.archive.log.only.mode が有効でない場合は、この設定は使用されません。

log.mining.transaction.retention.hours

0

正の整数値で、redo ログの切り替えの間に長時間実行されるトランザクションを保持する時間数を指定します。0 に設定すると、コミットまたはロールバックが検出されるまで、トランザクションが保持されます。

LogMiner アダプターは、実行中のすべてのトランザクションのインメモリーバッファーを維持します。トランザクションの一部となるすべての DML 操作は、コミットまたはロールバックが検出されるまでバッファーされるため、そのバッファーがオーバーフローしないように長時間実行されるトランザクションを回避する必要があります。設定されたこの値を超えるトランザクションは完全に破棄され、コネクターはトランザクションに含まれていた操作のメッセージを出力しません。

log.mining.archive.destination.name

デフォルトなし

LogMiner でアーカイブログをマイニングする際に使用する、設定された Oracle のアーカイブ先を指定します。

デフォルトの動作では、ローカルで設定された最初の有効なデスティネーションが自動的に選択されます。しかし、LOG_ARCHIVE_DEST_5 のように、デスティネーション名を指定すれば、特定のデスティネーションを使用することができます。

log.mining.username.exclude.list

デフォルトなし

LogMiner クエリーから除外するデータベースユーザーのリスト。特定のユーザーが行った変更を常にキャプチャプロセスから除外したい場合は、このプロパティーを設定すると便利です。

log.mining.scn.gap.detection.gap.size.min

1000000

SCN ギャップがあるかどうかを判断するために、コネクターが現在の SCN 値と前回の SCN 値の差と比較する値を指定します。SCN 値の差が指定された値より大きく、時間差が log.mining.scn.gap.detection.time.interval.max.ms より小さい場合、SCN ギャップが検出され、コネクターは設定された最大バッチよりも大きいマイニングウィンドウ。

log.mining.scn.gap.detection.time.interval.max.ms

20000

SCN ギャップがあるかどうかを判断するために、コネクターが現在の SCN タイムスタンプと前回の SCN タイムスタンプの差と比較する値をミリ秒単位で指定します。タイムスタンプの差が指定された値よりも小さく、SCN デルタが指定された値よりも大きい場合、SCN ギャップが検出され、設定された最大バッチよりも大きいマイニングウィンドウを使用します。log.mining.scn.gap.detection.gap.size.min より大きい場合、SCN ギャップが検出され、コネクターは設定された最大バッチより大きいマイニングウィンドウを使用します。

lob.enabled

false

ラージオブジェクト (CLOB または BLOB) のカラム値を変更イベントで出力するかどうかを制御します。

デフォルトでは、変更イベントには大きなオブジェクト列がありますが、列には値が含まれていません。大規模なオブジェクトのカラムタイプやペイロードの処理管理には、ある程度のオーバーヘッドがあります。大きなオブジェクトの値をキャプチャして、変更イベントでシリアル化するには、このオプションを true に設定します。

unavailable.value.placeholder

__debezium_unavailable_value

コネクターが提供する定数を指定して、元の値がデータベースによって提供されておらず、また変更されていない値であることを示します。

rac.nodes

デフォルトなし

Oracle Real Application Clusters (RAC) ノードのホスト名またはアドレスをコンマで区切って入力してください。このフィールドは、Oracle RAC サポートを有効にするために必要です。RAC ノードのリストを以下のいずれかの方法で指定します。

database.url プロパティーを使用してデータベースの生の JDBC URL を提供する場合、database.port の値を定義する代わりに、各 RAC ノードのエントリーでポート値を明示的に指定する必要があります。

skipped.operations

デフォルトなし

ストリーミング中にコネクターがスキップする操作タイプをコンマで区切ったリスト。以下のタイプの操作をスキップするようにコネクターを設定することができます。

デフォルトでは、操作はスキップされません。

signal.data.collection

デフォルト値なし

シグナルをコネクターに送信するために使用されるデータコレクションの完全修飾名 。
コレクション名の指定には次のフォーマットを使用します。
<databaseName>.<schemaName>.<tableName>

incremental.snapshot.chunk.size

1024

増分スナップショットのチャンクの実行中にコネクターがメモリーを取得して読み取る行の最大数。スナップショットは、サイズが大きいスナップショットの場合にはクエリーが少なくなるため、チャンクサイズを増やすと効率が上がります。ただし、チャンクサイズが大きい場合には、スナップショットデータのバッファーにより多くのメモリーが必要になります。チャンクサイズは、環境で最適なパフォーマンスを発揮できる値に、調整します。