2.4. Debezium 2.5.4 の機能および改善点

元の動作を維持する場合は、接続文字列に次のオプションを追加してコネクター設定をカスタマイズします。

&readPreference=secondaryPreferred

&readPreference=secondaryPreferred

コネクターがシャード化されたクラスターから読み取り、mongodb.connection.mode が replica_set に設定されている場合、新しい mongodb.connection.string.shard.params プロパティーを使用して、読み取り設定を secondary に設定する接続文字列を指定します。詳細は、Debezium ユーザーガイド のコネクターのセクションを参照してください。

コネクターをアップグレードすると、新しいデフォルト設定により既存のオフセットが無効になり、初期スナップショットのサイレント再実行がトリガーされます (DBZ-7272)。この動作を防ぐために、再起動によってスナップショットがトリガーされる場合にコネクターを失敗させるチェックが追加されました。

コネクターがシャード化されたクラスターから読み取る場合は、アップグレード後にコネクターの設定を確認し、必要に応じて接続モードを調整します。replica_set 接続モードを明示的に設定するか、既存のオフセットを削除することができます。

上記の設定で設定されたコネクターでスキーマレジストリーを使用する場合、レジストリーで厳密な互換性ルールが適用されていると、この変更によって互換性が失われる可能性があります。コネクターをアップグレードした後、互換性設定を調整するなど、必要に応じてアクションを実行し、精度を失わずに出力値が正確に表現されるようにします。

他のベンダーの実装とは異なり、Debezium JDBC シンクコネクターは、最初にイベントフラット化変換を処理する必要なく、Debezium ソースコネクターによって発行された変更イベントを取り込むことができます。Debezium JDBC コネクターを使用すると、パイプラインの処理フットプリントを削減し、設定を簡素化できます。コネクターは、列タイプの伝播などの Debezium ソースコネクター機能も活用できます。詳細は、Debezium ユーザーガイド を参照してください。

MongoDB コネクターを使用して、シャード化されたクラスターの複数のレプリカの増分スナップショットを実行することが、完全にサポートされるようになりました。詳細は、Debezium ユーザーガイド を参照してください。

以前のバージョンでは、シャード化されたクラスターのデプロイメントで MongoDB 用の Debezium コネクターを使用すると、コネクターは各シャードのレプリカセットとの接続を直接開きました。これは推奨されるアプローチではありません。代わりに、MongoDB ではコネクターが mongos インスタンス (ルーター) との接続を開く ことを提案しています。

このリリースは推奨ストラテジーに準拠しています。コネクターを mongos インスタンスに向けるために設定の調整が必要な場合があります。

下位互換性を維持するために、新しい設定プロパティー mongodb.connection.mode が利用可能です。このプロパティーのデフォルト値 replica_set は現在の動作を維持し、これにより、コネクターが各シャードを個別のレプリカセットとして処理します。値を sharded に設定すると、人工的に名前が付けられたクラスターを使用して ReplicaSet の単一インスタンスを内部的に作成するようコネクターに指示が出されます。この設定により、コネクターは最初に指定された接続文字列を使用して、シャードのすべてのメンバーへの接続を処理します。

詳細は、MongoDB のシャード化されたクラスターのサポート を参照してください。

増分スナップショットは、さまざまな再スナップショットのユースケースを処理するための一般的な方法です。ただし、スナップショット読み取りイベントがストリーミングイベント (作成、更新、削除) と絡み合っている場合、増分スナップショットの使用は、使用するアプリケーションによって示されなかったり、サポートされなかったりすることがあります。このような場合は、アドホックブロッキングスナップショットを実行できます。

アドホックブロッキングスナップショットとアドホック増分スナップショットの両方を Debezium にシグナルを送信してトリガーしますが、コネクターがブロッキングスナップショットシグナルを処理すると、スナップショット処理の間ストリーミングが保留になります。その結果、スナップショットは、スナップショット読み取りイベントとストリーミング作成、更新、および削除イベント間の分離を維持します。つまり、ブロッキングスナップショットプロセスは、従来のスナップショットが実行するプロセスと似ています。その結果、スループットは一般に増分スナップショットよりも高くなります。

アドホックブロッキングスナップショットを開始するためのシグナルは、アドホック増分スナップショットを開始するために使用するシグナルに似ています。次の例は、条件付きで特定のテーブルのブロッキングスナップショットを開始するためのシグナルのペイロードを示しています。このシグナルと増分スナップショットのシグナルとの唯一の違いは、シグナルの type が INCREMENTAL ではなく BLOCKING に設定されていることです。

{
  "type": "execute-snapshot",
  "data": {
    "data-collections": ["public.my_table"],
    "type": "BLOCKING",
    "additional-condition": "last_update_date >= '2023-01-01'"
  }
}

{
  "type": "execute-snapshot",
  "data": {
    "data-collections": ["public.my_table"],
    "type": "BLOCKING",
    "additional-condition": "last_update_date >= '2023-01-01'"
  }
}

コネクタータイプの詳細は、Debezium ユーザーガイドの スナップショットのブロック を参照してください。

多くの場合、お客様から、タイムゾーンが UTC 以外の値に設定された時間列を発行する機能のリクエストが寄せられます。過去のリリースでは、CustomConverter を作成したり、独自の単一メッセージ変換を記述して、コネクターが時間列を出力する方法を指定したりできました。

このリリースでは、Debezium は、コネクターが発行するイベント内の時間列のタイムゾーンを変更できる新しいタイムゾーン変換を提供します。パイプラインのニーズに応じて、列をデフォルトの UTC タイムゾーンから他のタイムゾーンに変換できます。この新しい変換を使い始めるには、コネクターに次の基本設定を追加します。

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York"
}

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York"
}

上記の設定を追加した後、コネクターがイベントを発行すると、UTC のすべての時間列が `America/New_York` タイムゾーンに変換されます。

次の例に示すように、include.fields プロパティーを使用して、時間フィールドのタイムゾーンを変更できるだけでなく、他のフィールドのタイムゾーン設定を変更することもできます。

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York",
  "transforms.tz.include.fields": "source:customers:created_at,customers:updated_at"
}

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York",
  "transforms.tz.include.fields": "source:customers:created_at,customers:updated_at"
}

上記の例では、include.fields の最初の値は、customers という名前の source テーブルにある created_at フィールドのタイムゾーンを変換します。次の値は、customers という名前のトピックの updated_at フィールドを変換します。

または、フィールドのサブセットを除くすべてに変換を適用する場合は、次の例のように exclude.fields プロパティーを設定できます。

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York",
  "transforms.tz.exclude.fields": "source:customers:updated_at"
}

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York",
  "transforms.tz.exclude.fields": "source:customers:updated_at"
}

前の例では、source テーブル名が customers で、フィールドが updated_at である場合を除き、変換によってすべての時間フィールドが America/New_York タイムゾーンに変換されます。詳細は、Debezium ユーザーガイドの Debezium イベントレコードのタイムゾーン値の変換 を参照してください。

コネクター MBean オブジェクト名に追加するカスタムタグを指定できるようになりました。カスタムタグを使用すると、より信頼性の高いコネクターのモニタリングを設定できます。

Debezium コネクターは、スナップショット、ストリーミング、スキーマ履歴プロセスの動作に関するデータを提供するメトリクスを公開します。これらのメトリクスは各コネクターで使用可能であり、コネクターの MBean 名を介して公開されます。

デフォルトでは、正しく設定されたコネクターをデプロイすると、Debezium はコネクター用の一意の MBean を生成します。その MBean に関連付けられたメトリクスを監視するように、可観測性スタックを設定できます。後でコネクター設定を変更すると、これらの変更によって元の MBean 名が変更される可能性があります。MBean 名が変更されると、コネクターインスタンスと MBean 間のリンクが切断され、新しい MBean 名を使用するように可観測性スタックを再設定しない限り、モニタリングツールはコネクターのメトリクスデータを取得できなくなります。

MBean 名の変更によって生じる潜在的な混乱を回避するには、コネクター設定に custom.metric.tags プロパティーを追加して、カスタムメトリクスタグを使用するようにコネクターを設定できます。custom.metric.tags プロパティーはキーと値のペアを受け入れます。各キーは MBean オブジェクト名のタグを表し、対応する値はそのタグの値を表します。たとえば、k1=v1,k2=v2 です。

コネクターの custom.metric.tags プロパティーを設定した後、指定したタグに関連付けられたメトリクスを取得するように可観測性スタックを設定します。可観測性スタックは、変更可能な MBean 名ではなく、指定されたタグを使用してコネクターを一意に識別します。その後、Debezium が MBean 名の構築方法を再定義したり、コネクター設定の topic.prefix が変更されたりしても、メトリクススクレイプタスクは指定されたタグパターンを使用してコネクターを識別するため、メトリクスの収集は中断されません。

カスタムタグを使用するさらなる利点は、データパイプラインのアーキテクチャーを反映するタグを使用できるため、運用上のニーズに合った方法でメトリクスを整理できることです。たとえば、コネクターアクティビティーのタイプ、アプリケーションコンテキスト、またはデータソースを宣言する値を持つタグを指定できます (例: db1-streaming-for-application-abc)。複数のキーと値のペアを指定すると、指定されたすべてのペアがコネクターの MBean 名に追加されます。

次の例は、タグがデフォルトの MBean 名を変更する方法を示しています。

debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>

debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>

debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory

debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory

Debezium MongoDB コネクターは、MongoDB 6 の大規模ドキュメント処理をサポートするようになりました。この変更により、コネクターが 16 MB を超えるドキュメントをキャプチャーしようとしたときに BSONObjectTooLarge 例外を返さなくなります。この機能を活用するようにコネクターを設定するには、oversize.handling.mode オプションを設定します。

Debezium 通知サブシステムは、従来の JMX アプローチを超えて、進行中の変更データキャプチャープロセスに関する洞察を得るために、サードパーティーのツールやアプリケーションを Debezium と簡単に統合する方法を提供します。以前のリリースでは、Debezium 通知サブシステムは、スナップショットの開始時刻、各テーブルの開始時刻と終了時刻、スナップショットの終了時刻など、初期スナップショットに関する基本的な情報のみを提供していました。現在は、初期スナップショットの進行中のステータスについて通知する機能が通知サブシステムに追加されました。

初期スナップショット通知は、Initial Snapshot の aggregatetType で発行され、スナップショットの現在のステータスを公開する type フィールドが含まれます。可能な値には、STARTED、ABORTED、PAUSED、RESUMED、IN_PROGRESS、TABLE_SCAN_COMPLETED、COMPLETED などがあります。

DBZ-6878 は基本機能を拡張し、スナップショットに関する詳細情報を提供します。たとえば、IN_PROGRESS 通知では、次の例のように、キャプチャーされているテーブルと現在進行中のテーブルに関する追加の詳細が提供されるようになりました。

{
   "id":"6d82a3ec-ba86-4b36-9168-7423b0dd5c1d",
   "aggregate_type":"Initial Snapshot",
   "type":"IN_PROGRESS",
   "additional_data":{
      "connector_name":"my-connector",
      "data_collections":"table1, table2",
      "current_collection_in_progress":"table1"
   },
   "timestamp": "1695817046353"
}

{
   "id":"6d82a3ec-ba86-4b36-9168-7423b0dd5c1d",
   "aggregate_type":"Initial Snapshot",
   "type":"IN_PROGRESS",
   "additional_data":{
      "connector_name":"my-connector",
      "data_collections":"table1, table2",
      "current_collection_in_progress":"table1"
   },
   "timestamp": "1695817046353"
}

このリリースにより、増分スナップショット中に使用するウォーターマークストラテジーを指定できるプロパティー incremental.snapshot.watermarking.strategy が導入されました。過去のリリースでは、insert_insert アプローチが使用されており、Debezium は各チャンクのスナップショット中にシグナリングデータコレクションに 2 つのエントリーを作成しました。最初のエントリーはスナップショット期間の開始を通知し、次のエントリーはスナップショット期間の終了を通知します。

新しい insert_delete オプションは、スナップショット期間の開始時に、各チャンクのシグナリングデータコレクションに 1 つのエントリーを書き込みます。スナップショットが完了すると、エントリーは削除され、スナップショット期間の終了を示す対応するエントリーは追加されません。この方法により、シグナリングデータコレクションをより効率的に管理できるようになります。

特定のソースデータベースの機能により、Debezium コネクターが変更イベントを発行すると、大量のデータを格納する列タイプの値がイベントによって除外される可能性があります。たとえば、PostgreSQL の TOAST 列、Oracle の LOB 列、または Oracle Exadata の Extended String 列の値はすべて、変更イベントから除外される可能性があります。

Debezium 2.5.4 では、コネクターがデータベーステーブルからキャプチャーした 1 つ以上の列を再選択し、それらの列の現在の状態を取得するメカニズムを提供する Reselect columns post processor が導入されました。次の列タイプを再選択するように post processor を設定できます。

PostProcessor の設定は、カスタムコンバーターまたは単一メッセージ変換の設定と似ていますが、SourceRecord ではなく、変更可能なペイロードの Struct で機能する点が異なります。詳細は、Debezium ユーザーガイドの using-the-reselect-columns-post-processor-to-add-source-fields-to-change-event-records を参照してください。

MongoDB 用の Debezium コネクターが変更イベントを発行する場合、イベントペイロードに更新で変更された完全なソースドキュメントが含まれるようにコネクターを設定できます。過去のリリースでは、コネクターによるイベントペイロード内の完全なドキュメントのストリーミングに一貫性がありませんでした。

コネクターが変更ストリーム内の完全なドキュメントを検索する方法を明示的に制御するには、設定オプション capture.mode.full.update.type を設定します。このオプションのデフォルト値は完全なドキュメントを検索するため、完全なドキュメントを取得するにはデータベースで別の検索を実行する必要があります。MongoDB 6 以降でコネクターを使用する場合は、コネクターを設定して post_image を使用し、MongoDB 変更ストリームのポストイメージサポートに依存できます。

詳細は、Debezium ユーザーガイドの MongoDB コネクターに関する章の capture.mode.full.update.type を参照してください。

Debezium 2.5.4 以降では、単一の MariaDB データベースデプロイメントに対して MySQL コネクターを実行できます。MySQL と MariaDB はどちらも、レプリケーションに グローバルトランザクション識別子 (GTID) を使用できます。GTID は、クラスター内のトランザクションを一意に識別する際に役立ちます。

MySQL コネクターを MariaDB GTID で動作させるには、コネクターに追加の設定を適用する必要があります。詳細は、Debezium ユーザーガイド を参照してください。

PostgreSQL 16 では、スタンバイインスタンスでレプリケーションスロットを定義できるようになりました。このデータベースの変更に基づいて、Debezium ではスタンバイ PostgreSQL 16 サーバーに接続し、そこから変更をストリーミングできるようになりました。運用システムからではなく、レプリカから変更データキャプチャーを実行すると、特に非常にアクティブなデータベースで、サーバーの負荷をより適切に分散できます。

CloudEvents コンバーターは、CloudEvents 仕様に準拠する変更イベントレコードを発行します。CloudEvents の変更イベントのエンベロープは、JSON または Avro であり、各エンベロープタイプは data フォーマットとして JSON または Avro をサポートしています。詳細は、CloudEvents コンバーター を参照してください。

デフォルトのデータ型変換がニーズを満たさない場合は、コネクターで使用するカスタムコンバーターを作成できます。詳細は、カスタム開発されたコンバーター を参照してください。

詳細は、Debezium ユーザーガイドの Oracle バイナリー文字 LOB タイプ を参照してください。

複数の並列スレッドを使用して初期スナップショットを実行する機能は、MySQL を除くすべての Debezium SQL コネクターのテクノロジープレビュー機能として利用できます。Debezium MySQL コネクターの並列初期スナップショットは、開発者プレビュー機能として利用できます。

並列初期スナップショットを使用するようにコネクターを設定するには、コネクター設定の snapshot.max.threads プロパティーを 1 より大きい値に設定します。

コネクターの詳細は、Debezium ユーザーガイドの snapshot.max.threads を参照してください。

スナップショットのパフォーマンスを向上させるために、MySQL コネクターは並列化を実装し、変更イベントのスナップショットを同時に作成して、テーブルのスキーマイベントを生成します。

これにより、データベース内の多数のテーブルのスキーマをキャプチャーする際のスナップショット時間が短縮されます。

このプロパティーを設定すると、コネクターはメトリクスを収集する際に、これらのキーと値のペアに基づく名前パターンを使用します。これにより、topic.prefix を変更するか、MBean 名が変更されるかに関係なく、コネクターが常に同じメトリクスセットを収集するように、安定した名前が確立されます。各コネクターインスタンスの MBean オブジェクト名をカスタマイズします。これらのカスタムメトリクスタグを追加することで、各コネクターに一意の MBean 名が付けられ、複数のインスタンス間の競合を防ぐことができます。

MySQL の Debezium 初期スナップショットは常にシングルスレッドでした。この制限は主に、複数のトランザクション間でデータの一貫性を確保するのが複雑であることに起因します。

このリリースでは、複数のスレッドを使用してテーブルレベルのスナップショットを並列に実行するように MySQL コネクターを設定できます。

この新しい機能を活用するには、コネクター設定に snapshot.max.threads プロパティーを追加し、そのプロパティーを 1 より大きい値に設定します。

snapshot.max.threads=4

snapshot.max.threads=4

前の例では、コネクターが 4 つ以上のテーブルをスナップショットする必要がある場合、最大 4 つのテーブルを並列でスナップショットできます。1 つのスレッドがテーブルの処理を終了すると、キュー内の次のテーブルを見つけてスナップショットの実行を開始します。コネクターが指定されたすべてのテーブルでスナップショットの実行を完了するまで、プロセスは続行されます。

詳細は、Debezium ユーザーガイドの snapshot.max.threads を参照してください。

Oracle 用の Debezium コネクターは、実稼働データベースまたはプライマリーデータベースに接続するときに、内部フラッシュテーブルを使用して Oracle Log Writer Buffer (LGWR) プロセスのフラッシュサイクルを管理します。フラッシュプロセスでは、コネクターがデータベースにアクセスするために使用するユーザーアカウントに、このフラッシュテーブルの作成と書き込みの権限が必要です。ただし、論理スタンバイデータベースには制限的なデータ操作ルールが設定されていることが多く、読み取り専用の場合もあります。その結果、データベースへの書き込みが実行できなくなる可能性があります。

Oracle の読み取り専用論理スタンバイデータベースをサポートするために、Debezium はフラッシュテーブルの作成と管理を無効にするプロパティーを導入しています。この機能は、Oracle スタンドアロンインストールと Oracle RAC インストールの両方で使用できます。

Oracle コネクターが読み取り専用論理スタンバイを使用できるようにするには、次のコネクターオプションを追加します。

internal.log.mining.read.only=true

internal.log.mining.read.only=true

詳細は、Debezium ユーザーガイドの Oracle コネクターのドキュメント を参照してください。

このリリースでは、Debezium は PostgreSQL コネクターに対して 1 回限りのセマンティクスのサポートを提供します。PostgreSQL の 1 回限りの配信はストリーミングフェーズにのみ適用され、スナップショットには適用されません。

Debezium は、監視対象ソースで発生するすべての変更イベントをコネクターが確実にキャプチャーできるようにすることを目的として、少なくとも 1 回の配信を提供するように設計されています。KIP-618 では、Apache Kafka コミュニティーが、プロデューサーがメッセージを再試行するときに発生する問題に対処するためのソリューションを提案しています。ソースコネクターは、ブローカーが以前にバッチをコミットした後でも、イベントのバッチを Kafka ブローカーに再送信することがあります。この状況では、重複したイベントがコンシューマー (シンクコネクター) に送信され、重複を簡単に処理できないコンシューマーに問題が発生する可能性があります。

1 回限りの配信を有効にするためにコネクター設定を変更する必要はありません。ただし、Kafka Connect ワーカー設定で 1 回限りの配信を設定する必要があります。必要な Kafka Connect 設定プロパティーの設定に関する詳細は、KIP-618 を参照してください。