Debezium ユーザーガイド

Red Hat Integration 2021.Q3

Debezium 1.5 の使用

概要

本ガイドでは、Debezium で提供されるコネクターを使用する方法を説明します。

前書き

Debezium は、データベースの行レベルの変更をキャプチャーする分散サービスのセットで、アプリケーションがそれらの変更を認識し、応答できるようにします。Debezium は、各データベーステーブルにコミットされたすべての行レベルの変更を記録します。各アプリケーションは、対象のトランザクションログを読み取り、発生した順序ですべての操作を確認します。

本ガイドでは、以下の Debezium トピックの使用方法について説明します。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。これは大規模な取り組みであるため、これらの変更は今後の複数のリリースで段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージをご覧ください。

第1章 Debezium の概要

Debezium は、データベースの変更をキャプチャーする分散サービスのセットです。アプリケーションはこれらの変更を利用し、応答できます。Debezium は、各データベーステーブルの行レベルの変更を 1 つずつ変更イベントレコードにキャプチャーし、これらのレコードを Kafka トピックにストリーミングします。これらのストリームはアプリケーションによって読み取られ、変更イベントレコードは生成された順に提供されます。

詳細は、以下を参照してください。

1.1. Debezium の機能

Debezium は、Apache Kafka Connect のソースコネクターのセットです。各コネクターは、CDC (Change Data Capture) のデータベースの機能を使用して、異なるデータベースから変更を取り込みます。ログベースの CDC は、ポーリングや二重書き込みなどのその他の方法とは異なり、Debezium によって実装されます。

  • すべてのデータ変更がキャプチャーされたことを確認します。
  • 頻度の高いポーリングに必要な CPU 使用率の増加を防ぎながら、非常に低遅延な変更イベントを生成します。たとえば、MySQL または PostgreSQL の場合、遅延はミリ秒の範囲内になります。
  • Last Updated (最終更新日時) の列など、データモデルへの変更は必要ありません
  • 削除をキャプチャー できます。
  • データベースの機能や設定に応じて、トランザクション ID や原因となるクエリーなどの古いレコードの状態や追加のメタデータをキャプチャーできます。

詳細は、ブログの記事「Five Advantages of Log-Based Change Data Capture」を参照してください。

Debezium コネクターは、さまざまな関連機能やオプションでデータの変更をキャプチャーします。

  • スナップショット: コネクターが起動し、すべてのログが存在していない場合は、任意でデータベースの現在の状態の初期スナップショットを取得できます。通常、これは、データベースが一定期間稼働していて、トランザクションのリカバリーやレプリケーションに不要となったトランザクションログを破棄してしまった場合に該当します。スナップショットを実行するためのモードは複数あります。使用しているコネクターのドキュメントを参照してください。
  • フィルター: キャプチャーされたスキーマ、テーブル、およびコラムは include または exclude リストフィルターで設定できます。
  • マスク:たとえば、機密データが含まれている場合など、特定の列からの値はマスクできます。
  • 監視: ほとんどのコネクターは JMX を使用して監視できます。
  • 使用準備が整った メッセージ変換:

各コネクターのドキュメントには、コネクター機能と設定オプションの詳細が記載されています。

1.2. Debezium アーキテクチャーの説明

Apache Kafka Connect を使用して Debezium をデプロイします。Kafka Connect は、以下を実装および操作するためのフレームワークおよびランタイムです。

  • レコードを Kafka に送信する Debezium などのソースコネクター
  • Kafka トピックから他のシステムにレコードを伝播するシンクコネクター

以下の図は、Debezium をベースとした Change Data Capture パイプラインのアーキテクチャーを示しています。

Debezium Architecture

イメージにあるように、MySQL と PostgresSQL の Debezium コネクターは、この 2 種類のデータベースへの変更をキャプチャーするためにデプロイされます。各 Debezium コネクターは、そのソースデータベースへの接続を確立します。

  • MySQL コネクターは、binlog へのアクセスにクライアントライブラリーを使用します。
  • PostgreSQL コネクターは論理レプリケーションストリームから読み取ります。

Kafka Connect は、Kafka ブローカー以外の別のサービスとして動作します。

デフォルトでは、1 つのデータベースからの変更が、名前がテーブル名に対応する Kafka トピックに書き込まれます。必要な場合は、Debezium の トピックルーティング変換 を設定すると、宛先トピック名を調整できます。たとえば、以下を実行できます。

  • テーブルの名前と名前が異なるトピックへレコードをルーティングする。
  • 複数テーブルの変更イベントレコードを単一のトピックにストリーミングする。

変更イベントレコードが Apache Kafka に存在する場合、Kafka Connect エコシステムの異なるコネクターは、Elasticsearch、データウェアハウス、分析システムなどのその他のシステムおよびデータベースや、Infinispan などのキャッシュにレコードをストリーミングできます。選択したシンクコネクターによっては、Debezium の 新しいレコード状態抽出 (Record State Extraction) の変換を設定する必要がある場合があります。この Kafka Connect SMT は、Debezium の変更イベントからシンクコネクターに after 構造を伝播します。これは、デフォルトで伝播される詳細な変更イベントレコードの代わりになります。

第2章 必要なカスタムリソースのアップグレード

Debezium は、AMQ Streams on OpenShift で実行される Apache Kafka クラスターにデプロイされた Kafka コネクタープラグインです。OpenShift CRD v1 向けに準備するために、現行バージョンの AMQ Streams で、カスタムリソース定義 (CRD) API の必要なバージョンが v1beta2 に設定されました。API の v1beta2 バージョンは、従来サポートされていた v1beta1 および v1alpha1 API バージョンに代わるものです。v1alpha1 および v1beta1 API バージョンのサポートは AMQ Streams で非推奨になりました。以前のバージョンは、Debezium コネクターの設定に使用する KafkaConnect および KafkaConnector リソースを含むほとんどの AMQ Streams カスタムリソースから削除されました。

v1beta2 API バージョンをベースとする CRD は OpenAPI 構造スキーマを使用します。非推奨の v1alpha1 または v1beta1 API に基づくカスタムリソースは構造スキーマをサポートしないため、現行バージョンの AMQ Streams と互換性がありません。AMQ Streams2021.q3 にアップグレードする前に、既存のカスタムリソースをアップグレードして API バージョン kafka.strimzi.io/v1beta2 を使用する必要があります。AMQ Streams 1.7 にアップグレードした後、カスタムリソースをいつでもアップグレードできます。AMQ Streams2021.q3 以降にアップグレードする前に、v1beta2 API へのアップグレードを完了する必要があります。

CRD およびカスタムリソースのアップグレードを容易にするため、AMQ Streams は {ApiVersion} と互換性のある形式に自動的にアップグレードする API 変換ツールを提供します。ツールの詳細と、AMQ Streams のアップグレード方法に関する詳細は、「NameDeployStreamsOpenShift」を参照してください。

注記

カスタムリソースの更新要件は、AMQ Streams on OpenShift で実行される Debezium デプロイメントにのみ適用されます。この要件は、Red Hat Enterprise Linux 上の Debezium には適用されません。

第3章 Db2 の Debezium コネクター

Debezium の Db2 コネクターは、Db2 データベースのテーブルで行レベルの変更をキャプチャーできます。このコネクターは、テーブルを「キャプチャーモード」にする SQL ベースのポーリングモデルを使用する、SQL Server の Debezium 実装から大きく影響を受けます。テーブルがキャプチャーモードの場合、Debezium Db2 コネクターは、そのテーブルへの行レベルの更新ごとに変更イベントを生成し、ストリーミングします。

キャプチャーモードのテーブルには、関連する変更テーブルがあり、このテーブルは Db2 によって作成されます。キャプチャーモードのテーブルに対する変更ごとに、Db2 はその変更に関するデータをテーブルの関連する変更データテーブルに追加します。変更データテーブルには、行の各状態のエントリーが含まれます。また、削除に関する特別なエントリーもあります。Debezium Db2 コネクターは変更イベントを変更データテーブルから読み取り、イベントを Kafka トピックに出力します。

Debezium Db2 コネクターが Db2 データベースに初めて接続すると、コネクターが変更をキャプチャーするように設定されたテーブルの整合性スナップショットを読み取ります。デフォルトでは、システム以外のテーブルがすべて対象になります。キャプチャーモードにするテーブルまたはキャプチャーモードから除外するテーブルを指定できるコネクター設定プロパティーがあります。

スナップショットが完了すると、コネクターはコミットされた更新の変更イベントをキャプチャーモードのテーブルに出力し始めます。デフォルトでは、特定のテーブルの変更イベントは、テーブルと同じ名前を持つ Kafka トピックに移動します。アプリケーションとサービスはこれらのトピックから変更イベントを使用します。

注記

コネクターには、Linux 用の Db2 の標準部分として利用できる抽象構文表記 (ASN) ライブラリーを使用する必要があります。ASN ライブラリーを使用するには、IBM InfoSphere Data Replication (IIDR) のライセンスが必要です。ASN ライブラリーを使用するために IIDR をインストールする必要はありません。

Debezium Db2 コネクターを使用するための情報および手順は、以下のように構成されています。

3.1. Debezium Db2 コネクターの概要

Debezium Db2 コネクターは、Db2 で SQL レプリケーションを有効にする ASN Capture/Apply エージェント をベースにしています。キャプチャーエージェントは以下を行います。

  • キャプチャーモードであるテーブルの変更データテーブルを生成します。
  • キャプチャーモードのテーブルを監視し、更新の変更イベントを対応する変更データテーブルのテーブルに格納します。

Debezium コネクターは SQL インターフェースを使用して変更イベントの変更データテーブルに対してクエリーを実行します。

データベース管理者は、変更をキャプチャーするテーブルをキャプチャーモードにする必要があります。便宜上およびテストを自動化するために、以下の管理タスクをコンパイルし、実行できる Debezium ユーザー定義関数 (UDF) が C にあります。

  • ASN エージェントの開始、停止、および再初期化。
  • テーブルをキャプチャーモードにする。
  • レプリケーション (ASN) スキーマと変更データテーブルの作成。
  • キャプチャーモードからのテーブルの削除。

また、Db2 制御コマンドを使用してこれらのタスクを実行することもできます。

対象のテーブルがキャプチャーモードになった後、コネクターは対応する変更データテーブルを読み取り、テーブル更新の変更イベントを取得します。コネクターは、変更されたテーブルと同じ名前を持つ Kafka トピックに対して、行レベルの挿入、更新、および削除操作ごとに変更イベントを出力します。これは、変更可能なデフォルトの動作です。クライアントアプリケーションは、対象のデータベーステーブルに対応する Kafka トピックを読み取り、行レベルの各変更イベントに対応できます。

通常、データベース管理者はテーブルのライフサイクルの途中でテーブルをキャプチャーモードにします。つまり、コネクターにはテーブルに加えられたすべての変更の完全な履歴はありません。そのため、Db2 コネクターが最初に特定の Db2 データベースに接続すると、キャプチャーモードである各テーブルで 整合性スナップショット を実行して起動します。コネクターは、スナップショットの完成後に、スナップショットが作成された時点から変更イベントをストリーミングします。これにより、コネクターはキャプチャーモードのテーブルの整合性のあるビューで開始し、スナップショットの実行中に加えられた変更は破棄されません。

Debezium コネクターはフォールトトラレントです。コネクターは変更イベントを読み取りおよび生成すると、変更データテーブルエントリーのログシーケンス番号 (LSN) を記録します。LSN はデータベースログの変更イベントの位置になります。コネクターが何らかの理由で停止した場合 (通信障害、ネットワークの問題、クラッシュなど)、コネクターは再起動後に最後に停止した場所の変更データテーブルの読み取りを続行します。これにはスナップショットが含まれます。つまり、コネクターの停止時にスナップショットが完了しなかった場合、コネクターの再起動時に新しいスナップショットが開始されます。

3.2. Debezium Db2 コネクターの仕組み

Debezium Db2 コネクターを最適に設定および実行するには、コネクターによるスナップショットの実行方法、変更イベントのストリーム方法、Kafka トピック名の決定方法、およびスキーマ変更の処理方法を理解すると便利です。

詳細は以下を参照してください。

3.2.1. Debezium Db2 コネクターによるデータベーススナップショットの実行方法

Db2 のレプリケーション機能は、データベース変更の完全な履歴を保存するようには設計されていません。そのため、Debezium Db2 コネクターが初めてデータベースに接続すると、キャプチャーモードのテーブルの整合性スナップショットを作成し、この状態を Kafka にストリーミングします。これにより、テーブルの内容のベースラインが確立されます。

デフォルトでは、Db2 コネクターがスナップショットを実行すると、以下が実行されます。

  1. キャプチャーモードになっているテーブルを判断するため、スナップショットに含まれなければならないテーブルも判断されます。デフォルトでは、システム以外のテーブルはすべてキャプチャーモードになっています。table.exclude.listtable.include.list などのコネクター設定プロパティーを使用すると、キャプチャーモードである必要があるテーブルを指定できます。
  2. キャプチャーモードの各テーブルでロックを取得します。これにより、スナップショットの実行中にこれらのテーブルでスキーマの変更が発生しないようにします。ロックのレベルは、snapshot.isolation.mode コネクター設定プロパティーによって決定されます。
  3. サーバーのトランザクションログで、最大 (最新) の LSN の位置を読み取ります。
  4. キャプチャーモードになっているすべてのテーブルのスキーマをキャプチャーします。コネクターは、内部データベース履歴トピックでこの情報を永続化します。
  5. 必要に応じて、ステップ 2 で取得したロックを解放します。通常、これらのロックは短期間のみ保持されます。
  6. ステップ 3 で読み取られた LSN の位置で、コネクターはキャプチャーモードテーブルとそれらのスキーマをスキャンします。スキャン中、コネクターは以下を行います。

    1. スナップショットの開始前に、テーブルが作成されたことを確認します。そうでない場合は、スナップショットはそのテーブルをスキップします。スナップショットが完了し、コネクターが変更イベントの出力を開始した後、コネクターはスナップショットの実行中に作成されたテーブルの変更イベントを生成します。
    2. キャプチャーモードになっている各テーブルで、各行の 読み取り イベントを生成します。すべての 読み取り イベントには、LSN の位置が含まれ、これはステップ 3 で取得した LSN の位置と同じです。
    3. テーブルと同じ名前を持つ Kafka トピックに各 読み取り イベントを出力します。
  7. コネクターオフセットにスナップショットの正常な完了を記録します。

3.2.2. Debezium Db2 コネクターによる変更データテーブルの読み取り方法

スナップショットの完了後、Debezium Db2 コネクターが初めて起動すると、キャプチャーモードである各ソーステーブルの変更データテーブルを識別します。コネクターは各変更データテーブルに対して以下を行います。

  1. 最後に保存された最大 LSN から現在の最大 LSN の間に作成された変更イベントを読み取ります。
  2. 各イベントのコミット LSN および変更 LSN に従って、変更イベントを順序付けます。これにより、コネクターはテーブルが変更された順序で変更イベントを出力します。
  3. コミット LSN および変更 LSN をオフセットとして Kafka Connect に渡します。
  4. コネクターが Kafka Connect に渡した最大 LSN を保存します。

再起動後、コネクターは停止した場所でオフセット (コミット LSN および変更 LSN) から変更イベントの出力を再開します。コネクターが稼働し、変更イベントを出力している間、キャプチャーモードからテーブルを削除したり、テーブルをキャプチャーモードに追加したりすると、コネクターはこれを検出し、その動作を変更します。

3.2.3. Debezium Db2 変更イベントレコードを受信する Kafka トピックのデフォルト名

デフォルトでは、Db2 コネクターは、単一テーブルのすべての挿入、更新、および削除操作の変更イベントを単一の Kafka トピックに書き込みます。Kafka トピックの名前の形式は次のとおりです。

databaseName.schemaName.tableName

databaseName
database.server.name コネクター設定プロパティーで指定したコネクターの論理名です。
schemaName
操作が発生したスキーマの名前。
tableName
操作が発生したテーブルの名前。

たとえば、MYSCHEMA スキーマにある PRODUCTSPRODUCTS_ON_HANDCUSTOMERS、および ORDERS の 4 つのテーブルが含まれる mydatabase データベースを使用する Db2 インストールについて考えてみましょう。コネクターはイベントを以下の 4 つの Kafka トピックに出力します。

  • mydatabase.MYSCHEMA.PRODUCTS
  • mydatabase.MYSCHEMA.PRODUCTS_ON_HAND
  • mydatabase.MYSCHEMA.CUSTOMERS
  • mydatabase.MYSCHEMA.ORDERS

変更イベントを異なる名前が付けられた Kafka トピックに出力するように Db2 コネクターを設定するには、「指定したトピックへの Debezium イベントレコードのルーティング」を参照してください。

3.2.4. Debezium Db2 コネクターのスキーマ変更トピック

Debezium Db2 コネクターは、キャプチャーモードであるテーブルに対して、スキーマ変更の履歴をデータベース履歴トピックのそのテーブルに保存します。このトピックは内部コネクターの状態を反映するため、使用しないでください。アプリケーションがスキーマの変更を追跡する必要がある場合、パブリックスキーマ変更トピックがあります。スキーマ変更トピックの名前は、コネクター設定に指定された論理サーバー名と同じです。

警告

コネクターがスキーマ変更トピックに出力するメッセージの形式は、初期の状態であり、通知なしに変更される可能性があります。

Debezium は、以下の場合にスキーマ変更トピックにメッセージを出力します。

  • 新しいテーブルがキャプチャーモードになる。
  • テーブルがキャプチャーモードから削除される。
  • データベーススキーマの更新 中に、キャプチャーモードであるテーブルのスキーマが変更される。

スキーマ変更トピックへのメッセージには、テーブルスキーマの論理表現が含まれます。以下に例を示します。

{
  "schema": {
  ...
  },
  "payload": {
    "source": {
      "version": "1.5.4.Final",
      "connector": "db2",
      "name": "db2",
      "ts_ms": 1588252618953,
      "snapshot": "true",
      "db": "testdb",
      "schema": "DB2INST1",
      "table": "CUSTOMERS",
      "change_lsn": null,
      "commit_lsn": "00000025:00000d98:00a2",
      "event_serial_no": null
    },
    "databaseName": "TESTDB", 1
    "schemaName": "DB2INST1",
    "ddl": null, 2
    "tableChanges": [ 3
      {
        "type": "CREATE", 4
        "id": "\"DB2INST1\".\"CUSTOMERS\"", 5
        "table": { 6
          "defaultCharsetName": null,
          "primaryKeyColumnNames": [ 7
            "ID"
          ],
          "columns": [ 8
            {
              "name": "ID",
              "jdbcType": 4,
              "nativeType": null,
              "typeName": "int identity",
              "typeExpression": "int identity",
              "charsetName": null,
              "length": 10,
              "scale": 0,
              "position": 1,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "FIRST_NAME",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "varchar",
              "typeExpression": "varchar",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 2,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "LAST_NAME",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "varchar",
              "typeExpression": "varchar",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 3,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "EMAIL",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "varchar",
              "typeExpression": "varchar",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 4,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            }
          ]
        }
      }
    ]
  }
}

表3.1 スキーマ変更トピックに出力されたメッセージのフィールドの説明

項目フィールド名説明

1

databaseName
schemaName

変更が含まれるデータベースとスキーマを識別します。

2

ddl

Db2 コネクターの場合は常に null です。その他のコネクターでは、このフィールドにスキーマの変更を行う DDL が含まれます。この DDL は Db2 コネクターでは使用できません。

3

tableChanges

DDL コマンドによって生成されるスキーマの変更が含まれる 1 つ以上の項目の配列。

4

type

変更の種類を説明します。値は以下のいずれかになります。

  • CREATE - テーブルの作成
  • ALTER - テーブルの変更
  • DROP - テーブルの削除

5

id

作成、変更、または破棄されたテーブルの完全な識別子。

6

table

適用された変更後のテーブルメタデータを表します。

7

primaryKeyColumnNames

テーブルのプライマリーキーを構成する列のリスト。

8

columns

変更されたテーブルの各列のメタデータ。

スキーマ変更トピックへのメッセージでは、キーはスキーマの変更が含まれるデータベースの名前です。以下の例では、payload フィールドにキーが含まれます。

{
  "schema": {
    "type": "struct",
    "fields": [
      {
        "type": "string",
        "optional": false,
        "field": "databaseName"
      }
    ],
    "optional": false,
    "name": "io.debezium.connector.db2.SchemaChangeKey"
  },
  "payload": {
    "databaseName": "TESTDB"
  }
}

3.2.5. トランザクション境界を表す Debezium Db2 コネクターによって生成されたイベント

Debezium は、トランザクション境界を表し、変更データイベントメッセージをエンリッチするイベントを生成できます。Debezium はすべてのトランザクションの BEGIN および END に対して、以下のフィールドが含まれるイベントを生成します。

  • status - BEGIN または END
  • id - 一意のトランザクション識別子の文字列表現。
  • event_count (END イベントの場合) -トランザクションによって出力されたイベントの合計数。
  • data_collections (END イベントの場合): 指定のデータコレクションからの変更によって出力されたイベントの数を提供する data_collectionevent_count のペアの配列。

{
  "status": "BEGIN",
  "id": "00000025:00000d08:0025",
  "event_count": null,
  "data_collections": null
}

{
  "status": "END",
  "id": "00000025:00000d08:0025",
  "event_count": 2,
  "data_collections": [
    {
      "data_collection": "testDB.dbo.tablea",
      "event_count": 1
    },
    {
      "data_collection": "testDB.dbo.tableb",
      "event_count": 1
    }
  ]
}

コネクターはトランザクションイベントを database.server.name.transaction トピックに出力します。

データ変更イベントのエンリッチメント

トランザクションメタデータを有効にすると、コネクターは変更イベント Envelope を新しい transaction フィールドでエンリッチします。このフィールドは、複合フィールドの形式ですべてのイベントに関する情報を提供します。

  • id - 一意のトランザクション識別子の文字列表現。
  • total_order - トランザクションによって生成されたすべてのイベントを対象とするイベントの絶対位置。
  • data_collection_order - トランザクションによって出力されたすべてのイベントを対象とするイベントのデータコレクションごとの位置。

以下は、メッセージの例になります。

{
  "before": null,
  "after": {
    "pk": "2",
    "aa": "1"
  },
  "source": {
...
  },
  "op": "c",
  "ts_ms": "1580390884335",
  "transaction": {
    "id": "00000025:00000d08:0025",
    "total_order": "1",
    "data_collection_order": "1"
  }
}

3.3. Debezium Db2 コネクターのデータ変更イベントの説明

Debezium Db2 コネクターは、行レベルの INSERTUPDATE、および DELETE 操作ごとにデータ変更イベントを生成します。各イベントにはキーと値が含まれます。キーと値の構造は、変更されたテーブルによって異なります。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリーム を中心として設計されています。ただし、これらのイベントの構造は時間の経過とともに変化する可能性があり、コンシューマーによる処理が困難になることがあります。これに対応するために、各イベントにはコンテンツのスキーマが含まれます。スキーマレジストリーを使用している場合は、コンシューマーがレジストリーからスキーマを取得するために使用できるスキーマ ID が含まれます。これにより、各イベントが自己完結型になります。

以下のスケルトン JSON は、変更イベントの基本となる 4 つの部分を示しています。ただし、アプリケーションで使用するために選択した Kafka Connect コンバーターの設定方法によって、変更イベントのこれら 4 部分の表現が決定されます。schema フィールドは、変更イベントが生成されるようにコンバーターを設定した場合のみ変更イベントに含まれます。同様に、イベントキーおよびイベントペイロードは、変更イベントが生成されるようにコンバーターを設定した場合のみ変更イベントに含まれます。JSON コンバーターを使用し、変更イベントの基本となる 4 つの部分すべてを生成するように設定すると、変更イベントの構造は次のようになります。

{
 "schema": { 1
   ...
  },
 "payload": { 2
   ...
 },
 "schema": { 3
   ...
 },
 "payload": { 4
   ...
 },
}

表3.2 変更イベントの基本内容の概要

項目フィールド名説明

1

schema

最初の schema フィールドはイベントキーの一部です。イベントキーの payload の部分の内容を記述する Kafka Connect スキーマを指定します。つまり、最初の schema フィールドは、変更されたテーブルのプライマリーキーの構造、またはテーブルにプライマリーキーがない場合は固有のキーの構造を記述します。

message.key.columns コネクター設定プロパティー を設定すると、テーブルのプライマリーキーをオーバーライドできます。この場合、最初の schema フィールドはそのプロパティーによって識別されるキーの構造を記述します。

2

payload

最初の payload フィールドはイベントキーの一部です。前述の schema フィールドによって記述された構造を持ち、変更された行のキーが含まれます。

3

schema

2 つ目の schema フィールドはイベント値の一部です。イベント値の payload の部分の内容を記述する Kafka Connect スキーマを指定します。つまり、2 つ目の schema は変更された行の構造を記述します。通常、このスキーマには入れ子になったスキーマが含まれます。

4

payload

2 つ目の payload フィールドはイベント値の一部です。前述の schema フィールドによって記述された構造を持ち、変更された行の実際のデータが含まれます。

デフォルトでは、コネクターによって、変更イベントレコードがイベントの元のテーブルと同じ名前を持つトピックにストリーミングされます。トピック名 を参照してください。

警告

Debezium Db2 コネクターは、すべての Kafka Connect スキーマ名が Avro スキーマ名の形式 に準拠するようにします。つまり、論理サーバー名はアルファベットまたはアンダースコア (a-z、A-Z、または _) で始まる必要があります。論理サーバー名の残りの各文字と、データベース名とテーブル名の各文字は、アルファベット、数字、またはアンダースコア ( a-z、A-Z、0-9、または \_) でなければなりません。無効な文字がある場合は、アンダースコアに置き換えられます。

論理サーバー名、データベース名、またはテーブル名に無効な文字が含まれ、名前を区別する唯一の文字が無効であると、無効な文字はすべてアンダースコアに置き換えられるため、予期せぬ競合が発生する可能性があります。

また、データベース、スキーマ、およびテーブルの Db2 名では、大文字と小文字を区別することができます。つまり、コネクターは同じ Kafka トピックに複数のテーブルのイベントレコードを出力できます。

詳細は以下を参照してください。

3.3.1. Debezium Db2 変更イベントのキーについて

変更イベントのキーには、変更されたテーブルのキーのスキーマと、変更された行の実際のキーのスキーマが含まれます。スキーマとそれに対応するペイロードの両方には、コネクターによってイベントが作成された時点において、変更されたテーブルの PRIMARY KEY (または一意な制約) に存在した各列のフィールドが含まれます。

以下の customers テーブルについて考えてみましょう。この後に、このテーブルの変更イベントキーの例を示します。

テーブルの例

CREATE TABLE customers (
 ID INTEGER IDENTITY(1001,1) NOT NULL PRIMARY KEY,
 FIRST_NAME VARCHAR(255) NOT NULL,
 LAST_NAME VARCHAR(255) NOT NULL,
 EMAIL VARCHAR(255) NOT NULL UNIQUE
);

変更イベントキーの例

customers テーブルへの変更をキャプチャーする変更イベントのすべてに、イベントキースキーマがあります。customers テーブルに前述の定義がある限り、customers テーブルへの変更をキャプチャーする変更イベントのキー構造はすべて以下のようになります。JSON では、以下のようになります。

{
    "schema": {  1
        "type": "struct",
        "fields": [  2
            {
                "type": "int32",
                "optional": false,
                "field": "ID"
            }
        ],
        "optional": false,  3
        "name": "mydatabase.MYSCHEMA.CUSTOMERS.Key"  4
    },
    "payload": {  5
        "ID": 1004
    }
}

表3.3 変更イベントキーの説明

項目フィールド名説明

1

schema

キーのスキーマ部分は、キーの payload 部分の内容を記述する Kafka Connect スキーマを指定します。

2

fields

各フィールドの名前、型、および必要かどうかなど、payload で想定される各フィールドを指定します。

3

optional

イベントキーの payload フィールドに値が含まれる必要があるかどうかを示します。この例では、キーのペイロードに値が必要です。テーブルにプライマリーキーがない場合は、キーの payload フィールドの値は任意です。

4

mydatabase.MYSCHEMA.CUSTOMERS.Key

キーのペイロードの構造を定義するスキーマの名前。このスキーマは、変更されたテーブルのプライマリーキーの構造を記述します。キースキーマ名の形式は connector-name.database-name.table-name.Key です。この例では、以下のようになります。

  • mydatabase はこのイベントを生成したコネクターの名前です。
  • MYSCHEMA は変更されたテーブルが含まれるデータベーススキーマです。
  • CUSTOMERS は更新されたテーブルです。

5

payload

この変更イベントが生成された行のキーが含まれます。この例では、キーには値が 1004 の 1 つの ID フィールドが含まれます。

3.3.2. Debezium Db2 変更イベントの値

変更イベントの値はキーよりも若干複雑です。キーと同様に、値には schema セクションと payload セクションがあります。schema セクションには、入れ子のフィールドを含む、payload セクションの Envelope 構造を記述するスキーマが含まれています。データを作成、更新、または削除する操作のすべての変更イベントには、Envelope 構造を持つ値 payload があります。

変更イベントキーの例を紹介するために使用した、同じサンプルテーブルについて考えてみましょう。

テーブルの例

CREATE TABLE customers (
 ID INTEGER IDENTITY(1001,1) NOT NULL PRIMARY KEY,
 FIRST_NAME VARCHAR(255) NOT NULL,
 LAST_NAME VARCHAR(255) NOT NULL,
 EMAIL VARCHAR(255) NOT NULL UNIQUE
);

customers テーブルのすべての変更イベントのイベント値部分は同じスキーマを指定します。イベント値のペイロードは、イベント型によって異なります。

作成 イベント

以下の例は、customers テーブルにデータを作成する操作に対して、コネクターによって生成される変更イベントの値の部分を示しています。

{
  "schema": {  1
    "type": "struct",
    "fields": [
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "ID"
          },
          {
            "type": "string",
            "optional": false,
            "field": "FIRST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "LAST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "EMAIL"
          }
        ],
        "optional": true,
        "name": "mydatabase.MYSCHEMA.CUSTOMERS.Value",  2
        "field": "before"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "ID"
          },
          {
            "type": "string",
            "optional": false,
            "field": "FIRST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "LAST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "EMAIL"
          }
        ],
        "optional": true,
        "name": "mydatabase.MYSCHEMA.CUSTOMERS.Value",
        "field": "after"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "string",
            "optional": false,
            "field": "version"
          },
          {
            "type": "string",
            "optional": false,
            "field": "connector"
          },
          {
            "type": "string",
            "optional": false,
            "field": "name"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "ts_ms"
          },
          {
            "type": "boolean",
            "optional": true,
            "default": false,
            "field": "snapshot"
          },
          {
            "type": "string",
            "optional": false,
            "field": "db"
          },
          {
            "type": "string",
            "optional": false,
            "field": "schema"
          },
          {
            "type": "string",
            "optional": false,
            "field": "table"
          },
          {
            "type": "string",
            "optional": true,
            "field": "change_lsn"
          },
          {
            "type": "string",
            "optional": true,
            "field": "commit_lsn"
          },
        ],
        "optional": false,
        "name": "io.debezium.connector.db2.Source",  3
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "mydatabase.MYSCHEMA.CUSTOMERS.Envelope"  4
  },
  "payload": {  5
    "before": null,  6
    "after": {  7
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "john.doe@example.org"
    },
    "source": {  8
      "version": "1.5.4.Final",
      "connector": "db2",
      "name": "myconnector",
      "ts_ms": 1559729468470,
      "snapshot": false,
      "db": "mydatabase",
      "schema": "MYSCHEMA",
      "table": "CUSTOMERS",
      "change_lsn": "00000027:00000758:0003",
      "commit_lsn": "00000027:00000758:0005",
    },
    "op": "c",  9
    "ts_ms": 1559729471739  10
  }
}

表3.4 作成 イベント値フィールドの説明

項目フィールド名説明

1

schema

値のペイロードの構造を記述する、値のスキーマ。変更イベントの値スキーマは、コネクターが特定のテーブルに生成するすべての変更イベントで同じになります。

2

name

schema セクションで、各 name フィールドは、値のペイロードのフィールドに対するスキーマを指定します。

mydatabase.MYSCHEMA.CUSTOMERS.Value はペイロードの before および after フィールドのスキーマです。このスキーマは customers テーブルに固有です。コネクターは、MYSCHEMA.CUSTOMERS テーブルのすべての行にこのスキーマを使用します。

before および after フィールドのスキーマ名は logicalName.schemaName.tableName.Value の形式で、スキーマ名がデータベースで一意になるようにします。つまり、Avro コンバーター を使用する場合、各論理ソースの各テーブルの Avro スキーマには独自の進化と履歴があります。

3

name

io.debezium.connector.db2.Source はペイロードの source フィールドのスキーマです。このスキーマは Db2 コネクターに固有です。コネクターは生成するすべてのイベントにこれを使用します。

4

name

mydatabase.MYSCHEMA.CUSTOMERS.Envelope は、ペイロードの全体的な構造のスキーマです。mydatabase はデータベース、MYSCHEMA はスキーマ、CUSTOMERS はテーブルです。

5

payload

値の実際のデータ。これは、変更イベントが提供する情報です。

イベントの JSON 表現はそれが記述する行よりもはるかに大きいように見えることがあります。これは、JSON 表現にはメッセージのスキーマ部分とペイロード部分を含める必要があるためです。しかし、Avro コンバーター を使用すると、コネクターが Kafka トピックにストリーミングするメッセージのサイズを大幅に小さくすることができます。

6

before

イベント発生前の行の状態を指定する任意のフィールド。この例のように、op フィールドが create (作成) の c である場合、この変更イベントは新しい内容に対するものであるため、beforenull になります。

7

after

イベント発生後の行の状態を指定する任意のフィールド。この例では、after フィールドには新しい行の IDFIRST_NAMELAST_NAME、および EMAIL 列の値が含まれます。

8

source

イベントのソースメタデータを記述する必須のフィールド。source 構造には、この変更に関する Db2 の情報が示され、トレーサビリティーが提供されます。また、同じトピックや他のトピックの他のイベントと比較する情報もあり、このイベントが他のイベントの前または後に発生したか、あるいはこのイベントが他のイベントと同じコミットの一部であるかを認識できます。ソースメタデータには以下が含まれています。

  • Debezium バージョン
  • コネクター型および名前
  • データベースに変更が加えられた時点のタイムスタンプ
  • イベントが進行中のスナップショットの一部であるかどうか
  • 新しい行が含まれるデータベース、スキーマ、およびテーブルの名前
  • 変更 LSN
  • コミット LSN (このイベントがスナップショットの一部である場合は省略)

9

op

コネクターによってイベントが生成される原因となった操作の型を記述する必須文字列。この例では、c は操作によって行が作成されたことを示しています。有効な値は次のとおりです。

  • c = create (作成)
  • u = update (更新)
  • d = delete (削除)
  • r = read (読み取り、スナップショットのみに適用)

10

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

更新イベント

サンプル customers テーブルにある更新の変更イベントの値には、そのテーブルの 作成 イベントと同じスキーマがあります。同様に、更新イベント値のペイロードは同じ構造を持ちます。ただし、イベント値ペイロードでは 更新 イベントに異なる値が含まれます。以下は、コネクターによって customers テーブルでの更新に生成されるイベントの変更イベント値の例になります。

{
  "schema": { ... },
  "payload": {
    "before": {  1
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "john.doe@example.org"
    },
    "after": {  2
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "noreply@example.org"
    },
    "source": {  3
      "version": "1.5.4.Final",
      "connector": "db2",
      "name": "myconnector",
      "ts_ms": 1559729995937,
      "snapshot": false,
      "db": "mydatabase",
      "schema": "MYSCHEMA",
      "table": "CUSTOMERS",
      "change_lsn": "00000027:00000ac0:0002",
      "commit_lsn": "00000027:00000ac0:0007",
    },
    "op": "u",  4
    "ts_ms": 1559729998706  5
  }
}

表3.5 更新 イベント値フィールドの説明

項目フィールド名説明

1

before

イベント発生前の行の状態を指定する任意のフィールド。更新 イベント値の before フィールドには、各テーブル列のフィールドと、データベースのコミット前にその列にあった値が含まれます。この例では、EMAIL の値が john.doe@example.com であることに注意してください。

2

after

イベント発生後の行の状態を指定する任意のフィールド。beforeafter の構造を比較すると、この行への更新内容を判断できます。この例では、EMAIL の値は noreply@example.com になりました。

3

source

イベントのソースメタデータを記述する必須のフィールド。source フィールド構造には create イベントと同じフィールドが含まれますが、一部の値が異なります。たとえば、更新 イベントサンプルの LSN は異なります。この情報を使用して、このイベントを他のイベントと比較し、このイベントが他のイベントの前または後に発生したか、あるいはこのイベントが他のイベントと同じコミットの一部であるかを認識できます。ソースメタデータには以下が含まれています。

  • Debezium バージョン
  • コネクター型および名前
  • データベースに変更が加えられた時点のタイムスタンプ
  • イベントが進行中のスナップショットの一部であるかどうか
  • 新しい行が含まれるデータベース、スキーマ、およびテーブルの名前
  • 変更 LSN
  • コミット LSN (このイベントがスナップショットの一部である場合は省略)

4

op

操作の型を記述する必須の文字列。更新 イベントの値では、op フィールドの値は u で、更新によってこの行が変更したことを示します。

5

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

注記

行のプライマリーキー/一意キーの列を更新すると、行のキーの値が変更されます。キーが変更されると、3 つ のイベントが Debezium によって出力されます。3 つのイベントとは、DELETE イベント、行の古いキーを持つ 廃棄 (tombstone)、およびそれに続く行の新しいキーを持つイベントです。

削除 イベント

削除 変更イベントの値は、同じテーブルの 作成 および 更新 イベントと同じ schema の部分になります。サンプル customers テーブルの 削除 イベントのイベント値 payload は以下のようになります。

{
  "schema": { ... },
  },
  "payload": {
    "before": {  1
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "noreply@example.org"
    },
    "after": null,  2
    "source": {  3
      "version": "1.5.4.Final",
      "connector": "db2",
      "name": "myconnector",
      "ts_ms": 1559730445243,
      "snapshot": false,
      "db": "mydatabase",
      "schema": "MYSCHEMA",
      "table": "CUSTOMERS",
      "change_lsn": "00000027:00000db0:0005",
      "commit_lsn": "00000027:00000db0:0007"
    },
    "op": "d",  4
    "ts_ms": 1559730450205  5
  }
}

表3.6 削除 イベント値フィールドの説明

項目フィールド名説明

1

before

イベント発生前の行の状態を指定する任意のフィールド。削除 イベント値の before フィールドには、データベースのコミットで削除される前に行にあった値が含まれます。

2

after

イベント発生後の行の状態を指定する任意のフィールド。削除 イベント値の after フィールドは null で、行が存在しないことを示します。

3

source

イベントのソースメタデータを記述する必須のフィールド。削除 イベント値の source フィールド構造は、同じテーブルの 作成 および 更新 イベントと同じになります。多くの source フィールドの値も同じです。削除 イベント値では、ts_ms および LSN フィールドの値や、その他の値が変更された可能性があります。ただし、削除 イベント値の source フィールドは、同じメタデータを提供します。

  • Debezium バージョン
  • コネクター型および名前
  • データベースに変更が加えられた時点のタイムスタンプ
  • イベントが進行中のスナップショットの一部であるかどうか
  • 新しい行が含まれるデータベース、スキーマ、およびテーブルの名前
  • 変更 LSN
  • コミット LSN (このイベントがスナップショットの一部である場合は省略)

4

op

操作の型を記述する必須の文字列。op フィールドの値は d で、行が削除されたことを示します。

5

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

削除 変更イベントレコードは、この行の削除を処理するために必要な情報を持つコンシューマーを提供します。コンシューマーによっては、削除を適切に処理するために古い値が必要になることがあるため、古い値が含まれます。

Db2 コネクターイベントは、Kafka のログコンパクション と動作するように設計されています。ログコンパクションにより、少なくとも各キーの最新のメッセージが保持される限り、一部の古いメッセージを削除できます。これにより、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できるようにするとともに、Kafka がストレージ領域を確保できるようにします。

行が削除された場合でも、Kafka は同じキーを持つ以前のメッセージをすべて削除できるため、削除 イベントの値はログコンパクションで動作します。ただし、Kafka が同じキーを持つすべてのメッセージを削除するには、メッセージの値が null である必要があります。これを可能にするために、Debezium の Db2 コネクターは 削除 イベントを出力した後に、同じキーと null の値を持つ特別な廃棄 (tombstone) イベントを出力します。

3.4. Debezium Db2 コネクターによるデータ型のマッピング方法

Db2 のデータ型の説明は「Db2 SQL Data Types」を参照してください。

Db2 コネクターは、行が存在するテーブルのように構造化されたイベントで行への変更を表します。イベントには、各列の値のフィールドが含まれます。その値がどのようにイベントで示されるかは、列の Db2 のデータ型によって異なります。ここでは、これらのマッピングについて説明します。

詳細は以下を参照してください。

基本型

以下の表では、各 Db2 データ型をイベントフィールドの リテラル型 および セマンティック型にマッピングする方法を説明します。

  • リテラル型 は、Kafka Connect スキーマ型 INT8INT16INT32INT64FLOAT32FLOAT64BOOLEANSTRINGBYTESARRAYMAP、および STRUCT を使用して、値を表す方法を記述します。
  • セマンティック型 は、フィールドの Kafka Connect スキーマの名前を使用して、Kafka Connect スキーマがフィールドの 意味 をキャプチャーする方法を記述します。

表3.7 Db2 の基本データ型のマッピング

DB2 データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

BOOLEAN

BOOLEAN

BOOLEAN 型の列のあるテーブルからのみスナップショットを作成できます。現在、Db2 での SQL レプリケーションは BOOLEAN をサポートしないため、Debezium はこれらのテーブルで CDC を実行できません。別の型の使用を検討してください。

BIGINT

INT64

該当なし

BINARY

BYTES

該当なし

BLOB

BYTES

該当なし

CHAR[(N)]

STRING

該当なし

CLOB

STRING

該当なし

DATE

INT32

io.debezium.time.Date

タイムゾーン情報のないタイムスタンプの文字列表現

DECFLOAT

BYTES

org.apache.kafka.connect.data.Decimal

DECIMAL

BYTES

org.apache.kafka.connect.data.Decimal

DBCLOB

STRING

該当なし

DOUBLE

FLOAT64

該当なし

INTEGER

INT32

該当なし

REAL

FLOAT32

該当なし

SMALLINT

INT16

該当なし

TIME

INT32

io.debezium.time.Time

タイムゾーン情報のない時間の文字列表現

TIMESTAMP

INT64

io.debezium.time.MicroTimestamp

タイムゾーン情報のないタイムスタンプの文字列表現

VARBINARY

BYTES

該当なし

VARCHAR[(N)]

STRING

該当なし

VARGRAPHIC

STRING

該当なし

XML

STRING

io.debezium.data.Xml

XML ドキュメントの文字列表現

列のデフォルト値がある場合は、対応するフィールドの Kafka Connect スキーマに伝達されます。明示的な列値が指定されない限り、変更イベントにはフィールドのデフォルト値が含まれます。そのため、スキーマからデフォルト値を取得する必要はほとんどありません。

時間型

タイムゾーン情報が含まれる Db2 の DATETIMEOFFSET データ型以外に、時間型がマッピングされる仕組みは time.precision.mode コネクター設定プロパティーの値によって異なります。ここでは、以下のマッピングについて説明します。

time.precision.mode=adaptive

time.precision.mode 設定プロパティーがデフォルトの adaptive に設定された場合、コネクターは列のデータ型定義に基づいてリテラル型とセマンティック型を決定します。これにより、イベントがデータベースの値を 正確 に表すようになります。

表3.8 time.precision.modeadaptive の場合のマッピング

DB2 データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

DATE

INT32

io.debezium.time.Date

エポックからの日数を表します。

TIME(0), TIME(1), TIME(2), TIME(3)

INT32

io.debezium.time.Time

午前 0 時から経過した時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIME(4), TIME(5), TIME(6)

INT64

io.debezium.time.MicroTime

午前 0 時から経過した時間をマイクロ秒で表し、タイムゾーン情報は含まれません。

TIME(7)

INT64

io.debezium.time.NanoTime

午前 0 時から経過した時間をナノ秒で表し、タイムゾーン情報は含まれません。

DATETIME

INT64

io.debezium.time.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

SMALLDATETIME

INT64

io.debezium.time.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

DATETIME2(0), DATETIME2(1), DATETIME2(2), DATETIME2(3)

INT64

io.debezium.time.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

DATETIME2(4), DATETIME2(5), DATETIME2(6)

INT64

io.debezium.time.MicroTimestamp

エポックからの経過時間をマイクロ秒で表し、タイムゾーン情報は含まれません。

DATETIME2(7)

INT64

io.debezium.time.NanoTimestamp

エポックからの経過時間をナノ秒で表し、タイムゾーン情報は含まれません。

time.precision.mode=connect

time.precision.mode 設定プロパティーが connect に設定された場合、コネクターは Kafka Connect の論理型を使用します。これは、コンシューマーが組み込みの Kafka Connect の論理型のみを処理でき、可変精度の時間値を処理できない場合に便利です。ただし、Db2 はマイクロ秒の 10 分の 1 の精度をサポートするため、connect 時間精度を指定してコネクターによって生成されたイベントは、データベース列の少数秒の精度値が 3 よりも大きい場合に、精度が失われます

表3.9 time.precision.modeconnect の場合のマッピング

DB2 データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

DATE

INT32

org.apache.kafka.connect.data.Date

エポックからの日数を表します。

TIME([P])

INT64

org.apache.kafka.connect.data.Time

午前 0 時からの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。Db2 では、範囲 が 0 - 7 の P が許可され、マイクロ秒の 10 分の 1 の精度まで保存されますが、P が 3 よりも大きい場合は、このモードでは精度が失われます。

DATETIME

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

SMALLDATETIME

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

DATETIME2

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。Db2 では、範囲 が 0 - 7 の P が許可され、マイクロ秒の 10 分の 1 の精度まで保存されますが、P が 3 よりも大きい場合は、このモードでは精度が失われます。

タイムスタンプ型

DATETIMESMALLDATETIME、および DATETIME2 型は、タイムゾーン情報のないタイムスタンプを表します。このような列は、UTC を基にして同等の Kafka Connect 値に変換されます。たとえば、「2018-06-20 15:13:16.945104」という DATETIME2 の値は、io.debezium.time.MicroTimestamp によって「1529507596945104」という値が示されます。

Kafka Connect および Debezium を実行している JVM のタイムゾーンは、この変換には影響しません。

表3.10 10 進数型

DB2 データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

NUMERIC[(P[,S])]

BYTES

org.apache.kafka.connect.data.Decimal

scale スキーマパラメーターには、小数点を移動した桁数を表す整数が含まれます。connect.decimal.precision スキーマパラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

DECIMAL[(P[,S])]

BYTES

org.apache.kafka.connect.data.Decimal

scale スキーマパラメーターには、小数点を移動した桁数を表す整数が含まれます。connect.decimal.precision スキーマパラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

SMALLMONEY

BYTES

org.apache.kafka.connect.data.Decimal

scale スキーマパラメーターには、小数点を移動した桁数を表す整数が含まれます。connect.decimal.precision スキーマパラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

MONEY

BYTES

org.apache.kafka.connect.data.Decimal

scale スキーマパラメーターには、小数点を移動した桁数を表す整数が含まれます。connect.decimal.precision スキーマパラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

3.5. Debezium コネクターを実行するための Db2 の設定

Db2 テーブルにコミットされた変更イベントを Debezium がキャプチャーするには、必要な権限を持つ Db2 データベース管理者が、変更データキャプチャー (CDC) のデータベースでテーブルを設定する必要があります。Debezium の実行を開始した後、キャプチャーエージェントの設定を調整してパフォーマンスを最適化できます。

Debezium コネクターと使用するために Db2 を設定する場合の詳細は、以下を参照してください。

3.5.1. 変更データキャプチャーの Db2 テーブルの設定

テーブルをキャプチャーモードにするために、Debezium ではユーザー定義関数 (UDF) のセットが提供されます。ここでは、これらの管理 UDF をインストールおよび実行する手順を説明します。また、Db2 制御コマンドを実行してテーブルをキャプチャーモードにすることもできます。管理者は、Debezium がキャプチャーする各テーブルの CDC を有効にする必要があります。

前提条件

  • db2instl ユーザーとして Db2 にログインしている。
  • Db2 ホストの $HOME/asncdctools/src ディレクトリーで Debezium 管理 UDF を使用できる。UDF は Debezium サンプルリポジトリーから入手できます。

手順

  1. Db2 で提供される bldrtn コマンドを使用して、Db2 サーバーホストで Debezium 管理 UDF をコンパイルします。

    cd $HOME/asncdctools/src
    ./bldrtn asncdc
  2. データベースが稼働していない場合は起動します。DB_NAME は、Debezium が接続するデータベースの名前に置き換えます。

    db2 start db DB_NAME
  3. JDBC が Db2 メタデータカタログを読み取りできるようにします。

    cd $HOME/sqllib/bnd
    db2 bind db2schema.bnd blocking all grant public sqlerror continue
  4. データベースが最近バックアップされたことを確認します。ASN エージェントには、読み取りを始める最新の開始点が必要です。バックアップを実行する必要がある場合は、以下のコマンドを実行して、最新のバージョンのみを利用できるようにデータをプルーニングします。古いバージョンのデータを保持する必要がない場合は、バックアップの場所に dev/null を指定します。

    1. データベースをバックアップします。DB_NAME および BACK_UP_LOCATION を適切な値に置き換えます。

      db2 backup db DB_NAME to BACK_UP_LOCATION
    2. データベースを再起動します。

      db2 restart db DB_NAME
  5. データベースに接続して、Debezium 管理 UDF をインストールします。db2instl ユーザーとしてログインしていることを前提とするため、UDF が db2inst1 ユーザーにインストールされている必要があります。

    db2 connect to DB_NAME
  6. Debezium 管理 UDF をコピーし、その権限を設定します。

    cp $HOME/asncdctools/src/asncdc $HOME/sqllib/function
    chmod 777 $HOME/sqllib/function
  7. ASN キャプチャーエージェントを開始および停止する Debezium UDF を有効にします。

    db2 -tvmf $HOME/asncdctools/src/asncdc_UDF.sql
  8. ASN 制御テーブルを作成します。

    $ db2 -tvmf $HOME/asncdctools/src/asncdctables.sql
  9. テーブルをキャプチャーモードに追加し、キャプチャーモードからテーブルを削除する Debezium UDF を有効にします。

    $ db2 -tvmf $HOME/asncdctools/src/asncdcaddremove.sql

    Db2 サーバーを設定したら、UDF を使用して SQL コマンドで Db2 レプリケーション (ASN) を制御します。UDF によっては戻り値が必要な場合があります。この場合、SQL の VALUE ステートメントを使用して呼び出します。その他の UDF には、SQL の CALL ステートメントを使用します。

  10. ASN エージェントを起動します。

    VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');
  11. テーブルをキャプチャーモードにします。キャプチャーする各テーブルに対して、以下のステートメントを呼び出します。MYSCHEMA を、キャプチャーモードにするテーブルが含まれるスキーマの名前に置き換えます。同様に、MYTABLE を、キャプチャーモードにするテーブルの名前に置き換えます。

    CALL ASNCDC.ADDTABLE('MYSCHEMA', 'MYTABLE');
  12. ASN サービスを再初期化します。

    VALUES ASNCDC.ASNCDCSERVICES('reinit','asncdc');

3.5.2. Db2 キャプチャーエージェント設定のサーバー負荷およびレイテンシーへの影響

データベース管理者がソーステーブルに対して変更データキャプチャーを有効にすると、キャプチャーエージェントの実行が開始されます。エージェントは新しい変更イベントレコードをトランザクションログから読み取り、イベントレコードをキャプチャーテーブルに複製します。変更がソーステーブルにコミットされてから、対応する変更テーブルに変更が反映される間、常に短いレイテンシーが間隔で発生します。この遅延間隔は、ソーステーブルで変更が発生したときから、Debezium がその変更を Apache Kafka にストリーミングできるようになるまでの差を表します。

データの変更に素早く対応する必要があるアプリケーションについては、ソースとキャプチャーテーブル間で密接に同期を維持するのが理想的です。キャプチャーエージェントを実行してできるだけ迅速に変更イベントを継続的に処理すると、スループットが増加し、レイテンシーが減少するため、イベントの発生後にほぼリアルタイムで新しいイベントレコードが変更テーブルに入力されることを想像するかもしれません。しかし、これは必ずしもそうであるとは限りません。同期を即時に行うとパフォーマンスに影響します。変更エージェントが新しいイベントレコードについてデータベースにクエリーを実行するたびに、データベースホストの CPU 負荷が増加します。サーバーへの負荷が増えると、データベース全体のパフォーマンスに悪影響を及ぼす可能性があり、特にデータベースの使用がピークに達するときにトランザクションの効率が低下する可能性があります。

データベースメトリクスを監視して、サーバーがキャプチャーエージェントのアクティビティーをサポートできなくなるレベルにデータベースが達した場合に認識できるようにすることが重要となります。キャプチャーエージェントの実行中にパフォーマンスの問題が発生した場合は、キャプチャーエージェント設定を調整して CPU の負荷を減らします。

3.5.3. DB2 キャプチャーエージェントの設定パラメーター

Db2 では、IBMSNAP_CAPPARMS テーブルにはキャプチャーエージェントの動作を制御するパラメーターが含まれています。これらのパラメーターの値を調整して、キャプチャープロセスの設定を調整すると、CPU の負荷を減らしながら許容レベルのレイテンシーを維持することができます。

注記

Db2 のキャプチャーエージェントパラメーターの設定方法に関する具体的なガイダンスは、本書の範囲外となります。

IBMSNAP_CAPPARMS テーブルでは、CPU 負荷の削減に最も影響を与えるパラメーターは以下のとおりです。

COMMIT_INTERVAL
  • キャプチャーエージェントがデータを変更データテーブルにコミットするまで待つ期間を秒単位で指定します。
  • 値が大きいほど、データベースホストの負荷が減少し、レイテンシーが増加します。
  • デフォルト値は 30 です。
SLEEP_INTERVAL
  • キャプチャーエージェントがアクティブなトランザクションログの最後に到達した後に、新しいコミットサイクルの開始まで待つ期間を秒単位で指定します。
  • 値が大きいほど、サーバーの負荷が減少し、レイテンシーが増加します。
  • デフォルト値は 5 です。

その他のリソース

  • キャプチャーエージェントパラメーターの詳細は、Db2 のドキュメントを参照してください。

3.6. Debezium Db2 コネクターのデプロイ

Debezium Db2 コネクターをデプロイするには、コネクターファイルを Kafka Connect に追加し、コネクターを実行するカスタムコンテナーを作成して、続いてコネクター設定をコンテナーに追加します。Debezium Db2 コネクターのデプロイに関する詳細は、以下を参照してください。

3.6.1. Debezium Db2 コネクターのデプロイ

Debezium Db2 コネクターをデプロイするには、Debezium コネクターアーカイブが含まれるカスタム Kafka Connect コンテナーイメージをビルドし、続いてこのコンテナーイメージをコンテナーレジストリーにプッシュする必要があります。その後、以下のカスタムリソース (CR) を作成する必要があります。

  • Kafka Connect インスタンスを定義する KafkaConnect CR。CR の image プロパティーは、Debezium コネクターを実行するために作成するコンテナーイメージの名前を指定します。この CR を、Red Hat AMQ Streams がデプロイされている OpenShift インスタンスに適用します。AMQ Streams は、Apache Kafka を OpenShift に取り入れる Operator およびイメージを提供します。
  • Debezium Db2 コネクターを定義する KafkaConnector CR。この CR を KafkaConnect CR を適用したのと同じ OpenShift インスタンスに適用します。

前提条件

  • Db2 が稼働状態にあり、Debezium コネクターと連携するように Db2 を設定する 手順を完了している必要があります。
  • AMQ Streams が OpenShift にデプロイされ、Apache Kafka および Kafka Connect を実行している。詳細は、『Deploying and Upgrading AMQ Streams on OpenShift』を参照してください。
  • Podman または Docker がインストールされている。
  • Debezium コネクターを実行するコンテナーを追加する予定のコンテナーレジストリー (quay.iodocker.io など) でコンテナーを作成および管理するアカウントとパーミッションを持っている。

手順

  1. Kafka Connect の Debezium Db2 コンテナーを作成します。

    1. Debezium Db2 コネクターアーカイブ をダウンロードします。
    2. Debezium Db2 コネクターアーカイブを展開して、コネクタープラグインのディレクトリー構造を作成します。以下に例を示します。

      ./my-plugins/
      ├── debezium-connector-db2
      │   ├── ...
    3. registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0 をベースイメージとして使用する Docker ファイルを作成します。たとえば、ターミナルウィンドウに以下を入力し、my-plugins をプラグインディレクトリーの名前に置き換えます。

      cat <<EOF >debezium-container-for-db2.yaml 1
      FROM registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0
      USER root:root
      COPY ./<my-plugins>/ /opt/kafka/plugins/ 2
      USER 1001
      EOF
      1 1 1 1 1 1 1
      任意のファイル名を指定できます。
      2 2 2 2 2 2 2
      my-plugins をプラグインディレクトリーの名前に置き換えます。

      このコマンドは、現在のディレクトリーに debezium-container-for-db2.yaml という名前の Docker ファイルを作成します。

    4. 前のステップで作成した debezium-container-for-db2.yaml Docker ファイルからコンテナーイメージをビルドします。ファイルを含むディレクトリーから、ターミナルウィンドウを開き、以下のコマンドのいずれかを入力します。

      podman build -t debezium-container-for-db2:latest .
      docker build -t debezium-container-for-db2:latest .

      上記のコマンドは、debezium-container-for-db2 という名前のコンテナーイメージをビルドします。

    5. カスタムイメージを quay.io などのコンテナーレジストリーまたは内部のコンテナーレジストリーにプッシュします。コンテナーレジストリーは、イメージをデプロイする OpenShift インスタンスで利用できる必要があります。以下のいずれかのコマンドを実行します。

      podman push <myregistry.io>/debezium-container-for-db2:latest
      docker push <myregistry.io>/debezium-container-for-db2:latest
    6. 新しい Debezium Db2 KafkaConnect カスタムリソース (CR) を作成します。たとえば、以下の例のように、annotations および image プロパティーを指定する dbz-connect.yaml という名前の KafkaConnect CR を作成します。

      apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnect
      metadata:
        name: my-connect-cluster
        annotations:
          strimzi.io/use-connector-resources: "true" 1
      spec:
        #...
        image: debezium-container-for-db2  2
      1
      KafkaConnector リソースはこの Kafka Connect クラスターでコネクターを設定するために使用されることを、metadata.annotations は Cluster Operator に示します。
      2
      spec.image は Debezium コネクターを実行するために作成したイメージの名前を指定します。このプロパティーによって Cluster Operator の STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 変数がオーバーライドされます。
    7. 以下のコマンドを入力して、KafkaConnect CR を OpenShift Kafka Connect 環境に適用します。

      oc create -f dbz-connect.yaml

      このコマンドは、Debezium コネクターを実行するために作成したイメージの名前を指定する Kafka Connect インスタンスを追加します。

  2. Debezium Db2 コネクターインスタンスを設定する KafkaConnector カスタムリソースを作成します。

    コネクターの設定プロパティーを指定する .yaml ファイルで Debezium Db2 コネクターを設定します。コネクター設定は、Debezium に対して、スキーマおよびテーブルのサブセットにイベントを生成するよう指示する可能性があり、または機密性の高い、大きすぎる、または不必要な指定のコラムで Debezium が値を無視、マスク、または切り捨てするようにプロパティーを設定する可能性もあります。

    以下の例では、ポート 50000 で Db2 サーバーホスト 192.168.99.100 に接続する Debezium コネクターを設定します。このホストには mydatabase という名前のデータベースと inventory という名前のテーブルがあり、fulfillment はサーバーの論理名です。

    Db2 inventory-connector.yaml

    apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnector
      metadata:
        name: inventory-connector  1
        labels:
          strimzi.io/cluster: my-connect-cluster
        annotations:
          strimzi.io/use-connector-resources: 'true'
      spec:
        class: io.debezium.connector.db2.Db2Connector 2
        tasksMax: 1  3
        config:  4
          database.hostname: 192.168.99.100   5
          database.port: 50000 6
          database.user: db2inst1 7
          database.password: Password! 8
          database.dbname: mydatabase 9
          database.server.name: fullfillment   10
          database.include.list: public.inventory   11

    表3.11 コネクター設定の説明

    項目説明

    1

    Kafka Connect クラスターに登録する場合のコネクターの名前。

    2

    この Db2 コネクタークラスの名前。

    3

    1 度に 1 つのタスクのみが動作する必要があります。

    4

    コネクターの設定。

    5

    Db2 インスタンスのアドレスであるデータベースホスト。

    6

    Db2 インスタンスのポート番号。

    7

    Db2 ユーザーの名前。

    8

    Db2 ユーザーのパスワード。

    9

    変更をキャプチャーするデータベースの名前。

    10

    namespace を形成する Db2 インスタンス/クラスターの論理名で、コネクターが書き込む Kafka トピックの名前、Kafka Connect スキーマ名、および Arvo コネクター が使用される場合に対応する Avro スキーマの namespace のすべてに使用されます。

    11

    Debezium が変更をキャプチャーする必要があるすべてのテーブルのリスト。

  3. Kafka Connect でコネクターインスタンスを作成します。たとえば、KafkaConnector リソースを inventory-connector.yaml ファイルに保存した場合は、以下のコマンドを実行します。

    oc apply -f inventory-connector.yaml

    上記のコマンドにより inventory-connector が登録され、コネクターは KafkaConnector CR で定義された mydatabase データベースに対して実行を開始します。

  4. コネクターが作成され、起動されたことを確認します。

    1. Kafka Connect ログ出力を表示して、コネクターが作成され、指定データベースの変更のキャプチャーが開始されたことを確認します。

      oc logs $(oc get pods -o name -l strimzi.io/cluster=my-connect-cluster)
    2. ログの出力を確認し、Debezium が初回のスナップショットを実行することを確認します。ログには、以下のメッセージと同様の出力が表示されます。

      ... INFO Starting snapshot for ...
      ... INFO Snapshot is using user 'debezium' ...

      コネクターがエラーがなく正常に起動すると、コネクターが変更をキャプチャーする各テーブルのトピックが作成されます。CR のサンプルでは、include.list プロパティーに指定されたテーブルのトピックがあります。ダウンストリームアプリケーションは、これらのトピックをサブスクライブできます。

    3. 以下のコマンドを実行して、コネクターによってトピックが作成されたことを検証します。

      oc get kafkatopics

Debezium Db2 コネクターに設定できる設定プロパティーの完全リストは、「Db2 コネクタープロパティー」を参照してください。

結果

コネクターが起動すると、コネクターが変更をキャプチャーするように設定された Db2 データベーステーブルの 整合性スナップショット が実行されます。その後、コネクターは行レベルの操作のデータ変更イベントの生成を開始し、変更イベントレコードを Kafka トピックにストリーミングします。

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

Debezium Db2 コネクターには、アプリケーションに適したコネクター動作を実現するために使用できる設定プロパティーが多数あります。多くのプロパティーにはデフォルト値があります。プロパティーに関する情報は、以下のように構成されています。

必要な Debezium Db2 コネクター設定プロパティー

以下の設定プロパティーは、デフォルト値がない場合は必須です。

プロパティーデフォルト説明

name

 

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

connector.class

 

コネクターの Java クラスの名前。Db2 コネクターには常に io.debezium.connector.db2.Db2Connector の値を使用します。

tasks.max

1

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

database.hostname

 

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

database.port

50000

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

database.user

 

Db2 データベースサーバーに接続するための Db2 データベースユーザーの名前。

database.password

 

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

database.dbname

 

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

database.server.name

 

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

table.include.list

 

コネクターで変更をキャプチャーするテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト (任意)。include リストに含まれていないテーブルの変更はキャプチャーされません。各識別子の形式は schemaName.tableName です。デフォルトでは、コネクターはシステム以外のテーブルすべての変更をキャプチャーします。また、table.exclude.list プロパティーは設定しないでください。

table.exclude.list

 

コネクターで変更をキャプチャーしないテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト (任意)。コネクターは exclude リストに含まれていないシステム以外のテーブルごとに変更をキャプチャーします。各識別子の形式は schemaName.tableName です。また、table.include.list プロパティーは設定しないでください。

column.exclude.list

空の文字列

変更イベント値から除外する列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は schemaName.tableName.columnName です。プライマリーキー列は、値から除外された場合でも、イベントのキーに常に含まれます。

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

該当なし

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

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

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

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

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

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

time.precision.mode

adaptive

時間、日付、およびタイムスタンプは、異なる精度の種類で表すことができます。

adaptive は、データベース列の型を基にして、ミリ秒、マイクロ秒、またはナノ秒の精度値のいずれかを使用して、データベースの値と全く同じように時間とタイムスタンプをキャプチャーします。

connect は、TimeDate、および Timestamp の Kafka Connect の組み込み表現を使用して、常に時間とタイムスタンプの値を表します。「時間値」を参照してください。

tombstones.on.delete

true

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

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

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

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

include.schema.changes

true

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

column.truncate.to._length_.chars

該当なし

文字ベースの列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は schemaName.tableName.columnName です。変更イベントレコードでは、これらの列の値がプロパティー名の 長さ によって指定される文字数よりも長い場合は切り捨てられます。単一の設定で、異なる長さを持つ複数のプロパティーを指定できます。長さは正の整数である必要があります (例:column.truncate.to.20.chars )。

column.mask.with._length_.chars

該当なし

文字ベースの列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は schemaName.tableName.columnName です。変更イベント値では、指定のテーブルコラムの値はアスタリスク (*) の 長さ (数) に置き換えられます。単一の設定で、異なる長さを持つ複数のプロパティーを指定できます。長さは正の整数またはゼロでなければなりません。ゼロを指定すると、コネクターは値を空の文字列に置き換えます。

column.propagate.source.type

該当なし

列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式はdatabaseName.tableName.columnName または databaseName .schemaName.tableName.columnName です。

コネクターは、指定した各列に対して、列の元の型と元の長さをパラメーターとして、出力された変更レコードの対応するフィールドスキーマに追加します。以下の追加されたスキーマパラメーターは、元の型名と可変幅型の元の長さを伝播します:

__debezium.source.column.type + __debezium.source.column.length + __debezium.source.column.scale

このプロパティーは、シンクデータベースの対応するコラムのサイズを適切に調整する場合に便利です。

datatype.propagate.source.type

該当なし

一部の列のデータベース固有のデータ型名と一致する正規表現のコンマ区切りリスト (任意)。完全修飾データ型名の形式は、databaseName.tableName . typeName または databaseName. schemaName.tableName.typeName です。

これらのデータタイプでは、コネクターは出力された変更レコードの対応するフィールドスキーマにパラメーターを追加します。追加されたパラメーターは、列の元の型と長さを指定します。

__debezium.source.column.type + __debezium.source.column.length + __debezium.source.column.scale

これらのパラメーターは、それぞれ可変幅型の列の元の型名と長さを伝播します。このプロパティーは、シンクデータベースの対応する列のサイズを適切に調整するのに便利です。

Db2 固有のデータ型名のリストは 「Db2 データ型」を参照してください。

message.key.columns

空の文字列

テーブルの列名と一致する正規表現が含まれるテーブルのセミコロン区切りのリスト。コネクターは、一致する列の値を Kafka トピックに送信する変更イベントレコードのキーフィールドにマップします。これは、テーブルにプライマリーキーがない場合や、プライマリーキーではないフィールドに応じて Kafka トピックで変更イベントレコードを順序付ける場合に便利です。

セミコロンでエントリーを区切ります。完全修飾テーブル名とその正規表現の間にコロンを挿入します。形式:

schema-name.table-name:_regexp_;…​

例:

schemaA.table_a:regex_1;schemaB.table_b:regex_2;schemaC.table_c:regex_3

table_aid 列があり、regex_1^iiで始まる列と一致する)の場合、コネクターは table_aid 列の値を Kafka に送信する変更イベントのキーフィールドにマップします。

高度なコネクター設定プロパティー

以下の 高度な 設定プロパティーには、ほとんどの状況で機能するデフォルト設定があるため、コネクターの設定で指定する必要はほとんどありません。

プロパティーデフォルト説明

snapshot.mode

initial

コネクターの起動時にスナップショットを実行する基準を指定します:

initial - キャプチャーモードのテーブルの場合、コネクターはテーブルとテーブルのデータのスナップショットを作成します。これは、データの完全な表現で Kafka トピックに入力する場合に便利です。

schema_only キャプチャーモードのテーブルの場合、コネクターはテーブルのスキーマのみのスナップショットを作成します。これは、現時点以降に発生する変更のみを Kafka トピックに出力する必要がある場合に便利です。スナップショットの完了後、コネクターはデータベースのやり直し (redo) ログから変更イベントの読み取りを続行します。

snapshot.isolation.mode

repeatable_read

スナップショットの実行中に、トランザクション分離レベルとキャプチャーモードのテーブルをロックする期間を制御します。可能な値は

read_uncommitted - 最初のスナップショットの実行中に、他のトランザクションがテーブル行を更新しないようにします。このモードには、データの整合性の保証はありません。一部のデータが損失または破損する可能性があります。

read_committed - 最初のスナップショットの実行中に、他のトランザクションによるテーブル行の更新を防ぎません。新しいレコードが初回のスナップショットで 1 回、ストリーミングフェーズで 1 回の計 2 回発生する可能性があります。しかし、この整合性レベルはデータのミラーリングに適しています。

repeatable_read: 最初のスナップショットの実行中に、他のトランザクションがテーブル行を更新しないようにします。新しいレコードが初回のスナップショットで 1 回、ストリーミングフェーズで 1 回の計 2 回発生する可能性があります。しかし、この整合性レベルはデータのミラーリングに適しています。

exclusive: 繰り返し可能な読み取り分離レベルを使用しますが、すべてのテーブルを読み取るために排他的ロックを使用します。このモードは、最初のスナップショットの実行中に他のトランザクションがテーブル行を更新しないようにします。exclusive モードのみが完全な整合性を保証し、最初のスナップショットとログのストリーミングが履歴の線形を構成します。

event.processing.failure.handling.mode

fail

イベントの処理中にコネクターが例外を処理する方法を指定します。使用できる値は次のとおりです:

fail - コネクターは問題のあるイベントのオフセットをログに記録し、処理を停止します。

warn - コネクターは問題のあるイベントのオフセットをログに記録し、次のイベントの処理を続行します。

skip - コネクターは問題のあるイベントを省略し、次のイベントの処理を続行します。

poll.interval.ms

1000

コネクターがイベントのバッチの処理を開始する前に、新しい変更イベントの発生を待つ期間をミリ秒単位で指定する正の整数値。デフォルトは 1000 ミリ秒 (1 秒) です。

max.queue.size

8192

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

max.batch.size

2048

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

max.queue.size.in.bytes

0

ブロッキングキューの最大サイズ (バイト単位) の long 値。この機能はデフォルトで無効になっています。正の long 値が設定されると有効になります。

heartbeat.interval.ms

0

コネクターがハートビートメッセージを Kafka トピックに送信する頻度を制御します。デフォルトの動作では、コネクターはハートビートメッセージを送信しません。

ハートビートメッセージは、コネクターがデータベースから変更イベントを受信しているかどうかを監視するのに便利です。ハートビートメッセージは、コネクターの再起動時に再送信する必要がある変更イベントの数を減らすのに役立つ可能性があります。ハートビートメッセージを送信するには、このプロパティーを、ハートビートメッセージの間隔をミリ秒単位で示す正の整数に設定します。

ハートビートメッセージは、追跡されるデータベースに多くの更新があるにも関わらず、キャプチャーモードのテーブルにある更新はわずかである場合に便利です。この場合、コネクターは通常どおりにデータベーストランザクションログから読み取りしますが、変更レコードを Kafka に出力することはほとんどありません。そのため、コネクターが最新のオフセットを Kafka に送信することはほとんどありません。ハートビートメッセージを送信すると、コネクターは最新のオフセットを Kafka に送信できます。

heartbeat.topics.prefix

__debezium-heartbeat

コネクターがハートビートメッセージを送信するトピック名のプレフィックスを指定します。このトピック名の形式は <heartbeat.topics.prefix>.<server.name> です。

snapshot.delay.ms

 

コネクターの起動時にスナップショットを実行するまでコネクターが待つ必要がある間隔 (ミリ秒単位)。クラスターで複数のコネクターを起動する場合、このプロパティーは、コネクターのリバランスが行われる原因となるスナップショットの中断を防ぐのに役立ちます。

snapshot.fetch.size

2000

スナップショットの実行中、コネクターは行のバッチでテーブルの内容を読み取ります。このプロパティーは、バッチの行の最大数を指定します。

snapshot.lock.timeout.ms

10000

スナップショットの実行時に、テーブルロックを取得するまで待つ最大時間 (ミリ秒単位) を指定する正の整数値。コネクターがこの間隔でテーブルロックを取得できないと、スナップショットは失敗します。詳細は「コネクターによるスナップショットの実行方法」を参照してください。他の可能な設定:

0 - ロックを取得できない場合、コネクターは即座に失敗します。

-1 - コネクターは無限待機します。

snapshot.select.statement.overrides

 

スナップショットに含まれるテーブル行を制御します。このプロパティーはスナップショットにのみ影響します。コネクターがログから読み取るイベントには影響しません。schemaName.tableName の形式で完全修飾テーブル名のコンマ区切りリストを指定します。

指定するテーブルごとに、別の設定プロパティー snapshot.select.statement.overrides.SCHEMA_NAME.TABLE_NAME も指定します。例: snapshot.select.statement.overrides.customers.ordersこのプロパティーを、スナップショットに必要な行のみを取得する SELECT ステートメントに設定します。コネクターがスナップショットを実行すると、この SELECT ステートメントを実行して、そのテーブルからデータを取得します。

これらのプロパティーの設定に使用可能なユースケースは、大規模な追加専用のテーブルです。スナップショットを開始する場所や、以前のスナップショットが中断された場合にスナップショットを再開する場所を設定する SELECT ステートメントを指定できます。

sanitize.field.names

コネクターが key.converter または value.converter プロパティーを Avro コンバーターに設定する場合は true に設定します。

そうでない場合は false に設定します。

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

provide.transaction.metadata

false

コネクターがトランザクション境界でイベントを生成し、トランザクションメタデータで変更イベントエンベロープを強化するかどうかを決定します。これを行う場合は true を指定します。詳細は、「トランザクションメタデータ」を参照してください。

Debezium コネクターデータベース履歴設定プロパティー

Debezium は、コネクターがスキーマ履歴トピックと対話する方法を制御する database.history.* プロパティーのセットを提供します。

以下の表で、Debezium コネクターを設定するための database.history プロパティーを説明します。

表3.12 コネクターデータベース履歴設定プロパティー

プロパティーデフォルト説明

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 です。

プロデューサーおよびコンシューマークライアントを設定するためのパススルーデータベース履歴プロパティー


Debezium は Kafka プロデューサーを使用して、データベース履歴トピックにスキーマ変更を書き込みます。同様に、コネクターの起動時に、Kafka コンシューマーを使用してデータベース履歴トピックから読み取ります。database.history.producer.* および database.history.consumer.* プレフィックスで始まるパススルー設定プロパティーのセットに値を割り当てて、Kafka プロデューサーおよびコンシューマークライアントの設定を定義します。パススループロデューサーおよびコンシューマーデータベース履歴プロパティーは、以下の例のようにこれらのクライアントが Kafka ブローカーとの接続をセキュリティー保護する方法など、さまざまな動作を制御します。

database.history.producer.security.protocol=SSL
database.history.producer.ssl.keystore.location=/var/private/ssl/kafka.server.keystore.jks
database.history.producer.ssl.keystore.password=test1234
database.history.producer.ssl.truststore.location=/var/private/ssl/kafka.server.truststore.jks
database.history.producer.ssl.truststore.password=test1234
database.history.producer.ssl.key.password=test1234

database.history.consumer.security.protocol=SSL
database.history.consumer.ssl.keystore.location=/var/private/ssl/kafka.server.keystore.jks
database.history.consumer.ssl.keystore.password=test1234
database.history.consumer.ssl.truststore.location=/var/private/ssl/kafka.server.truststore.jks
database.history.consumer.ssl.truststore.password=test1234
database.history.consumer.ssl.key.password=test1234

Debezium は、プロパティーを Kafka クライアントに渡す前に、プロパティー名から接頭辞を取り除きます。

Kafka プロデューサー設定プロパティー および Kafka コンシューマー設定プロパティー の詳細は、Kafka のドキュメントを参照してください。

Debezium コネクターパススルーデータベースドライバー設定プロパティー

Debezium コネクターは、データベースドライバーのパススルー設定を提供します。パススルーデータベースプロパティーはプレフィックス database.* で始まります。たとえば、コネクターは database.foobar=false などのプロパティーを JDBC URL に渡します。

データベース履歴クライアントのパススループロパティー の場合と同様に、Debezium はプロパティーからプレフィックスを取り除き、データベースドライバーに渡します。

3.7. Debezium Db2 コネクターのパフォーマンスの監視

Debezium Db2 コネクターは、Apache ZooKeeper、Apache Kafka、および Kafka Connect によって提供される JMX メトリクスの組み込みサポートに加えて、3 種類のメトリクスを提供します。

Debezium モニタリングのドキュメント では、JMX を使用してこれらのメトリクスを公開する方法の詳細を提供します。

3.7.1. Db2 データベースのスナップショット作成時の Debezium の監視

MBeandebezium.db2:type=connector-metrics,context=snapshot,server=<database.server.name> です。

属性説明

LastEvent

string

コネクターが読み取りした最後のスナップショットイベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取りおよび処理してからの経過時間 (ミリ秒単位)。

TotalNumberOfEventsSeen

long

前回の開始またはリセット以降にコネクターで確認されたイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定された include/exclude リストのフィルタリングルールによってフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルの一覧。

QueueTotalCapacity

int

snapshotter とメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの長さ。

QueueRemainingCapacity

int

snapshotter とメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの空き容量。

TotalTableCount

int

スナップショットに含まれているテーブルの合計数。

RemainingTableCount

int

スナップショットによってまだコピーされていないテーブルの数。

SnapshotRunning

boolean

スナップショットが起動されたかどうか。

SnapshotAborted

boolean

スナップショットが中断されたかどうか。

SnapshotCompleted

boolean

スナップショットが完了したかどうか。

SnapshotDurationInSeconds

long

スナップショットが完了したかどうかに関わらず、これまでスナップショットにかかった時間 (秒単位)。

RowsScanned

Map<String, Long>

スナップショットの各テーブルに対してスキャンされる行数が含まれるマップ。テーブルは、処理中に増分がマップに追加されます。スキャンされた 10,000 行ごとに、テーブルの完成時に更新されます。

MaxQueueSizeInBytes

long

キューの最大バッファー (バイト単位)。max.queue.size.in.bytes が正の long 値で渡された場合に有効になります。

CurrentQueueSizeInBytes

long

キュー内のレコードの現在のデータ (バイト単位)。

3.7.2. Debezium Db2 コネクターレコードストリーミングの監視

MBeandebezium.db2:type=connector-metrics,context=streaming,server=<database.server.name> です。

属性説明

LastEvent

string

コネクターが読み取られた最後のストリーミングイベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取りおよび処理してからの経過時間 (ミリ秒単位)。

TotalNumberOfEventsSeen

long

前回の開始またはリセット以降にコネクターで確認されたイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定された include/exclude リストのフィルタリングルールによってフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルの一覧。

QueueTotalCapacity

int

ストリーマーとメイン Kafka Connect ループの間でイベントを渡すために使用されるキューの長さ。

QueueRemainingCapacity

int

ストリーマーとメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの空き容量。

Connected

boolean

コネクターが現在データベースサーバーに接続されているかどうかを示すフラグ。

MilliSecondsBehindSource

long

最後の変更イベントのタイムスタンプとそれを処理するコネクターとの間の期間 (ミリ秒単位)。この値は、データベースサーバーとコネクターが稼働しているマシンのクロック間の差異に対応します。

NumberOfCommittedTransactions

long

コミットされた処理済みトランザクションの数。

SourceEventPosition

Map<String, String>

最後に受信したイベントの位置。

LastTransactionId

string

最後に処理されたトランザクションのトランザクション識別子。

MaxQueueSizeInBytes

long

キューの最大バッファー (バイト単位)。

CurrentQueueSizeInBytes

long

キュー内のレコードの現在のデータ (バイト単位)。

3.7.3. Debezium Db2 コネクターのスキーマ履歴の監視

MBeandebezium.db2:type=connector-metrics,context=schema-history,server=<database.server.name> です。

属性説明

Status

string

データベース履歴の状態を示す STOPPEDRECOVERING (ストレージから履歴を復元)、または RUNNING のいずれか。

RecoveryStartTime

long

リカバリーが開始された時点のエポック秒の時間。

ChangesRecovered

long

リカバリーフェーズ中に読み取られた変更の数。

ChangesApplied

long

リカバリーおよびランタイム中に適用されるスキーマ変更の合計数。

MilliSecondsSinceLast​RecoveredChange

long

最後の変更が履歴ストアから復元された時点からの経過時間 (ミリ秒単位)。

MilliSecondsSinceLast​AppliedChange

long

最後の変更が適用された時点からの経過時間 (ミリ秒単位)。

LastRecoveredChange

string

履歴ストアから復元された最後の変更の文字列表現。

LastAppliedChange

string

最後に適用された変更の文字列表現。

3.8. Debezium Db2 コネクターの管理

Debezium Db2 コネクターをデプロイしたら、Debezium 管理 UDF を使用して、SQL コマンドで Db2 レプリケーション (ASN) を制御します。UDF によっては戻り値が必要な場合があります。この場合、SQL の VALUE ステートメントを使用して呼び出します。その他の UDF には、SQL の CALL ステートメントを使用します。

表3.13 Debezium 管理 UDF の説明

タスクコマンドおよび注記

ASN エージェントの起動

VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');

ASN エージェントの停止

VALUES ASNCDC.ASNCDCSERVICES('stop','asncdc');

ASN エージェントの状態確認

VALUES ASNCDC.ASNCDCSERVICES('status','asncdc');

テーブルをキャプチャーモードにする

CALL ASNCDC.ADDTABLE('MYSCHEMA', 'MYTABLE');

MYSCHEMA を、キャプチャーモードにするテーブルが含まれるスキーマの名前に置き換えます。同様に、MYTABLE を、キャプチャーモードにするテーブルの名前に置き換えます。

キャプチャーモードからテーブルを削除

CALL ASNCDC.REMOVETABLE('MYSCHEMA', 'MYTABLE');

ASN サービスの再初期化

VALUES ASNCDC.ASNCDCSERVICES('reinit','asncdc');

テーブルをキャプチャーモードにするか、キャプチャーモードからテーブルを削除した後に、これを行います。

3.9. Debezium コネクターでのキャプチャーモードの Db2 テーブルのスキーマの更新

Debezium Db2 コネクターはスキーマ変更をキャプチャーできますが、スキーマを更新するには、データベース管理者と協力してコネクターが変更イベントの生成を継続するようにする必要があります。これは、Db2 がレプリケーションを実装する方法に必要です。

Db2 のレプリケーション機能は、キャプチャーモードのテーブルごとに、すべての変更が含まれる変更データテーブルをそのソーステーブルに作成します。ただし、変更データテーブルスキーマは静的です。キャプチャーモードのテーブルのスキーマを更新する場合は、対応する変更データテーブルのスキーマを更新する必要もあります。Debezium Db2 コネクターはこれを実行できません。昇格された権限を持つデータベース管理者は、キャプチャーモードのテーブルのスキーマを更新する必要があります。

警告

同じテーブルの新しいスキーマ更新の前に、スキーマ更新の手順を完全に実行することが重要です。そのため、スキーマ更新の手順を 1 度で完了するために、すべての DDL を 1 つのバッチで実行することが推奨されます。

通常、テーブルスキーマを更新する手順は 2 つあります。

それぞれの方法に長所と短所があります。

3.9.1. Debezium Db2 コネクターでのオフラインスキーマ更新の実行

オフラインでスキーマの更新を行う前に、Debezium Db2 コネクターを停止します。これはより安全なスキーマ更新の手順ですが、高可用性の要件のあるアプリケーションには実現できない可能性があります。

前提条件

  • スキーマの更新が必要なキャプチャーモードのテーブル 1 つ以上。

手順

  1. データベースを更新するアプリケーションを一時停止します。
  2. Debezium コネクターがストリーミングされていない変更イベントレコードをすべてストリーミングするまで待ちます。
  3. Debezium コネクターを停止します。
  4. すべての変更をソーステーブルスキーマに適用します。
  5. ASN レジスターテーブルで、スキーマが更新されたテーブルを INACTIVE でマーク付けします。
  6. ASN キャプチャーサービスを再度初期化します (https://access.redhat.com/documentation/en-us/red_hat_integration/2021.Q3/html-single/debezium_user_guide/index#debezium-db2-reinitialize-asn-service)。
  7. キャプチャーモードからテーブルを削除するために Debezium UDF を実行 して、キャプチャーモードから古いスキーマを持つソーステーブルを削除します。
  8. テーブルをキャプチャーモードに追加するために Debezium UDF を実行 して、新しいスキーマを持つソーステーブルをキャプチャーモードに追加します。
  9. ASN レジスターテーブルで、更新されたソーステーブルを ACTIVE としてマーク付けします。
  10. ASN キャプチャーサービスを再初期化します。
  11. データベースを更新するアプリケーションを再開します。
  12. Debezium コネクターを再起動します。

3.9.2. Debezium Db2 コネクターでのオンラインスキーマ更新の実行

オンラインスキーマの更新ではアプリケーションやデータ処理のダウンタイムは必要ありません。そのため、オンラインスキーマの更新を実行する前に Debezium Db2 コネクターを停止しません。また、オンラインスキーマの更新手順は、オフラインスキーマの更新手順よりも簡単です。

ただし、テーブルがキャプチャーモードの場合は、列名の変更後も Db2 レプリケーション機能は引き続き古い列名を使用します。新しい列名は、Debezium の変更イベントでは表示されません。変更イベントにある新しい列名を確認するには、コネクターを再起動する必要があります。

前提条件

  • スキーマの更新が必要なキャプチャーモードのテーブル 1 つ以上。

テーブルの最後に列を追加する場合の手順

  1. 変更するスキーマのソーステーブルをロックします。
  2. ASN レジスターテーブルで、ロックされたテーブルを INACTIVE としてマーク付けします。
  3. ASN キャプチャーサービスを再初期化します。
  4. ソーステーブルのスキーマにすべての変更を適用します。
  5. 対応する変更データテーブルのスキーマにすべての変更を適用します。
  6. ASN レジスターテーブルで、ソーステーブルを ACTIVE としてマーク付けします。
  7. ASN キャプチャーサービスを再初期化します。
  8. 任意手順:コネクターを再起動して、変更イベントにある更新された列名を確認します。

テーブルの中に列を追加する場合の手順

  1. 変更するソーステーブルをロックします。
  2. ASN レジスターテーブルで、ロックされたテーブルを INACTIVE としてマーク付けします。
  3. ASN キャプチャーサービスを再初期化します。
  4. 変更するソーステーブルごとに以下を行います。

    1. ソーステーブルのデータをエクスポートします。
    2. ソーステーブルを切り捨てます。
    3. ソーステーブルを変更して列を追加します。
    4. エクスポートしたデータを変更したソーステーブルに読み込みます。
    5. ソーステーブルの対応する変更データテーブルのデータをエクスポートします。
    6. 変更データテーブルを切り捨てます。
    7. 変更データテーブルを変更して、列を追加します。
    8. エクスポートしたデータを変更した変更データテーブルに読み込みます。
  5. ASN レジスターテーブルで、テーブルを INACTIVE としてマーク付けします。これにより、古い変更データテーブルが非アクティブとしてマーク付けされるため、それらのテーブルにあるデータは保持されますが、更新されなくなります。
  6. ASN キャプチャーサービスを再初期化します。
  7. 任意手順:コネクターを再起動して、変更イベントにある更新された列名を確認します。

第4章 MongoDB の Debezium コネクター

Debezium の MongoDB コネクターは、データベースおよびコレクションにおけるドキュメントの変更に対して、MongoDB レプリカセットまたは MongoDB シャードクラスターを追跡し、これらの変更を Kafka トピックのイベントとして記録します。コネクターは、シャードクラスターにおけるシャードの追加または削除、各レプリカセットのメンバーシップの変更、各レプリカセット内の選出、および通信問題の解決待ちを自動的に処理します。

Debezium MongoDB コネクターを使用するための情報および手順は、以下のように構成されています。

4.1. Debezium MongoDB コネクターの概要

MongoDB のレプリケーションメカニズムは冗長性と高可用性を提供し、実稼働環境における MongoDB の実行に推奨される方法です。MongoDB コネクターは、レプリカセットまたはシャードクラスターの変更をキャプチャーします。

MongoDB レプリカセット は、すべてが同じデータのコピーを持つサーバーのセットで構成され、レプリケーションによって、クライアントがレプリカセットの プライマリー のドキュメントに追加したすべての変更が、セカンダリーと呼ばれる別のレプリカセットのサーバーに適用されるようにします。MongoDB のレプリケーションでは、プライマリーが oplog (または操作ログ) に変更を記録した後、各セカンダリーがプライマリーの oplog を読み取って、すべての操作を順番に独自のドキュメントに適用します。新規サーバーをレプリカセットに追加すると、そのサーバーは最初にプライマリーのすべてのデータベースおよびコレクションの スナップショット を実行し、次にプライマリーの oplog を読み取り、スナップショットの開始後に加えられたすべての変更を適用します。この新しいサーバーは、プライマリーの oplog の最後に到達するとセカンダリーになり、クエリーを処理できます。

MongoDB コネクターはこのレプリケーションメカニズムを使用しますが、実際にはレプリカセットのメンバーにはなりません。ただし、MongoDB のセカンダリーと同様に、コネクターはレプリカセットのプライマリーの oplog を常に読み取ります。また、コネクターが初めてレプリカセットを表示するとき、oplog を確認して最後に記録されたトランザクションを取得した後、プライマリーのデータベースおよびコレクションのスナップショットを実行します。すべてのデータがコピーされると、コネクターは oplog から読み取った位置から変更をストリーミングします。MongoDB oplog における操作は べき等 であるため、操作の適用回数に関係なく、同じ最終状態になります。

MongoDB コネクターが変更を処理すると、イベントの発生元となる oplog の位置を定期的に記録します。MongoDB コネクターが停止したときに、最後に処理した oplog の位置を記録するため、再起動時にはその位置からストリーミングが開始されます。つまり、コネクターを停止、アップグレード、または維持でき、後で再起動できます。イベントを何も失うことなく、停止した場所を正確に特定します。当然ながら、MongoDB の oplogs は通常は最大サイズに制限されているため、コネクターを長時間停止しないようにしてください。長時間停止すると、oplog の操作によってはコネクターによって読み取られる前にパージされる可能性があります。この場合、コネクターを再起動すると、不足している oplog 操作が検出され、スナップショットが実行されます。その後、変更のストリーミングが続行されます。

MongoDB コネクターは、レプリカセットのメンバーシップとリーダーシップの変更、シャードクラスター内でのシャードの追加と削除、および通信障害の原因となる可能性のあるネットワーク問題にも非常に寛容です。コネクターは常にレプリカセットのプライマリーノードを使用して変更をストリーミングします。そのため、レプリカセットの選出が行われ、他のノードがプライマリーになると、コネクターはすぐ変更のストリーミングを停止し、新しいプライマリーに接続し、新しいプライマリーを使用して変更のストリーミングを開始します。同様に、コネクターがレプリカセットのプライマリーと通信する際に問題が発生した場合は、再接続を試み (ネットワークまたはレプリカセットを圧倒しないように指数バックオフを使用)、最後に停止した位置から変更のストリーミングを続行します。これにより、コネクターはレプリカセットメンバーシップの変更を動的に調整でき、通信の失敗を自動的に処理できます。

4.2. Debezium MongoDB コネクターの仕組み

コネクターがサポートする MongoDB トポロジーの概要は、アプリケーションを計画するときに役立ちます。

MongoDB コネクターが設定およびデプロイされると、シードアドレスの MongoDB サーバーに接続して起動し、利用可能な各レプリカセットの詳細を判断します。各レプリカセットには独立した独自の oplog があるため、コネクターはレプリカセットごとに個別のタスクの使用を試みます。コネクターは、使用するタスクの最大数を制限でき、十分なタスクが利用できない場合は、コネクターは各タスクに複数のレプリカセットを割り当てます。ただし、タスクはレプリカセットごとに個別のスレッドを使用します。

注記

シャードクラスターに対してコネクターを実行する場合は、レプリカセットの数よりも大きい tasks.max の値を使用します。これにより、コネクターはレプリカセットごとに 1 つのタスクを作成でき、Kafka Connect が利用可能なワーカープロセス全体でタスクを調整、配布、および管理できるようにします。

Debezium MongoDB コネクターの動作に関する詳細は、以下のトピックを参照してください。

4.2.1. Debezium コネクターでサポートされる MongoDB トポロジー

MongoDB コネクターは以下の MongoDB トポロジーをサポートします。

MongoDB レプリカセット

Debezium MongoDB コネクターは単一の MongoDB レプリカセット から変更をキャプチャーできます。実稼働のレプリカセットには、少なくとも 3 つのメンバー が必要です。

レプリカセットで MongoDB コネクターを使用するには、コネクターの mongodb.hosts プロパティーを使用して、1 つ以上のレプリカセットサーバーのアドレスを シードアドレス として提供します。コネクターはこれらのシードを使用してレプリカセットに接続した後、レプリカセットからメンバーの完全セットを取得し、どのメンバーがプライマリーであるかを認識します。コネクターは、プライマリーに接続するタスクを開始し、プライマリーの oplog から変更をキャプチャーします。レプリカセットが新しいプライマリーを選出すると、タスクは自動的に新しいプライマリーに切り替えます。

注記

MongoDB がプロキシーと面する場合 (Docker on OS X や Windows などのように)、クライアントがレプリカセットに接続し、メンバーを検出すると、MongoDB クライアントはプロキシーを有効なメンバーから除外し、プロキシーを経由せずに直接メンバーに接続しようとし、失敗します。

このような場合、コネクターのオプションの mongodb.members.auto.discover 設定プロパティーを false に設定して、コネクターにメンバーシップの検出を見送るように指示し、代わりに最初のシードアドレス (mongodb.hosts プロパティーによって指定) をプライマリーノードとして使用するよう指示します。これは機能する可能性がありますが、選出が行われるときに問題が発生します。

MongoDB のシャードクラスター

MongoDB のシャードクラスター は以下で構成されます。

  • レプリカセットとしてデプロイされる 1 つ以上のシャード
  • クラスターの設定サーバーとして動作する個別のレプリカセット。
  • クライアントが接続し、要求を適切なシャードにルーティングする 1 つ以上の ルーター (mongos とも呼ばれます)。

    シャードクラスターで MongoDB コネクターを使用するには、コネクターを設定サーバーレプリカセットのホストアドレスで設定します。コネクターがこのレプリカセットに接続すると、シャードクラスターの設定サーバーとして動作していることを検出し、クラスターでシャードとして使用される各レプリカセットに関する情報を検出した後、各レプリカセットから変更をキャプチャーするために別のタスクを起動します。新しいシャードがクラスターに追加される場合または既存のシャードが削除される場合、コネクターはそのタスクを自動的に調整します。

MongoDB スタンドアロンサーバー
スタンドアロンサーバーには oplog がないため、MongoDB コネクターはスタンドアロン MongoDB サーバーの変更を監視できません。スタンドアロンサーバーが 1 つのメンバーを持つレプリカセットに変換されると、コネクターが動作します。
注記

MongoDB は、実稼働でのスタンドアロンサーバーの実行を推奨しません。詳細は、MongoDB のドキュメント を参照してください。

4.2.2. Debezium MongoDB コネクターがレプリカセットおよびシャードクラスターに論理名を使用する方法

コネクター設定プロパティー mongodb.name は、MongoDB レプリカセットまたはシャードされたクラスターの 論理名 として提供されます。コネクターは、論理名をさまざまな方法で使用します。すべてトピック名のプレフィックとして使用したり、各レプリカセットの oplog の位置を記録するときに一意の識別子として使用したりします。

一意の論理名を各 MongoDB コネクターに割り当てます。この名前は、ソース MongoDB システムについて意味的に記述する必要があります。アルファベットまたはアンダースコアで始まる論理名を割り当て、英数字またはアンダースコアのみを含めることが推奨されます。

4.2.3. Debezium MongoDB コネクターのスナップショット実行方法

タスクがレプリカセットを使用して起動すると、コネクターの論理名とレプリカセット名を使用して、コネクターが変更の読み取りを停止した位置を示す オフセット を検出します。オフセットが検出され、oplog に存在する場合、タスクは記録されたオフセットの位置から即座に 変更のストリーミング を続行します。

ただし、オフセットが見つからない場合や、oplog にその位置が含まれなくなった場合、タスクは スナップショット を実行してレプリカセットの内容の現在の状態を取得する必要があります。このプロセスは、oplog の現在の位置を記録して開始され、オフセット (スナップショットが開始されたことを示すフラグとともに) として記録します。その後、タスクは各コレクションをコピーし、できるだけ多くのスレッドを生成し (snapshot.max.threads 設定プロパティーの値まで)、この作業を並行して行います。コネクターは、確認した各ドキュメントの個別の 読み取りイベント を記録します。読み取りイベントにはオブジェクトの識別子、オブジェクトの完全な状態、およびオブジェクトが見つかった MongoDB レプリカセットの ソース 情報が含まれます。ソース情報には、スナップショット中にイベントが生成されたことを示すフラグも含まれます。

このスナップショットは、コネクターのフィルターと一致するすべてのコレクションがコピーされるまで継続されます。タスクのスナップショットが完了する前にコネクターが停止した場合は、コネクターを再起動すると、再びスナップショットを開始します。

注記

コネクターがレプリカセットのスナップショットを実行している間は、タスクの再割り当てと再設定をしないようにします。コネクターはスナップショットの進捗とともにメッセージをログに記録します。最大限の制御を行う場合は、各コネクターに対して Kafka Connect の個別のクラスターを実行します。

4.2.4. Debezium MongoDB コネクターが変更イベントレコードをストリーミングする方法

レプリカセットのコネクタータスクがオフセットを記録した後、オフセットを使用して変更のストリーミングを開始する oplog の位置を判断します。その後、タスクはレプリカセットのプライマリーノードに接続し、その位置から変更のストリーミングを開始します。これは、すべての作成、挿入、および削除操作を処理し、それらを Debezium の 変更イベント に変換します。各変更イベントには操作が検出された oplog の位置が含まれ、コネクターはこれを最新のオフセットとして定期的に記録します。オフセットが記録される間隔は、Kafka Connect ワーカー設定プロパティーである offset.flush.interval.ms によって制御されます。

コネクターが正常に停止されると、処理された最後のオフセットが記録され、再起動時にコネクターは停止した場所から続行されます。しかし、コネクターのタスクが予期せず終了した場合、最後にオフセットが記録された後、最後のオフセットが記録される前に、タスクによってイベントが処理および生成されることがあります。再起動時に、コネクターは最後に 記録された オフセットから開始し、クラッシュの前に生成された同じイベントを生成する可能性があります。

注記

通常、Kafka コンシューマーはすべてのメッセージを 1 度だけ 読み取ります。ただし、エラーが発生した場合は、Kafka はコンシューマーが 最低でも 1 回 すべてのメッセージを確認することのみを保証します。したがって、コンシューマーが複数回メッセージを確認することを想定する必要があります。

前述のように、コネクタータスクは常にレプリカセットのプライマリーノードを使用して oplog からの変更をストリーミングし、コネクターが可能な限り最新の操作を確認できるようにし、代わりにセカンダリーが使用された場合よりも短いレイテンシーで変更をキャプチャーできるようにします。レプリカセットが新しいプライマリーを選出すると、コネクターは即座に変更のストリーミングを停止し、新しいプライマリーに接続して、同じ場所にある新しいプライマリーノードから変更のストリーミングを開始します。同様に、コネクターとレプリカセットメンバーとの通信で問題が発生した場合は、レプリカセットが過剰にならないように指数バックオフを使用して再接続を試みます。接続の確立後、停止した場所から変更のストリーミングを続行します。これにより、コネクターはレプリカセットメンバーシップの変更を動的に調整でき、通信障害を自動的に処理できます。

要約すると、MongoDB コネクターはほとんどの状況で実行を継続します。通信の問題により、問題が解決されるまでコネクターが待機する可能性があります。

4.2.5. Debezium MongoDB 変更イベントレコードを受信する Kafka トピックのデフォルト名

MongoDB コネクターは、各コレクションのドキュメントに対するすべての挿入、更新、および削除操作のイベントを 1 つの Kafka トピックに書き込みます。Kafka トピックの名前は常に logicalName.databaseName.collectionName の形式を取ります。logicalName は、mongodb.name 設定プロパティーで指定されるコネクターの 論理名databaseName は操作が発生したデータベースの名前、collectionName は影響を受けるドキュメントが存在する MongoDB コレクションの名前です。

たとえば、productsproducts_on_handcustomers、および orders の 4 つのコレクションが含まれる inventory データベースを持つ MongoDB レプリカセットについて考えてみましょう。コネクターが監視するこのデータベースの論理名が fulfillment である場合、コネクターは以下の 4 つの Kafka トピックでイベントを生成します。

  • fulfillment.inventory.products
  • fulfillment.inventory.products_on_hand
  • fulfillment.inventory.customers
  • fulfillment.inventory.orders

トピック名には、レプリカセット名やシャード名が含まれないことに注意してください。その結果、シャード化コレクションへの変更 (各シャードにコレクションのドキュメントのサブセットが含まれる) はすべて同じ Kafka トピックに移動します。

Kafka を設定して、必要に応じてトピックを自動作成 できます。そうでない場合は、Kafka 管理ツールを使用してコネクターを起動する前にトピックを作成する必要があります。

4.2.6. イベントキーが Debezium MongoDB コネクターのトピックパーティショニングを制御する方法

MongoDB コネクターは、イベントのトピックをどのようにパーティション化するかを明確に決定しません。代わりに、Kafka がイベントキーに基づいてトピックを分割する方法を判断できるようにします。Kafka Connect ワーカー設定に Partitioner 実装の名前を定義することで、Kafka のパーティショニングロジックを変更できます。

Kafka は、1 つのトピックパーティションに書き込まれたイベントのみ、合計順序を維持します。キーでイベントのパーティションを行うと、同じキーを持つすべてのイベントは常に同じパーティションに移動します。これにより、特定のドキュメントのすべてのイベントが常に完全に順序付けされます。

4.2.7. トランザクション境界を表す Debezium MongoDB コネクターによって生成されたイベント

Debezium は、トランザクションメタデータ境界を表すイベントを生成でき、変更データイベントメッセージをエンリッチできます。Debezium はすべてのトランザクションの BEGIN および END に対して、以下のフィールドが含まれるイベントを生成します。

status
BEGIN または END
id
一意のトランザクション識別子の文字列表現。
event_count (END イベント用)
トランザクションによって出力されるイベントの合計数。
data_collections (END イベント用)
指定のデータコレクションからの変更によって出力されたイベントの数を提供する data_collectionevent_count のペアの配列。

以下の例は、典型的なメッセージを示しています。

{
  "status": "BEGIN",
  "id": "1462833718356672513",
  "event_count": null,
  "data_collections": null
}

{
  "status": "END",
  "id": "1462833718356672513",
  "event_count": 2,
  "data_collections": [
    {
      "data_collection": "rs0.testDB.collectiona",
      "event_count": 1
    },
    {
      "data_collection": "rs0.testDB.collectionb",
      "event_count": 1
    }
  ]
}

トランザクションイベントは、<database.server.name>.transaction という名前のトピックに書き込まれます。

変更データイベントのエンリッチメント

トランザクションメタデータを有効にすると、データメッセージ Envelope は新しい transaction フィールドでエンリッチされます。このフィールドは、複合フィールドの形式ですべてのイベントに関する情報を提供します。

id
一意のトランザクション識別子の文字列表現。
total_order
トランザクションによって生成されたすべてのイベントを対象とするイベントの絶対位置。
data_collection_order
トランザクションによって出力されたすべてのイベントを対象とするイベントのデータコレクションごとの位置。

以下は、メッセージの内容の例です。

{
  "before": null,
  "after": {
    "pk": "2",
    "aa": "1"
  },
  "source": {
...
  },
  "op": "c",
  "ts_ms": "1580390884335",
  "transaction": {
    "id": "1462833718356672513",
    "total_order": "1",
    "data_collection_order": "1"
  }
}

4.3. Debezium MongoDB コネクターのデータ変更イベントの説明

Debezium MongoDB コネクターは、データを挿入、更新、または削除する各ドキュメントレベルの操作に対してデータ変更イベントを生成します。各イベントにはキーと値が含まれます。キーと値の構造は、変更されたコレクションによって異なります。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリーム を中心として設計されています。ただし、これらのイベントの構造は時間の経過とともに変化する可能性があり、コンシューマーによる処理が困難になることがあります。これに対応するために、各イベントにはコンテンツのスキーマが含まれます。スキーマレジストリーを使用している場合は、コンシューマーがレジストリーからスキーマを取得するために使用できるスキーマ ID が含まれます。これにより、各イベントが自己完結型になります。

以下のスケルトン JSON は、変更イベントの基本となる 4 つの部分を示しています。ただし、アプリケーションで使用するために選択した Kafka Connect コンバーターの設定方法によって、変更イベントのこれら 4 部分の表現が決定されます。schema フィールドは、変更イベントが生成されるようにコンバーターを設定した場合のみ変更イベントに含まれます。同様に、イベントキーおよびイベントペイロードは、変更イベントが生成されるようにコンバーターを設定した場合のみ変更イベントに含まれます。JSON コンバーターを使用し、変更イベントの基本となる 4 つの部分すべてを生成するように設定すると、変更イベントの構造は次のようになります。

{
 "schema": { 1
   ...
  },
 "payload": { 2
   ...
 },
 "schema": { 3
   ...
 },
 "payload": { 4
   ...
 },
}

表4.1 変更イベントの基本内容の概要

項目フィールド名説明

1

schema

最初の schema フィールドはイベントキーの一部です。イベントキーの payload の部分の内容を記述する Kafka Connect スキーマを指定します。つまり、最初の schema フィールドには、変更されたドキュメントのキーの構造を記述されます。

2

payload

最初の payload フィールドはイベントキーの一部です。前述の schema フィールドによって記述された構造を持ち、変更されたドキュメントのキーが含まれます。

3

schema

2 つ目の schema フィールドはイベント値の一部です。イベント値の payload の部分の内容を記述する Kafka Connect スキーマを指定します。つまり、2 つ目の schema は変更されたドキュメントの構造を記述します。通常、このスキーマには入れ子になったスキーマが含まれます。

4

payload

2 つ目の payload フィールドはイベント値の一部です。前述の schema フィールドによって記述された構造を持ち、変更されたドキュメントの実際のデータが含まれます。

デフォルトでは、コネクターによって、変更イベントレコードがイベントの元のコレクションと同じ名前を持つトピックにストリーミングされます。トピック名 を参照してください。

警告

MongoDB コネクターは、すべての Kafka Connect スキーマ名が Avro スキーマ名の形式 に準拠するようにします。つまり、論理サーバー名はアルファベットまたはアンダースコア (a-z、A-Z、または _) で始まる必要があります。論理サーバー名の残りの各文字と、データベース名とコレクション名の各文字は、アルファベット、数字、またはアンダースコア ( a-z、A-Z、0-9、または _) でなければなりません。無効な文字がある場合は、アンダースコアに置き換えられます。

論理サーバー名、データベース名、またはコレクション名に無効な文字が含まれ、名前を区別する唯一の文字が無効であると、無効な文字はすべてアンダースコアに置き換えられるため、予期せぬ競合が発生する可能性があります。

詳細は、以下のトピックを参照してください。

4.3.1. Debezium MongoDB 変更イベントのキー

変更イベントのキーには、変更されたドキュメントのキーのスキーマと、変更されたドキュメントの実際のキーのスキーマが含まれます。特定のコレクションでは、スキーマとそれに対応するペイロードの両方に単一の id フィールドが含まれます。このフィールドの値は、MongoDB Extended JSON のシリアライゼーションの厳格モード から派生する文字列として表されるドキュメントの識別子です。

論理名が fulfillment のコネクター、inventory データベースが含まれるレプリカセット、および以下のようなドキュメントが含まれる customers コレクションについて考えてみましょう。

ドキュメントの例

{
  "_id": 1004,
  "first_name": "Anne",
  "last_name": "Kretchmar",
  "email": "annek@noanswer.org"
}

変更イベントキーの例

customers コレクションへの変更をキャプチャーする変更イベントのすべてに、イベントキースキーマがあります。customers コレクションに前述の定義がある限り、customers コレクションへの変更をキャプチャーする変更イベントのキー構造はすべて以下のようになります。JSON では、以下のようになります。

{
  "schema": { 1
    "type": "struct",
    "name": "fulfillment.inventory.customers.Key", 2
    "optional": false, 3
    "fields": [ 4
      {
        "field": "id",
        "type": "string",
        "optional": false
      }
    ]
  },
  "payload": { 5
    "id": "1004"
  }
}

表4.2 変更イベントキーの説明

項目フィールド名説明

1

schema

キーのスキーマ部分は、キーの payload 部分の内容を記述する Kafka Connect スキーマを指定します。

2

fulfillment.inventory.customers.Key

キーのペイロードの構造を定義するスキーマの名前。このスキーマは、変更したドキュメントのキーの構造を説明します。キースキーマ名の形式は connector-name.database-name.collection-name.Key です。この例では、以下のようになります。

  • fulfillment はこのイベントを生成したコネクターの名前です。
  • inventory は変更されたコレクションが含まれるデータベースです。
  • customers は更新されたドキュメントが含まれるコレクションです。

3

optional

イベントキーの payload フィールドに値が含まれる必要があるかどうかを示します。この例では、キーのペイロードに値が必要です。ドキュメントにキーがない場合、キーの payload フィールドの値は任意です。

4

fields

各フィールドの名前、タイプ、および必要かどうかなど、payload で想定される各フィールドを指定します。

5

payload

この変更イベントが生成されたドキュメントのキーが含まれます。この例では、キーには型 string の 1 つの id フィールドが含まれ、その値は 1004 です。

この例では、整数の識別子を持つドキュメントを使用しますが、有効な MongoDB ドキュメント識別子は、ドキュメント識別子を含め、同じように動作します。ドキュメント識別子の場合、イベントキーの payload.id 値は、厳格モードを使用する MongoDB Extended JSON シリアライゼーションとして更新されたドキュメントの元の _id フィールドを表す文字列です。以下の表では、さまざまな型の _id フィールドを表す例を示します。

表4.3 イベントキーペイロードのドキュメント _id フィールドを表す例

MongoDB _id の値キーのペイロード

Integer

1234

{ "id" : "1234" }

Float

12.34

{ "id" : "12.34" }

String

"1234"

{ "id" : "\"1234\"" }

Document

{ "hi" : "kafka", "nums" : [10.0, 100.0, 1000.0] }

{ "id" : "{\"hi\" : \"kafka\", \"nums\" : [10.0, 100.0, 1000.0]}" }

ObjectId

ObjectId("596e275826f08b2730779e1f")

{ "id" : "{\"$oid\" : \"596e275826f08b2730779e1f\"}" }

Binary

BinData("a2Fma2E=",0)

{ "id" : "{\"$binary\" : \"a2Fma2E=\", \"$type\" : \"00\"}" }

4.3.2. Debezium MongoDB 変更イベントの値

変更イベントの値はキーよりも若干複雑です。キーと同様に、値には schema セクションと payload セクションがあります。schema セクションには、入れ子のフィールドを含む、payload セクションの Envelope 構造を記述するスキーマが含まれています。データを作成、更新、または削除する操作のすべての変更イベントには、Envelope 構造を持つ値 payload があります。

変更イベントキーの例を紹介するために使用した、同じサンプルドキュメントについて考えてみましょう。

ドキュメントの例

{
  "_id": 1004,
  "first_name": "Anne",
  "last_name": "Kretchmar",
  "email": "annek@noanswer.org"
}

このドキュメントへの変更に対する変更イベントの値部分には、以下の各イベントタイプについて記述されています。

作成イベント

以下の例は、customers コレクションにデータを作成する操作に対して、コネクターによって生成される変更イベントの値の部分を示しています。

{
    "schema": { 1
      "type": "struct",
      "fields": [
        {
          "type": "string",
          "optional": true,
          "name": "io.debezium.data.Json", 2
          "version": 1,
          "field": "after"
        },
        {
          "type": "string",
          "optional": true,
          "name": "io.debezium.data.Json",
          "version": 1,
          "field": "patch"
        },
        {
          "type": "string",
          "optional": true,
          "name": "io.debezium.data.Json",
          "version": 1,
          "field": "filter"
        },
        {
          "type": "struct",
          "fields": [
            {
              "type": "string",
              "optional": false,
              "field": "version"
            },
            {
              "type": "string",
              "optional": false,
              "field": "connector"
            },
            {
              "type": "string",
              "optional": false,
              "field": "name"
            },
            {
              "type": "int64",
              "optional": false,
              "field": "ts_ms"
            },
            {
              "type": "boolean",
              "optional": true,
              "default": false,
              "field": "snapshot"
            },
            {
              "type": "string",
              "optional": false,
              "field": "db"
            },
            {
              "type": "string",
              "optional": false,
              "field": "rs"
            },
            {
              "type": "string",
              "optional": false,
              "field": "collection"
            },
            {
              "type": "int32",
              "optional": false,
              "field": "ord"
            },
            {
              "type": "int64",
              "optional": true,
              "field": "h"
            }
          ],
          "optional": false,
          "name": "io.debezium.connector.mongo.Source", 3
          "field": "source"
        },
        {
          "type": "string",
          "optional": true,
          "field": "op"
        },
        {
          "type": "int64",
          "optional": true,
          "field": "ts_ms"
        }
      ],
      "optional": false,
      "name": "dbserver1.inventory.customers.Envelope" 4
      },
    "payload": { 5
      "after": "{\"_id\" : {\"$numberLong\" : \"1004\"},\"first_name\" : \"Anne\",\"last_name\" : \"Kretchmar\",\"email\" : \"annek@noanswer.org\"}", 6
      "patch": null,
      "source": { 7
        "version": "1.5.4.Final",
        "connector": "mongodb",
        "name": "fulfillment",
        "ts_ms": 1558965508000,
        "snapshot": false,
        "db": "inventory",
        "rs": "rs0",
        "collection": "customers",
        "ord": 31,
        "h": 1546547425148721999
      },
      "op": "c", 8
      "ts_ms": 1558965515240 9
    }
  }

表4.4 作成 イベント値フィールドの説明

項目フィールド名説明

1

schema

値のペイロードの構造を記述する、値のスキーマ。変更イベントの値スキーマは、コネクターが特定のコレクションに生成するすべての変更イベントで同じになります。

2

name

schema セクションで、各 name フィールドは、値のペイロードのフィールドに対するスキーマを指定します。

io.debezium.data.Json はペイロードの afterpatch、および filter フィールドのスキーマです。このスキーマは customers コレクションに固有です。作成 イベントは、after フィールドが含まれる唯一のイベントです。更新 イベントには、filter フィールドと patch フィールドが含まれます。削除 イベントには filter フィールドが含まれますが、after フィールドや patch フィールドは含まれません。

3

name

io.debezium.connector.mongo.Source はペイロードの source フィールドのスキーマです。このスキーマは MongoDB コネクターに固有です。コネクターは生成するすべてのイベントにこれを使用します。

4

name

dbserver1.inventory.customers.Envelope は、ペイロードの全体的な構造のスキーマです。dbserver1 はコネクター名、inventory はデータベース、customers はコレクションです。このスキーマはコレクションに固有です。

5

payload

値の実際のデータ。これは、変更イベントが提供する情報です。

イベントの JSON 表現はそれが記述するドキュメントよりもはるかに大きいように見えることがあります。これは、JSON 表現にはメッセージのスキーマ部分とペイロード部分を含める必要があるためです。しかし、Avro コンバーター を使用すると、コネクターが Kafka トピックにストリーミングするメッセージのサイズを大幅に小さくすることができます。

6

after

イベント発生後のドキュメントの状態を指定する任意のフィールド。この例では、after フィールドには新しいドキュメントの _idfirst_namelast_name、および email フィールドの値が含まれます。after の値は常に文字列です。慣例により、ドキュメントの JSON 表現が含まれます。MongoDB の oplog エントリーには、作成イベントのみにドキュメントの完全な状態が含まれます。つまり、作成 イベントは after フィールドが含まれる唯一のイベントです。

7

source

イベントのソースメタデータを記述する必須のフィールド。このフィールドには、イベントの発生元、イベントの発生順序、およびイベントが同じトランザクションの一部であるかどうかなど、このイベントと他のイベントを比較するために使用できる情報が含まれています。ソースメタデータには以下が含まれています。

  • Debezium バージョン。
  • イベントを生成したコネクターの名前。
  • 生成されたイベントの namespace を形成し、コネクターが書き込む Kafka トピック名で使用される、MongoDB レプリカセットの論理名。
  • 新しいドキュメントが含まれるコレクションおよびデータベースの名前。
  • イベントがスナップショットの一部である場合。
  • データベースで変更が加えられた時点のタイムスタンプおよびタイムスタンプ内のイベントの順序。
  • MongoDB 操作の一意の識別子。これは MongoDB のバージョンに依存します。これは、oplog イベントの h フィールド、または oplog イベントの lsid および txnNumber フィールドを表す stxnid という名前のフィールドです。

8

op

コネクターによってイベントが生成される原因となった操作のタイプを記述する必須文字列。この例では、c は操作によってドキュメントが作成されたことを示しています。有効な値は次のとおりです。

  • c = create (作成)
  • u = update (更新)
  • d = delete (削除)
  • r = read (読み取り、スナップショットのみに適用)

9

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

更新イベント

サンプル customers コレクションにある更新の変更イベントの値には、そのコレクションの 作成 イベントと同じスキーマがあります。同様に、イベント値のペイロードは同じ構造を持ちます。ただし、イベント値ペイロードでは 更新 イベントに異なる値が含まれます。更新 イベントには after の値はありません。その代わりに、以下の 2 つのフィールドがあります。

  • patch は、べき等更新操作の JSON 表現が含まれる文字列フィールドです。
  • filter は、更新の選択基準の JSON 表現が含まれる文字列フィールドです。filter 文字列には、シャード化コレクションの複数のシャードキーフィールドを含めることができます。

以下は、コネクターによって customers コレクションでの更新に生成されるイベントの変更イベント値の例になります。

{
    "schema": { ... },
    "payload": {
      "op": "u", 1
      "ts_ms": 1465491461815, 2
      "patch": "{\"$set\":{\"first_name\":\"Anne Marie\"}}", 3
      "filter": "{\"_id\" : {\"$numberLong\" : \"1004\"}}", 4
      "source": { 5
        "version": "1.5.4.Final",
        "connector": "mongodb",
        "name": "fulfillment",
        "ts_ms": 1558965508000,
        "snapshot": true,
        "db": "inventory",
        "rs": "rs0",
        "collection": "customers",
        "ord": 6,
        "h": 1546547425148721999
      }
    }
  }

表4.5 更新 イベント値フィールドの説明

項目フィールド名説明

1

op

コネクターによってイベントが生成される原因となった操作のタイプを記述する必須文字列。この例では、u は操作によってドキュメントが更新されたことを示しています。

2

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

3

patch

ドキュメントへの実際の MongoDB のべき等変更の JSON 文字列表現が含まれます。この例では、更新で first_name フィールドを新しい値に変更されています。

更新 イベント値には after フィールドが含まれません。

4

filter

更新するドキュメントの特定に使用された MongoDB 選択基準の JSON 文字列表現が含まれます。

5

source

イベントのソースメタデータを記述する必須のフィールド。このフィールドには、同じコレクションの 作成 イベントと同じ情報が含まれますが、oplog の異なる位置からのイベントであるため、値は異なります。ソースメタデータには以下が含まれています。

  • Debezium バージョン。
  • イベントを生成したコネクターの名前。
  • 生成されたイベントの namespace を形成し、コネクターが書き込む Kafka トピック名で使用される、MongoDB レプリカセットの論理名。
  • 更新されたドキュメントが含まれるコレクションおよびデータベースの名前。
  • イベントがスナップショットの一部である場合。
  • データベースで変更が加えられた時点のタイムスタンプおよびタイムスタンプ内のイベントの順序。
  • MongoDB 操作の一意の識別子。これは MongoDB のバージョンに依存します。これは、oplog イベントの h フィールド、または oplog イベントの lsid および txnNumber フィールドを表す stxnid という名前のフィールドです。
警告

Debezium 変更イベントでは、MongoDB は patch フィールドの内容を提供します。このフィールドの形式は、MongoDB データベースのバージョンによって異なります。したがって、新しい MongoDB データベースバージョンにアップグレードする場合は、形式が変更された可能性があるため注意してください。本書のサンプルは、MongoDB 3.4 から取得したため、ご使用のアプリケーションではイベントの形式が異なる場合があります。

注記

MongoDB の oplog では、更新 イベントには変更されたドキュメントの または の状態は含まれません。そのため、Debezium コネクターがこの情報を提供することはできません。ただし、Debezium コネクターは 作成 および 読み取り イベントでドキュメントの開始状態を提供します。ストリームのダウンストリームのコンシューマーは、ドキュメントごとに最新状態を維持し、新しいイベントの状態を保存された状態に比較することで、ドキュメント状態を再構築できます。Debezium コネクターはこの状態を維持できません。

削除 イベント

削除 変更イベントの値は、同じコレクションの 作成 および 更新 イベントと同じ schema の部分になります。削除 イベントの payload 部分には、同じコレクションの 作成 および 更新 イベントとは異なる値が含まれます。特に、削除 イベントには after の値や patch の値は含まれません。以下は、customers コレクションのドキュメントの 削除 イベントの例になります。

{
    "schema": { ... },
    "payload": {
      "op": "d", 1
      "ts_ms": 1465495462115, 2
      "filter": "{\"_id\" : {\"$numberLong\" : \"1004\"}}", 3
      "source": { 4
        "version": "1.5.4.Final",
        "connector": "mongodb",
        "name": "fulfillment",
        "ts_ms": 1558965508000,
        "snapshot": true,
        "db": "inventory",
        "rs": "rs0",
        "collection": "customers",
        "ord": 6,
        "h": 1546547425148721999
      }
    }
  }

表4.6 削除 イベント値フィールドの説明

項目フィールド名説明

1

op

操作の型を記述する必須の文字列。op フィールドの値は d で、ドキュメントが削除されたことを示します。

2

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

3

filter

削除するドキュメントの特定に使用された MongoDB 選択基準の JSON 文字列表現が含まれます。

4

source

イベントのソースメタデータを記述する必須のフィールド。このフィールドには、同じコレクションの 作成 または 更新 イベントと同じ情報が含まれますが、oplog の異なる位置からのイベントであるため、値は異なります。ソースメタデータには以下が含まれています。

  • Debezium バージョン。
  • イベントを生成したコネクターの名前。
  • 生成されたイベントの namespace を形成し、コネクターが書き込む Kafka トピック名で使用される、MongoDB レプリカセットの論理名。
  • 削除されたドキュメントが含まれたコレクションおよびデータベースの名前。
  • イベントがスナップショットの一部である場合。
  • データベースで変更が加えられた時点のタイムスタンプおよびタイムスタンプ内のイベントの順序。
  • MongoDB 操作の一意の識別子。これは MongoDB のバージョンに依存します。これは、oplog イベントの h フィールドまたは oplog イベントからの lsid および txnNumber フィールドを表す stxnid という名前のフィールドです。

MongoDB コネクターイベントは、Kafka ログコンパクション と動作するように設計されています。ログコンパクションにより、少なくとも各キーの最新のメッセージが保持される限り、一部の古いメッセージを削除できます。これにより、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できるようにするとともに、Kafka がストレージ領域を確保できるようにします。

廃棄 (tombstone) イベント

一意に識別ドキュメントの MongoDB コネクターイベントはすべて同じキーを持ちます。ドキュメントが削除された場合でも、Kafka は同じキーを持つ以前のメッセージをすべて削除できるため、削除 イベントの値はログコンパクションで動作します。ただし、Kafka がそのキーを持つすべてのメッセージを削除するには、メッセージの値が null である必要があります。これを可能にするために、Debezium の MongoDB コネクターは 削除 イベントを出力した後に、同じキーと null の値を持つ特別な廃棄 (tombstone) イベントを出力します。tombstone イベントは、同じキーを持つすべてのメッセージを削除できることを Kafka に通知します。

4.4. Debezium コネクターと連携する MongoDB の設定

MongoDB コネクターは MongoDB の oplog を使用して変更をキャプチャーするため、コネクターは MongoDB レプリカセットと、各シャードが個別のレプリカセットであるシャードクラスターとのみ動作します。レプリカセット またはシャードクラスターの設定については、MongoDB ドキュメントを参照してください。また、レプリカセットで アクセス制御と認証を有効にする方法についても理解するようにしてください。

oplog が読み取られる admin データベースを読み取るために適切なロールを持つ MongoDB ユーザーも必要です。さらに、ユーザーはシャードクラスターの設定サーバーで config データベースを読み取りできる必要もあり、listDatabases 権限も必要です。

4.5. Debezium MongoDB コネクターのデプロイ

Debezium MongoDB コネクターをデプロイするには、コネクターファイルを Kafka Connect に追加し、コネクターを実行するカスタムコンテナーを作成して、コネクター設定をコンテナーに追加します。詳細は以下を参照してください。

4.5.1. Debezium MongoDB コネクターのデプロイ

Debezium MongoDB コネクターをデプロイするには、Debezium コネクターアーカイブが含まれるカスタム Kafka Connect コンテナーイメージをビルドし、続いてこのコンテナーイメージをコンテナーレジストリーにプッシュする必要があります。その後、2 つのカスタムリソース (CR) を作成します。

  • Kafka Connect インスタンスを定義する KafkaConnect CR。CR の image プロパティーは、Debezium コネクターを実行するために作成するコンテナーイメージの名前を指定します。この CR を、Red Hat AMQ Streams がデプロイされている OpenShift インスタンスに適用します。AMQ Streams は、Apache Kafka を OpenShift に取り入れる Operator およびイメージを提供します。
  • Debezium MongoDB コネクターを定義する KafkaConnector CR。この CR を KafkaConnect CR を適用するのと同じ OpenShift インスタンスに適用します。

前提条件

  • MongoDB が稼働状態にあり、Debezium コネクターと連携するように MongoDB を設定する 手順を完了している必要があります。
  • AMQ Streams が OpenShift にデプロイされ、Apache Kafka および Kafka Connect を実行している。詳細は、『Deploying and Upgrading AMQ Streams on OpenShift』を参照してください。
  • Podman または Docker がインストールされている。
  • Debezium コネクターを実行するコンテナーを追加する予定のコンテナーレジストリー (quay.iodocker.io など) でコンテナーを作成および管理するアカウントとパーミッションを持っている。

手順

  1. Kafka Connect の Debezium MongoDB コンテナーを作成します。

    1. Debezium MongoDB コネクターアーカイブ をダウンロードします。
    2. Debezium MongoDB コネクターアーカイブを展開して、コネクタープラグインのディレクトリー構造を作成します。以下に例を示します。

      ./my-plugins/
      ├── debezium-connector-mongodb
      │   ├── ...
    3. registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0 をベースイメージとして使用する Docker ファイルを作成します。たとえば、ターミナルウィンドウに以下を入力し、my-plugins をプラグインディレクトリーの名前に置き換えます。

      cat <<EOF >debezium-container-for-mongodb.yaml 1
      FROM registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0
      USER root:root
      COPY ./<my-plugins>/ /opt/kafka/plugins/ 2
      USER 1001
      EOF
      1 1 1 1 1 1 1
      任意のファイル名を指定できます。
      2 2 2 2 2 2 2
      my-plugins をプラグインディレクトリーの名前に置き換えます。

      このコマンドは、現在のディレクトリーに debezium-container-for-mongodb.yaml という名前の Docker ファイルを作成します。

    4. 前のステップで作成した debezium-container-for-mongodb.yaml Docker ファイルからコンテナーイメージをビルドします。ファイルを含むディレクトリーから、ターミナルウィンドウを開き、以下のコマンドのいずれかを入力します。

      podman build -t debezium-container-for-mongodb:latest .
      docker build -t debezium-container-for-mongodb:latest .

      上記のコマンドは、debezium-container-for-mongodb という名前のコンテナーイメージをビルドします。

    5. カスタムイメージを quay.io などのコンテナーレジストリーまたは内部のコンテナーレジストリーにプッシュします。コンテナーレジストリーは、イメージをデプロイする OpenShift インスタンスで利用できる必要があります。以下のいずれかのコマンドを実行します。

      podman push <myregistry.io>/debezium-container-for-mongodb:latest
      docker push <myregistry.io>/debezium-container-for-mongodb:latest
    6. 新しい Debezium MongoDB KafkaConnect カスタムリソース (CR) を作成します。たとえば、以下の例のように、annotations および image プロパティーを指定する dbz-connect.yaml という名前の KafkaConnect CR を作成します。

      apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnect
      metadata:
        name: my-connect-cluster
        annotations:
          strimzi.io/use-connector-resources: "true" 1
      spec:
        #...
        image: debezium-container-for-mongodb  2
      1
      KafkaConnector リソースはこの Kafka Connect クラスターでコネクターを設定するために使用されることを、metadata.annotations は Cluster Operator に示します。
      2
      spec.image は Debezium コネクターを実行するために作成したイメージの名前を指定します。このプロパティーによって Cluster Operator の STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 変数がオーバーライドされます。
    7. 以下のコマンドを入力して、KafkaConnect CR を OpenShift Kafka Connect 環境に適用します。

      oc create -f dbz-connect.yaml

      このコマンドは、Debezium コネクターを実行するために作成したイメージの名前を指定する Kafka Connect インスタンスを追加します。

  2. Debezium MongoDB コネクターインスタンスを設定する KafkaConnector カスタムリソースを作成します。

    コネクターの設定プロパティーを指定する .yaml ファイルで Debezium MongoDB コネクターを設定します。コネクター設定は、Debezium に対して MongoDB レプリカセットまたはシャードクラスターのサブセットの変更イベントを生成するよう指示することがあります。任意で、不要なコレクションをフィルタリングするプロパティーを設定できます。

    以下の例では、192.168.99.100 上のポート 27017 で MongoDB レプリカセット rs0 に接続し、inventory コレクションで発生する変更をキャプチャーする Debezium コネクターを設定します。fullfillment はレプリカセットの論理名です。

    MongoDB inventory-connector.yaml

    apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnector
      metadata:
        name: inventory-connector 1
        labels: strimzi.io/cluster: my-connect-cluster
      spec:
        class: io.debezium.connector.mongodb.MongoDbConnector 2
        config:
         mongodb.hosts: rs0/192.168.99.100:27017 3
         mongodb.name: fulfillment 4
         collection.include.list: inventory[.]* 5

    1
    コネクターを Kafka Connect に登録するために使用される名前。
    2
    MongoDB コネクタークラスの名前。
    3
    MongoDB レプリカセットへの接続に使用するホストアドレス。
    4
    生成されたイベントの namespace を形成する MongoDB レプリカセットの論理名。コネクターが書き込む Kafka トピックの名前、Kafka Connect スキーマ名、および Arvo コンバーターが使用される場合に対応する Avro スキーマの namespace のすべてに使用されます。
    5
    監視するすべてのコレクションのコレクション namespace (例: <dbName>.<collectionName>) と一致する正規表現のオプションリスト。
  3. Kafka Connect でコネクターインスタンスを作成します。たとえば、KafkaConnector リソースを inventory-connector.yaml ファイルに保存した場合は、以下のコマンドを実行します。

    oc apply -f inventory-connector.yaml

    上記のコマンドにより inventory-connector が登録され、コネクターは KafkaConnector CR で定義された inventory コレクションに対して実行を開始します。

  4. コネクターが作成され、起動されたことを確認します。

    1. Kafka Connect ログ出力を表示して、コネクターが作成され、指定データベースの変更のキャプチャーが開始されたことを確認します。

      oc logs $(oc get pods -o name -l strimzi.io/cluster=my-connect-cluster)
    2. ログの出力を確認し、Debezium が初回のスナップショットを実行することを確認します。ログには、以下のメッセージと同様の出力が表示されます。

      ... INFO Starting snapshot for ...
      ... INFO Snapshot is using user 'debezium' ...

      コネクターがエラーがなく正常に起動すると、コネクターが変更をキャプチャーする各コレクションのトピックが作成されます。前述の例の CR には、collection.include.list プロパティーに指定されたコレクションのトピックがあります。ダウンストリームアプリケーションは、コネクターによって作成されるトピックをサブスクライブできます。

    3. 以下のコマンドを実行して、コネクターによってトピックが作成されたことを検証します。

      oc get kafkatopics

Debezium MongoDB コネクターに設定できる設定プロパティーの完全リストは、「MongoDB コネクター設定プロパティー」を参照してください。

結果

コネクターが起動すると、以下のアクションを完了します。

  • MongoDB レプリカセットのコレクションの 整合性スナップショットを実行します
  • レプリカセットの oplogs を読み取ります。
  • 挿入、更新、および削除されたすべてのドキュメントの変更イベントを生成します。
  • 変更イベントレコードを Kafka トピックへストリーミングします。

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

Debezium MongoDB コネクターには、アプリケーションに適したコネクター動作を実現するために使用できる設定プロパティーが多数あります。多くのプロパティーにはデフォルト値があります。プロパティーに関する情報は、以下のように構成されています。

以下の設定プロパティーは、デフォルト値がない場合は必須です。

表4.7 必要な Debezium MongoDB コネクター設定プロパティー

プロパティーデフォルト説明

name

 

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

connector.class

 

コネクターの Java クラスの名前。MongoDB コネクターには常に io.debezium.connector.mongodb.MongoDbConnector の値を使用します。

mongodb.hosts

 

レプリカセットでの MongoDB サーバーのホスト名とポートのペア ('host' または 'host:port' 形式) のコンマ区切りリスト。リストには、ホスト名とポートのペアを 1 つ含めることができます。mongodb.members.auto.discoverfalse に設定されている場合、ホストとポートのペアの前にレプリカセット名 (例: rs0/localhost:27017) を付ける必要があります。

mongodb.name

 

このコネクターが監視するコネクターや MongoDB レプリカセット、またはシャードクラスターを識別する一意の名前。このサーバー名は、MongoDB レプリカセットまたはクラスターから生成される永続化されたすべての Kafka トピックのプレフィックスになるため、各サーバーは最大 1 つの Debezium コネクターによって監視される必要があります。英数字とアンダースコアのみを使用する必要があります。

mongodb.user

 

MongoDB への接続時に使用されるデータベースユーザーの名前。これは MongoDB が認証を使用するように設定されている場合にのみ必要です。

mongodb.password

 

MongoDB への接続時に使用されるパスワード。これは MongoDB が認証を使用するように設定されている場合にのみ必要です。

mongodb.authsource

admin

MongoDB クレデンシャルが含まれるデータベース (認証ソース)。これは、MongoDB が admin 以外の認証データベースで認証を使用するよう設定されている場合に必要です。

mongodb.ssl.enabled

false

コネクターは SSL を使用して MongoDB インスタンスに接続します。

mongodb.ssl.invalid.hostname.allowed

false

SSL が有効な場合、接続フェーズ中に厳密なホスト名のチェックを無効にするかどうかを制御する設定です。true に設定すると、接続で中間者攻撃は阻止されません。

database.include.list

空の文字列

監視するデータベース名と一致する正規表現のコンマ区切りリスト (任意)。database.include.list に含まれていないデータベース名は、監視から除外されます。デフォルトでは、すべてのデータベースが監視されます。database.exclude.list と併用しないでください。

database.exclude.list

空の文字列

監視から除外されるデータベース名と一致する正規表現のコンマ区切りリスト (任意)。database.exclude.list に含まれていないデータベース名が監視の対象となります。database.include.list と併用しないでください。

collection.include.list

空の文字列

監視する MongoDB コレクションの完全修飾 namespace と一致する正規表現のコンマ区切りリスト (任意)。collection.include.list に含まれていないコレクションはすべて監視から除外されます。各識別子の形式は databaseName.collectionName です。デフォルトでは、local および admin データベースにあるコレクションを除くすべてのコレクションがコネクターによって監視されます。collection.exclude.list と併用しないでください。

collection.exclude.list

空の文字列

監視から除外される MongoDB コレクションの完全修飾 namespace と一致する正規表現のコンマ区切りリスト (任意)。collection.exclude.list に含まれていないコレクションはすべて監視されます。各識別子の形式は databaseName.collectionName です。collection.include.list と併用しないでください。

snapshot.mode

initial

コネクターの起動時にスナップショットを実行する基準を指定します。デフォルトは initial で、オフセットが見つからない場合や oplog に以前のオフセットが含まれなくなった場合にコネクターがスナップショットを読み取るように指定します。never オプションは、コネクターはスナップショットを使用せずに、ログをの追跡を続行すべきであることを指定します。

snapshot.include.collection.list

collection.include.list に指定されたすべてのコレクション

スナップショットを作成したい collection.include.list に指定されたスキーマの名前と一致する正規表現のコンマ区切りリスト (任意)。

field.exclude.list

空の文字列

変更イベントメッセージ値から除外される必要があるフィールドの完全修飾名のコンマ区切りリスト (任意)。フィールドの完全修飾名の形式はdatabaseName.collectionName.fieldName.nestedFieldName で、databaseName および collectionName にはすべての文字と一致するワイルドカード (*) が含まれることがあります。

field.renames

空の文字列

イベントメッセージ値のフィールドの名前を変更するために使用されるフィールドの完全修飾置換のコンマ区切りリスト (任意)。フィールドの完全修飾置換の形式は databaseName.collectionName.fieldName.nestedFieldName:newNestedFieldName で、databaseName および collectionName にはすべての文字と一致するワイルドカード (*) が含まれることがあります。コロン (:) は、フィールドの名前変更マッピングを決定するために使用されます。次のフィールドの置換は、リストの前のフィールド置換の結果に適用されるため、同じパスにある複数のフィールドの名前を変更する場合は、この点に注意してください。

tasks.max

1

このコネクターのために作成する必要のあるタスクの最大数。MongoDB コネクターは各レプリカセットに個別のタスクの使用しようとします。そのため、コネクターを単一の MongoDB レプリカセットと使用する場合は、デフォルトを使用できます。MongoDB のシャードクラスターでコネクターを使用する場合、クラスターのシャード数以上の値を指定して、各レプリカセットの作業が Kafka Connect によって分散されるようにすることが推奨されます。

snapshot.max.threads

1

レプリカセットでコレクションの最初の同期を実行するために使用されるスレッドの最大数を指定する正の整数値。デフォルトは 1 です。

tombstones.on.delete

true

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

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

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

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

snapshot.delay.ms

 

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

snapshot.fetch.size

0

スナップショットの実行中に各コレクションから 1 度に読み取る必要があるドキュメントの最大数を指定します。コネクターは、このサイズの複数のバッチでコレクションの内容を読み取ります。
デフォルトは 0 で、サーバーが適切なフェッチサイズを選択することを示します。

以下の 高度な 設定プロパティーには、ほとんどの状況で機能する適切なデフォルト設定があるため、コネクターの設定で指定する必要はほとんどありません。

表4.8 必要な Debezium MongoDB コネクターの高度な設定プロパティー

プロパティーデフォルト説明

max.queue.size

8192

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

max.batch.size

2048

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

max.queue.size.in.bytes

0

ブロッキングキューの最大サイズ (バイト単位) の long 値。この機能はデフォルトで無効になっています。正の long 値が設定されると有効になります。

poll.interval.ms

1000

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

connect.backoff.initial.delay.ms

1000

最初に失敗した接続試行の後またはプライマリーが利用できない場合に、プライマリーへの再接続を試行するときの最初の遅延を指定する正の整数値。デフォルトは 1 秒 (1000 ミリ秒) です。

connect.backoff.max.delay.ms

1000

接続試行に繰り返し失敗した後またはプライマリーが利用できない場合に、プライマリーへの再接続を試行するときの最大遅延を指定する正の整数値。デフォルトは 120 秒 (120,000 ミリ秒) です。

connect.max.attempts

16

レプリカセットのプライマリーへの接続を試行する場合の最大失敗回数を指定する正の整数値。この値を越えると、例外が発生し、タスクが中止されます。デフォルトは 16 で、connect.backoff.initial.delay.ms のデフォルトであり、connect.backoff.max.delay.ms の場合は失敗する前に 20 分以上試行されます。

mongodb.members.auto.discover

true

'mongodb.hosts' 内のアドレスがクラスターまたはレプリカセットの全メンバーを検出するために使用されるシードであるかどうか (true)、または mongodb.hosts のアドレスをそのまま使用する必要があるかどうか (false) を指定するブール値。デフォルトは true で、MongoDB が プロキシーと面する 場合を除き、すべてのケースで使用する必要があります。

heartbeat.interval.ms

0

ハートビートメッセージが送信される頻度を制御します。
このプロパティーには、コネクターがメッセージをハートビートトピックに送信する頻度を定義する間隔 (ミリ秒単位) が含まれます。これは、コネクターがデータベースから変更イベントを受信しているかどうかを監視するために使用できます。また、長期に渡り変更されるのはキャプチャーされていないコレクションのレコードのみである場合は、ハートビートメッセージを利用する必要があります。このような場合、コネクターはデータベースからの oplog の読み取りを続行しますが、変更メッセージを Kafka に出力しないため、オフセットの更新が Kafka にコミットされません。これにより、oplog ファイルがローテーションされますが、コネクターはこれを認識しないため、再起動時に一部のイベントが利用できなくなり、最初のスナップショットの再実行が必要になります。

このプロパティーを 0 に設定して、ハートビートメッセージが全く送信されないようにします。
デフォルトでは無効にされています。

heartbeat.topics.prefix

__debezium-heartbeat

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

sanitize.field.names

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

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

skipped.operations

 

ストリーミング中にスキップされる oplog 操作のコンマ区切りリスト。操作には、c (挿入/作成)、u (更新)、および d (削除) が含まれます。デフォルトでは、操作はスキップされません。

snapshot.collection.filter.overrides

 

スナップショットに含まれるコレクション項目を制御します。このプロパティーはスナップショットにのみ影響します。databaseName.collectionName の形式でコレクション名のコンマ区切りリストを指定します。

指定するコレクションごとに別の設定プロパティーも指定します: snapshot.collection.filter.overrides.databaseName.collectionName たとえば、別の設定プロパティーの名前が snapshot.collection.filter.overrides.customers.orders であるとします。このプロパティーは、スナップショットで必要なアイテムのみを取得する有効なフィルター式に設定します。コネクターがスナップショットを実行すると、フィルター式と一致する項目のみを取得します。

provide.transaction.metadata

false

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

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

retriable.restart.connector.wait.ms

10000 (10 秒)

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

mongodb.poll.interval.ms

30000

コネクターが新規、削除、または変更したレプリカセットをポーリングする間隔。

mongodb.connect.timeout.ms

10000 (10 秒)

新しい接続試行が中断されるまでドライバーが待機する時間 (ミリ秒単位)。

mongodb.socket.timeout.ms

0

ソケットでの送受信がタイムアウトするまでにかかる時間 (ミリ秒単位)。0 の値は、この動作を無効にします。

mongodb.server.selection.timeout.ms

30000 (30 秒)

ドライバーがタイムアウトし、エラーがスローされる前に、サーバーが選択されるまでドライバーが待つ時間 (ミリ秒単位)。

4.6. Debezium MongoDB コネクターのパフォーマンスの監視

Debezium MongoDB コネクターには、Zookeeper、Kafka、および Kafka Connect にある JMX メトリクスの組み込みサポートに加えて、2 種類のメトリクスがあります。

Debezium モニタリングのドキュメント では、JMX を使用してこれらのメトリクスを公開する方法の詳細を提供します。

4.6.1. MongoDB スナップショット時の Debezium の監視

MBeandebezium.mongodb:type=connector-metrics,context=snapshot,server=<mongodb.name> です。

属性説明

LastEvent

string

コネクターが読み取りした最後のスナップショットイベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取りおよび処理してからの経過時間 (ミリ秒単位)。

TotalNumberOfEventsSeen

long

前回の開始またはリセット以降にコネクターで確認されたイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定された include/exclude リストのフィルタリングルールによってフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルの一覧。

QueueTotalCapacity

int

snapshotter とメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの長さ。

QueueRemainingCapacity

int

snapshotter とメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの空き容量。

TotalTableCount

int

スナップショットに含まれているテーブルの合計数。

RemainingTableCount

int

スナップショットによってまだコピーされていないテーブルの数。

SnapshotRunning

boolean

スナップショットが起動されたかどうか。

SnapshotAborted

boolean

スナップショットが中断されたかどうか。

SnapshotCompleted

boolean

スナップショットが完了したかどうか。

SnapshotDurationInSeconds

long

スナップショットが完了したかどうかに関わらず、これまでスナップショットにかかった時間 (秒単位)。

RowsScanned

Map<String, Long>

スナップショットの各テーブルに対してスキャンされる行数が含まれるマップ。テーブルは、処理中に増分がマップに追加されます。スキャンされた 10,000 行ごとに、テーブルの完成時に更新されます。

MaxQueueSizeInBytes

long

キューの最大バッファー (バイト単位)。max.queue.size.in.bytes が正の long 値で渡された場合に有効になります。

CurrentQueueSizeInBytes

long

キュー内のレコードの現在のデータ (バイト単位)。

Debezium MongoDB コネクターは、以下のカスタムスナップショットメトリクスも提供します。

属性説明

NumberOfDisconnects

long

データベースの切断数。

4.6.2. Debezium MongoDB コネクターレコードストリーミングの監視

MBeandebezium.sql_server:type=connector-metrics,context=streaming,server=<mongodb.name> です。

属性説明

LastEvent

string

コネクターが読み取られた最後のストリーミングイベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取りおよび処理してからの経過時間 (ミリ秒単位)。

TotalNumberOfEventsSeen

long

前回の開始またはリセット以降にコネクターで確認されたイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定された include/exclude リストのフィルタリングルールによってフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルの一覧。

QueueTotalCapacity

int

ストリーマーとメイン Kafka Connect ループの間でイベントを渡すために使用されるキューの長さ。

QueueRemainingCapacity

int

ストリーマーとメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの空き容量。

Connected

boolean

コネクターが現在データベースサーバーに接続されているかどうかを示すフラグ。

MilliSecondsBehindSource

long

最後の変更イベントのタイムスタンプとそれを処理するコネクターとの間の期間 (ミリ秒単位)。この値は、データベースサーバーとコネクターが稼働しているマシンのクロック間の差異に対応します。

NumberOfCommittedTransactions

long

コミットされた処理済みトランザクションの数。

SourceEventPosition

Map<String, String>

最後に受信したイベントの位置。

LastTransactionId

string

最後に処理されたトランザクションのトランザクション識別子。

MaxQueueSizeInBytes

long

キューの最大バッファー (バイト単位)。

CurrentQueueSizeInBytes

long

キュー内のレコードの現在のデータ (バイト単位)。

Debezium MongoDB コネクターは、以下のカスタムストリーミングメトリクスも提供します。

属性説明

NumberOfDisconnects

long

データベースの切断数。

NumberOfPrimaryElections

long

プライマリーノードの選出数。

4.7. Debezium MongoDB コネクターによる障害および問題の処理方法

Debezium は、複数のアップストリームデータベースのすべての変更をキャプチャーする分散システムであり、イベントの見逃しや損失は発生しません。システムが正常に稼働し、慎重に管理されている場合は、Debezium は変更イベントごとに 1 度だけ 配信します。

障害が発生しても、システムはイベントを失いません。ただし、障害から復旧している間は、変更イベントが繰り返えされる可能性があります。このような正常でない状態では、Debezium は Kafka と同様に、変更イベントを 少なくとも 1 回 配信します。

以下のトピックでは、Debezium MongoDB コネクターがさまざまな障害や問題をどのように処理するかについて説明します。

設定および起動エラー

以下の状況では、起動時にコネクターが失敗し、エラーまたは例外がログに記録され、実行が停止されます。

  • コネクターの設定が無効である。
  • 指定の接続パラメーターを使用してコネクターを MongoDB に接続できない。

障害が発生した後、コネクターは指数バックオフを使用して再接続を試みます。再接続試行の最大数を設定できます。

このような場合、エラーには問題の詳細が含まれ、場合によっては回避策が提示されます。設定が修正されたり、MongoDB の問題が解決された場合はコネクターを再起動できます。

MongoDB が使用不可能になる

コネクターが実行され、MongoDB レプリカセットのプライマリーノードが利用できなくなったり、アクセスできなくなったりすると、コネクターは指数バックオフを使用してプライマリーノードへの再接続を繰り返し試み、ネットワークやサーバーが飽和状態にならないようにします。設定可能な接続試行回数を超えた後もプライマリーが利用できない状態である場合、コネクターは失敗します。

再接の続試行は、3 つのプロパティーで制御されます。

  • connect.backoff.initial.delay.ms - 初回の再接続を試みるまでの遅延。デフォルトは 1 秒 (1000 ミリ秒) です。
  • connect.backoff.max.delay.ms - 再接続を試行するまでの最大遅延。デフォルトは 120 秒 (120,000 ミリ秒) です。
  • connect.max.attempts - エラーが生成されるまでの最大試行回数。デフォルトは 16 です。

各遅延は、最大遅延以下で、前の遅延の 2 倍です。以下の表は、デフォルト値を指定した場合の、失敗した各接続試行の遅延と、失敗前の合計累積時間を表しています。

再接続試行回数試行までの遅延 (秒単位)試行までの遅延合計 (分および秒単位)

1

1

00:01

2

2

00:03

3

4

00:07

4

8

00:15

5

16

00:31

6

32

01:03

7

64

02:07

8

120

04:07

9

120

06:07

10

120

08:07

11

120

10:07

12

120

12:07

13

120

14:07

14

120

16:07

15

120

18:07

16

120

20:07

Kafka Connect のプロセスは正常に停止する

Kafka Connect が分散モードで実行され、Kafka Connect プロセスが正常に停止された場合は、Kafka Connect はプロセスのシャットダウン前に、すべてのプロセスのコネクタータスクをそのグループの別の Kafka Connect プロセスに移行し、新しいコネクタータスクは、以前のタスクが停止した場所で開始されます。コネクタータスクが正常に停止され、新しいプロセスで再起動されるまでの間、プロセスに短い遅延が発生します。

グループにプロセスが 1 つだけあり、そのプロセスが正常に停止された場合、Kafka Connect はコネクターを停止し、各レプリカセットの最後のオフセットを記録します。再起動時に、レプリカセットタスクは停止した場所で続行されます。

Kafka Connect プロセスのクラッシュ

Kafka Connector プロセスが予期せず停止した場合、最後に処理されたオフセットを記録せずに、実行中のコネクタータスクが終了します。Kafka Connect が分散モードで実行されている場合は、他のプロセスでこれらのコネクタータスクを再起動します。ただし、MongoDB コネクターは以前のプロセスによって 記録 された最後のオフセットから再開します。つまり、新しい代替タスクによって、クラッシュの直前に処理された同じ変更イベントが生成される可能性があります。重複するイベントの数は、オフセットのフラッシュ期間とクラッシュの直前のデータ変更の量によって異なります。

注記

障害からの復旧中に一部のイベントが重複された可能性があるため、コンシューマーは常に一部のイベントが重複している可能性があることを想定する必要があります。Debezium の変更はべき等であるため、一連のイベントは常に同じ状態になります。

Debezium の各変更イベントメッセージには、イベントの生成元に関するソース固有の情報が含まれます。これには、MongoDB イベントの一意なトランザクション識別子 (h) やタイムスタンプ (sec および ord) が含まれます。コンシューマーはこれらの値の他の部分を追跡し、特定のイベントがすでに発生しているかどうかを確認することができます。

Kafka が使用不可能になる

変更イベントはコネクターによって生成されるため、Kafka Connect フレームワークは、Kafka プロデューサー API を使用してこれらのイベントを記録します。また、Kafka Connect は、これらの変更イベントに発生する最新のオフセットを Kafka Connect ワーカー設定で指定した頻度で定期的に記録します。Kafka ブローカーが利用できなくなると、コネクターを実行する Kafka Connect ワーカープロセスは Kafka ブローカーへの再接続を繰り返し試行します。つまり、コネクタータスクは接続が再確立されるまで一時停止します。接続が再確立されると、コネクターは停止した場所から再開します。

長期間コネクターが停止している。

コネクターが正常に停止された場合、レプリカセットは引き続き使用でき、新しい変更は MongoDB の oplog に記録されます。コネクターが再起動されると、最後に停止した場所で各レプリカセットの変更のストリーミングを再開し、コネクターが停止した間に加えられたすべての変更の記録イベントを記録します。コネクターが一定期間停止し、コネクターが読み取っていない一部の操作を MongoDB が oplog からパージするようになると、コネクターは起動時にスナップショットを実行します。

Kafka クラスターを適切に設定すると、大量のスループットを実現できます。Kafka Connect は Kafka のベストプラクティスを使用して記述され、十分なリソースがあれば非常に多くのデータベース変更イベントを処理できます。そのため、コネクターがしばらくして再起動されると、データベースに追いつく可能性が非常に高くなりますが、遅れを取り戻すまでに掛かる時間は、Kafka の機能やパフォーマンスおよび MongoDB のデータへの変更の量に応じて異なります。

注記

コネクターが長時間停止した場合、MongoDB が古い oplog ファイルをパージし、コネクターの最後の位置が失われる可能性があります。この場合、最初 のスナップショットモード (デフォルト) で設定されたコネクターが最終的に再起動されると、MongoDB サーバーには開始点がなくなり、コネクターはエラーによって失敗します。

MongoDB による書き込みの損失

特定の障害状況では、MongoDB がコミットを失う可能性があり、MongoDB コネクターが失われた変更をキャプチャーできなくなります。たとえば、プライマリーが変更を適用した後に突然クラッシュし、その oplog に変更を記録すると、セカンダリーノードがそのコンテンツを読み取る前に oplog が利用できなくなる可能性があります。その結果、新しいプライマリーノードとして選択されるセカンダリーノードには、その oplog からの最新の変更が欠落する可能性があります。

現時点では、MongoDB でこの副次的な影響を防ぐ方法はありません。

第5章 MySQL の Debezium コネクター

重要

本リリースの Debezium MySQL コネクターには、他の Debezium コネクターによって使用される一般的なコネクターフレームワークをベースとした新しいデフォルトキャプチャー実装が含まれています。改訂されたキャプチャー実装はテクノロジープレビュー機能です。テクノロジープレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat はテクノロジープレビュー機能を実稼働環境に実装することは推奨しません。テクノロジープレビューの機能は、最新の技術をいち早く提供して、開発段階で機能のテストやフィードバックの収集を可能にするために提供されます。サポート範囲の詳細は、「テクノロジプレビュー機能のサポート範囲」を参照してください。

新しいキャプチャー実装と共に実行中にコネクターでエラーや予期しない動作を生じる場合は、以下の設定オプションを設定して以前の実装に戻すことができます。

internal.implementation=legacy

MySQL には、データベースにコミットされた順序ですべての操作を記録するバイナリーログ (binlog) があります。これには、テーブルスキーマの変更やテーブルのデータの変更が含まれます。MySQL はレプリケーションとリカバリーに binlog を使用します。

Debezium MySQL コネクターは binlog を読み取り、行レベルの INSERTUPDATE、および DELETE 操作の変更イベントを生成し、変更イベントを Kafka トピックに出力します。クライアントアプリケーションはこれらの Kafka トピックを読み取ります。

MySQL は通常、指定期間後に binlogs をパージするように設定されているため、MySQL コネクターは各データベースの最初の整合性スナップショット を実行します。MySQL コネクターは、スナップショットが作成された時点から binlog を読み取ります。

Debezium MySQL コネクターの使用に関する情報および手順は、以下のように整理されています。

5.1. Debezium MySQL コネクターの仕組み

コネクターがサポートする MySQL トポロジーの概要は、アプリケーションを計画するときに役立ちます。Debezium MySQL コネクターを最適に設定および実行するには、コネクターによるテーブルの構造の追跡方法、スキーマ変更の公開方法、スナップショットの実行方法、および Kafka トピック名の決定方法を理解しておくと便利です。

詳細は以下を参照してください。

5.1.1. Debezium コネクターでサポートされる MySQL トポロジー

Debezium MySQL コネクターは以下の MySQL トポロジーをサポートします。

スタンドアロン
単一の MySQL サーバーを使用する場合は、Debezium MySQL コネクターがサーバーを監視できるように、binlog を有効 (および任意で GTID を有効) にする必要があります。バイナリーログも増分バックアップとして使用できるため、これは多くの場合で許容されます。この場合、MySQL コネクターは常にこのスタンドアロン MySQL サーバーインスタンスに接続し、それに従います。
プライマリーおよびレプリカ

Debezium MySQL コネクターはプライマリーサーバーまたはレプリカの 1 つ (レプリカの binlog が有効になっている場合) に従うことができますが、コネクターはサーバーが認識できるクラスターのみで変更を確認できます。通常、これはマルチプライマリートポロジー以外では問題ではありません。

コネクターは、サーバーの binlog の位置を記録します。この位置は、クラスターの各サーバーごとに異なります。そのため、コネクターは 1 つの MySQL サーバーインスタンスのみに従う必要があります。このサーバーに障害が発生した場合、サーバーを再起動またはリカバリーしないと、コネクターは継続できません。

高可用性クラスター
MySQL にはさまざまな 高可用性 ソリューションが存在し、問題や障害の耐性をつけ、即座に回復することが大変容易になります。ほとんどの HA MySQL クラスターは GTID を使用します。そのため、レプリカはあらゆるプライマリーサーバーの変更をすべて追跡できます。
マルチプライマリー

ネットワークデータベース (NDB) クラスターのレプリケーション は、複数のプライマリーアーバーからそれぞれをレプリケートする 1 つ以上の MySQL レプリカを使用します。これは、複数の MySQL クラスターのレプリケーションを集約する強力な方法です。このトポロジーには GTID を使用する必要があります。

Debezium MySQL コネクターはこれらのマルチプライマリー MySQL レプリカをソースとして使用することができ、新しいレプリカが古いレプリカに追い付けば、異なるマルチプライマリー MySQL レプリカにフェイルオーバーできます。つまり、新しいレプリカには最初のレプリカで確認されたすべてのトランザクションが含まれます。これは、新しいマルチプライマリー MySQL レプリカへの再接続を試み、binlog で適切な場所を見つけようとする際に、特定の GTID ソースが含まれるまたは除外されるようにコネクターを設定できるため、コネクターがデータベースやテーブルのサブセットのみを使用している場合でも機能します。

ホステッド

Debezium MySQL コネクターが Amazon RDS や Amazon Aurora などのホステッドオプションを使用するためのサポートがあります。

これらのホステッドオプションではグローバル読み取りロックが許可されないため、テーブルレベルロックを使用して 整合性スナップショット を作成します。

5.1.2. Debezium MySQL コネクターによるデータベーススキーマの変更の処理方法

データベースクライアントがデータベースのクエリーを行うと、クライアントはデータベースの現在のスキーマを使用します。しかし、データベーススキーマはいつでも変更が可能です。そのため、挿入、更新、または削除の操作が記録されるたびに、コネクターはどのスキーマであるかを特定できる必要があります。また、コネクターが比較的古いイベントを処理し、テーブルのスキーマが変更される前に記録された可能性があるため、コネクターは現在のスキーマのみを使用することはできません。

これに対応するために、MySQL の binlog にはデータの行レベルの変更だけでなく、データベースに適用される DDL ステートメントも含まれます。コネクターは binlog を読み取り、DDL ステートメントを見つけると、それらの DDL ステートメントを解析し、各テーブルのスキーマのインメモリー表現を更新します。コネクターはこのスキーマ表現を使用して、挿入、更新、または削除の操作時にテーブルの構造を特定し、適切な変更イベントを生成します。別のデータベース履歴 Kafka トピックでは、コネクターは各 DDL ステートメントがある binlog の場所とともにすべての DDL ステートメントを記録します。

コネクターが正常にクラッシュまたは停止された後にコネクターが再起動されると、コネクターは特定の場所 (特定の時点) から binlog の読み取りを開始します。コネクターは、データベース履歴の Kafka トピックを読み取り、コネクターが起動する binlog の時点まですべての DDL ステートメントを解析することで、この時点で存在したテーブル構造を再ビルドします。

このデータベース履歴トピックはコネクターのみが使用します。コネクターは任意で、コンシューマーアプリケーション向けの異なるトピックへのスキーマ変更イベントの生成を表示でき ます。

MySQL コネクターが、gh-ostpt-online-schema-change などのスキーマ変更ツールが適用されるテーブルで変更をキャプチャーすると、移行プロセス中にヘルパーテーブルが作成されます。これらのヘルパーテーブルへの変更をキャプチャーするようにコネクターを設定する必要があります。ヘルパーテーブル用に生成されたレコードがコンシューマーに必要ない場合は、単一メッセージ変換を適用して、除去できます。

Debezium イベントレコードを受信する トピックのデフォルト名 を参照してください。

5.1.3. Debezium MySQL コネクターによるデータベーススキーマの変更の公開方法

Debezium MySQL コネクターを設定すると、MySQL サーバーのデータベースに適用されるすべての DDL ステートメントが含まれるスキーマ変更イベントを生成できます。コネクターは、これらのイベントを serverName という名前の Kafka トピックに出力します。serverName は、database.server.name コネクター設定プロパティーによって指定されるコネクターの名前になります。

スキーマ変更イベント の使用を選択した場合、スキーマ変更トピックからレコードを使用するようにしてください。データベース履歴トピックはコネクターのみが使用します。

重要

スキーマ変更トピックに出力されたイベントのグローバルな順序は重要です。したがって、データベース履歴のトピックをパーティション化しないでください。つまり、データベース履歴トピックの作成時にパーティション数として 1 を指定する必要があります。自動トピックの作成に依存する場合は、デフォルトのパーティション数を指定する Kafka の num.partitions 設定オプションが 1 に設定されていることを確認します。

コネクターがスキーマ変更トピックに出力する各レコードには、DDL ステートメントの適用時に接続されたデータベースの名前を含むメッセージキーが含まれています。例を以下に示します。

{
  "schema": {
    "type": "struct",
    "name": "io.debezium.connector.mysql.SchemaChangeKey",
    "optional": false,
    "fields": [
      {
        "field": "databaseName",
        "type": "string",
        "optional": false
      }
    ]
  },
  "payload": {
    "databaseName": "inventory"
  }
}

スキーマ変更イベントレコードの値には、DDL ステートメント、ステートメントが適用されたデータベースの名前、および binlog におけるステートメントの位置を含む構造が含まれます。以下に例を示します。

{
  "schema": {
    "type": "struct",
    "name": "io.debezium.connector.mysql.SchemaChangeValue",
    "optional": false,
    "fields": [
      {
        "field": "databaseName",
        "type": "string",
        "optional": false
      },
      {
        "field": "ddl",
        "type": "string",
        "optional": false
      },
      {
        "field": "source",
        "type": "struct",
        "name": "io.debezium.connector.mysql.Source",
        "optional": false,
        "fields": [
          {
            "type": "string",
            "optional": true,
            "field": "version"
          },
          {
            "type": "string",
            "optional": false,
            "field": "name"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "server_id"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "ts_ms"
          },
          {
            "type": "string",
            "optional": true,
            "field": "gtid"
          },
          {
            "type": "string",
            "optional": false,
            "field": "file"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "pos"
          },
          {
            "type": "int32",
            "optional": false,
            "field": "row"
          },
          {
            "type": "boolean",
            "optional": true,
            "default": false,
            "field": "snapshot"
          },
          {
            "type": "int64",
            "optional": true,
            "field": "thread"
          },
          {
            "type": "string",
            "optional": true,
            "field": "db"
          },
          {
            "type": "string",
            "optional": true,
            "field": "table"
          },
          {
            "type": "string",
            "optional": true,
            "field": "query"
          }
        ]
      }
    ]
  },
  "payload": {
    "databaseName": "inventory",
    "ddl": "CREATE TABLE products ( id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255) NOT NULL, description VARCHAR(512), weight FLOAT ); ALTER TABLE products AUTO_INCREMENT = 101;",
    "source" : {
      "version": "1.5.4.Final",
      "name": "mysql-server-1",
      "server_id": 0,
      "ts_ms": 0,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 154,
      "row": 0,
      "snapshot": true,
      "thread": null,
      "db": null,
      "table": null,
      "query": null
    }
  }
}

ddl フィールドには複数の DDL ステートメントが含まれることがあります。各ステートメントは、databaseName フィールドのデータベースに適用されます。ステートメントは、データベースに適用された順序で示されます。source フィールドは、テーブル固有のトピックに書き込まれた標準のデータ変更イベントとして構成されます。このフィールドは、異なるトピックでイベントを関連付けるのに役立ちます。

....
"payload": {
    "databaseName": "inventory",
    "ddl": "CREATE TABLE products ( id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,...)",
    "source" : {
        ...
    }
}
....

クライアントは、複数のデータベースに適用される複数の DDL ステートメントを送信できます。MySQL がこれらをアトミックに適用する場合、コネクターは DDL ステートメントを順番に取得し、データベース別にグループ化して、各グループにスキーマ変更イベントを作成します。MySQL がこれらを個別に適用すると、コネクターは各ステートメントに対して個別のスキーマ変更イベントを作成します。

スキーマ履歴トピック」も参照してください。

5.1.4. Debezium MySQL コネクターによるデータベーススナップショットの実行方法

Debezium MySQL コネクターが最初に起動すると、データベースの最初の 整合性スナップショット が実行されます。以下のフローは、コネクターによってこのスナップショットが作成される方法を示しています。このフローは、デフォルト initial のスナップショットモード用です。その他のスナップショットモードの詳細は、「MySQL コネクター snapshot.mode 設定プロパティー」を参照してください。

表5.1 グローバル読み取りロックを使用して最初のスナップショットを実行するためのワークフロー

ステップアクション

1

他のデータベースクライアントによる書き込みをブロックするグローバル読み取りロックを取得します

スナップショット自体は、コネクターによる binlog の位置やテーブルスキーマの読み取りを妨害する可能性のある DDL を他のクライアントが適用しないようにする訳ではありません。コネクターは binlog の位置を読み取る間にグローバル読み取りロックを保持し、後のステップで説明するように、ロックを解除します。

2

繰り返し可能な読み取りセマンティクス でトランザクションを開始し、トランザクション内の後続の読み取りがすべて 整合性スナップショット に対して実行されるようにします。

3

現在の binlog の位置を読み取ります。

4

コネクターが変更をキャプチャーするように設定されたデータベースとテーブルのスキーマを読み取ります。

5

グローバル読み取りロックを解放します。他のデータベースクライアントがデータベースに書き込みできるようになりました。

6

該当する場合は、DDL の変更をスキーマ変更トピックに書き込みます。これには、必要な DROP…​ および CREATE…​ DDL ステートメントがすべて含まれます。

7

データベーステーブルをスキャンします。コネクターは、行ごとに、CREATE イベントを関係するテーブル固有の Kafka トピックに出力します。

8

トランザクションをコミットします。

9

コネクターオフセットの完了済みスナップショットを記録します。

コネクターの再起動

最初のスナップショット の実行中にコネクターが失敗または停止したり、再分散された場合、コネクターの再起動後に新しいスナップショットが実行されます。この 最初のスナップショット が完了すると、Debezium MySQL コネクターは binlog の同じ位置から再起動するため、更新が見逃されることはありません。

コネクターが長時間停止した場合、MySQL が古い binlog ファイルをパージし、コネクターの位置が失われる可能性があります。位置が失われた場合、コネクターは 最初のスナップショット を開始位置に戻します。Debezium MySQL コネクターのトラブルシューティングに関する詳細は、「Debezium MySQL コネクターによる障害および問題の処理方法」を参照してください。

グローバル読み取りロックが許可されない

一部の環境では、グローバル読み取りロックが許可されません。Debezium MySQL コネクターがグローバル読み取りロックが許可されないことを検出すると、代わりにテーブルレベルロックを使用して、この方法でスナップショットを実行します。これには、Debezium コネクターのデータベースユーザーに LOCK TABLES 権限が必要になります。

表5.2 テーブルレベルロックを使用して最初のスナップショットを実行するためのワークフロー

ステップアクション

1

テーブルレベルロックを取得します。

2

繰り返し可能な読み取りセマンティクス でトランザクションを開始し、トランザクション内の後続の読み取りがすべて 整合性スナップショット に対して実行されるようにします。

3

データベースとテーブルの名前を読み取り、選別します。

4

現在の binlog の位置を読み取ります。

5

コネクターが変更をキャプチャーするように設定されたデータベースとテーブルのスキーマを読み取ります。

6

該当する場合は、DDL の変更をスキーマ変更トピックに書き込みます。これには、必要な DROP…​ および CREATE…​ DDL ステートメントがすべて含まれます。

7

データベーステーブルをスキャンします。コネクターは、行ごとに、CREATE イベントを関係するテーブル固有の Kafka トピックに出力します。

8

トランザクションをコミットします。

9

テーブルレベルロックを解除します。

10

コネクターオフセットの完了済みスナップショットを記録します。

5.1.5. Debezium MySQL 変更イベントレコードを受信する Kafka トピックのデフォルト名

デフォルトの動作では、Debezium MySQL コネクターは 1 つのテーブルの INSERTUPDATE、および DELETE 操作すべてのイベントを 1 つの Kafka トピックに書き込みます。Kafka トピックの命名規則は次のとおりです。

serverName.databaseName.tableName

fulfillment はサーバー名、inventory はデータベース名で、データベースに orderscustomers、および products という名前のテーブルが含まれるとします。Debezium MySQL コネクターは、データベースのテーブルごとに 1 つずつ、3 つの Kafka トピックにイベントを出力します。

fulfillment.inventory.orders
fulfillment.inventory.customers
fulfillment.inventory.products

トランザクションメタデータ

Debezium は、トランザクション境界を表し、データ変更イベントメッセージをエンリッチするイベントを生成できます。Debezium はすべてのトランザクションの BEGIN および END に対して、以下のフィールドが含まれるイベントを生成します。

  • status - BEGIN または END
  • id - 一意のトランザクション識別子の文字列表現。
  • event_count (END イベントの場合) -トランザクションによって出力されたイベントの合計数。
  • data_collections (END イベントの場合): 指定のデータコレクションからの変更によって出力されたイベントの数を提供する data_collectionevent_count のペアの配列。

{
  "status": "BEGIN",
  "id": "0e4d5dcd-a33b-11ea-80f1-02010a22a99e:10",
  "event_count": null,
  "data_collections": null
}

{
  "status": "END",
  "id": "0e4d5dcd-a33b-11ea-80f1-02010a22a99e:10",
  "event_count": 2,
  "data_collections": [
    {
      "data_collection": "s1.a",
      "event_count": 1
    },
    {
      "data_collection": "s2.a",
      "event_count": 1
    }
  ]
}

トランザクションイベントは、database.server.name.transaction という名前のトピックに書き込まれます。

変更データイベントのエンリッチメント

トランザクションメタデータを有効にすると、データメッセージ Envelope は新しい transaction フィールドでエンリッチされます。このフィールドは、複合フィールドの形式ですべてのイベントに関する情報を提供します。

  • id - 一意のトランザクション識別子の文字列表現。
  • total_order - トランザクションによって生成されたすべてのイベントを対象とするイベントの絶対位置。
  • data_collection_order - トランザクションによって出力されたすべてのイベントを対象とするイベントのデータコレクションごとの位置。

以下は、メッセージの例になります。

{
  "before": null,
  "after": {
    "pk": "2",
    "aa": "1"
  },
  "source": {
...
  },
  "op": "c",
  "ts_ms": "1580390884335",
  "transaction": {
    "id": "0e4d5dcd-a33b-11ea-80f1-02010a22a99e:10",
    "total_order": "1",
    "data_collection_order": "1"
  }
}

GTID が有効になっていないシステムの場合、トランザクション識別子は binlog ファイル名と binlog の位置の組み合わせを使用して作成されます。たとえば、トランザクション BEGIN イベントに対応するファイル名および位置がそれぞれ mysql-bin.000002 および 1913 の場合、Debezium の構築したトランザクション識別子は file=mysql-bin.000002,pos=1913 になります。

5.2. Debezium MySQL コネクターのデータ変更イベントの説明

Debezium MySQL コネクターは、行レベルの INSERTUPDATE、および DELETE 操作ごとにデータ変更イベントを生成します。各イベントにはキーと値が含まれます。キーと値の構造は、変更されたテーブルによって異なります。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリーム を中心として設計されています。ただし、これらのイベントの構造は時間の経過とともに変化する可能性があり、コンシューマーによる処理が困難になることがあります。これに対応するために、各イベントにはコンテンツのスキーマが含まれます。スキーマレジストリーを使用している場合は、コンシューマーがレジストリーからスキーマを取得するために使用できるスキーマ ID が含まれます。これにより、各イベントが自己完結型になります。

以下のスケルトン JSON は、変更イベントの基本となる 4 つの部分を示しています。ただし、アプリケーションで使用するために選択した Kafka Connect コンバーターの設定方法によって、変更イベントのこれら 4 部分の表現が決定されます。schema フィールドは、変更イベントが生成されるようにコンバーターを設定した場合のみ変更イベントに含まれます。同様に、イベントキーおよびイベントペイロードは、変更イベントが生成されるようにコンバーターを設定した場合のみ変更イベントに含まれます。JSON コンバーターを使用し、変更イベントの基本となる 4 つの部分すべてを生成するように設定すると、変更イベントの構造は次のようになります。

{
 "schema": { 1
   ...
  },
 "payload": { 2
   ...
 },
 "schema": { 3
   ...
 },
 "payload": { 4
   ...
 },
}

表5.3 変更イベントの基本内容の概要

項目フィールド名説明

1

schema

最初の schema フィールドはイベントキーの一部です。イベントキーの payload の部分の内容を記述する Kafka Connect スキーマを指定します。つまり、最初の schema フィールドは、変更されたテーブルのプライマリーキーの構造、またはテーブルにプライマリーキーがない場合は固有のキーの構造を記述します。

message.key.columns コネクター設定プロパティー を設定すると、テーブルのプライマリーキーをオーバーライドできます。この場合、最初の schema フィールドはそのプロパティーによって識別されるキーの構造を記述します。

2

payload

最初の payload フィールドはイベントキーの一部です。前述の schema フィールドによって記述された構造を持ち、変更された行のキーが含まれます。

3

schema

2 つ目の schema フィールドはイベント値の一部です。イベント値の payload の部分の内容を記述する Kafka Connect スキーマを指定します。つまり、2 つ目の schema は変更された行の構造を記述します。通常、このスキーマには入れ子になったスキーマが含まれます。

4

payload

2 つ目の payload フィールドはイベント値の一部です。前述の schema フィールドによって記述された構造を持ち、変更された行の実際のデータが含まれます。

デフォルトでは、コネクターによって、変更イベントレコードがイベントの元のテーブルと同じ名前を持つトピックにストリーミングされます。トピック名 を参照してください。

警告

MySQL コネクターは、すべての Kafka Connect スキーマ名が Avro スキーマ名の形式 に準拠するようにします。つまり、論理サーバー名はアルファベットまたはアンダースコア (a-z、A-Z、または _) で始まる必要があります。論理サーバー名の残りの各文字と、データベース名とテーブル名の各文字は、アルファベット、数字、またはアンダースコア (a-z、A-Z、0-9、または _) でなければなりません。無効な文字がある場合は、アンダースコアに置き換えられます。

論理サーバー名、データベース名、またはテーブル名に無効な文字が含まれ、名前を区別する唯一の文字が無効であると、無効な文字はすべてアンダースコアに置き換えられるため、予期せぬ競合が発生する可能性があります。

詳細は以下を参照してください。

5.2.1. Debezium MySQL 変更イベントのキー

変更イベントのキーには、変更されたテーブルのキーのスキーマと、変更された行の実際のキーのスキーマが含まれます。スキーマとそれに対応するペイロードの両方には、コネクターによってイベントが作成された時点において、変更されたテーブルの PRIMARY KEY (または一意な制約) に存在した各列のフィールドが含まれます。

以下の customers テーブルについて考えてみましょう。この後に、このテーブルの変更イベントキーの例を示します。

CREATE TABLE customers (
  id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE KEY
) AUTO_INCREMENT=1001;

customers テーブルへの変更をキャプチャーする変更イベントのすべてに、イベントキースキーマがあります。customers テーブルに前述の定義がある限り、customers テーブルへの変更をキャプチャーする変更イベントのキー構造はすべて以下のようになります。JSON では、以下のようになります。

{
 "schema": { 1
    "type": "struct",
    "name": "mysql-server-1.inventory.customers.Key", 2
    "optional": false, 3
    "fields": [ 4
      {
        "field": "id",
        "type": "int32",
        "optional": false
      }
    ]
  },
 "payload": { 5
    "id": 1001
  }
}

表5.4 変更イベントキーの説明

項目フィールド名説明

1

schema

キーのスキーマ部分は、キーの payload 部分の内容を記述する Kafka Connect スキーマを指定します。

2

mysql-server-1.inventory.customers.Key

キーのペイロードの構造を定義するスキーマの名前。このスキーマは、変更されたテーブルのプライマリーキーの構造を記述します。キースキーマ名の形式は connector-name.database-name.table-name.Key です。この例では、以下のようになります。

  • mysql-server-1 はこのイベントを生成したコネクターの名前です。
  • inventory は変更されたテーブルが含まれるデータベースです。
  • customers は更新されたテーブルです。

3

optional

イベントキーの payload フィールドに値が含まれる必要があるかどうかを示します。この例では、キーのペイロードに値が必要です。テーブルにプライマリーキーがない場合は、キーの payload フィールドの値は任意です。

4

fields

各フィールドの名前、タイプ、および必要かどうかなど、payload で想定される各フィールドを指定します。

5

payload

この変更イベントが生成された行のキーが含まれます。この例では、キーには値が 1001 の 1 つの id フィールドが含まれます。

5.2.2. Debezium MySQL 変更イベントの値

変更イベントの値はキーよりも若干複雑です。キーと同様に、値には schema セクションと payload セクションがあります。schema セクションには、入れ子のフィールドを含む、payload セクションの Envelope 構造を記述するスキーマが含まれています。データを作成、更新、または削除する操作のすべての変更イベントには、Envelope 構造を持つ値 payload があります。

変更イベントキーの例を紹介するために使用した、同じサンプルテーブルについて考えてみましょう。

CREATE TABLE customers (
  id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE KEY
) AUTO_INCREMENT=1001;

このテーブルへの変更に対する変更イベントの値部分には以下について記述されています。

作成イベント

以下の例は、customers テーブルにデータを作成する操作に対して、コネクターによって生成される変更イベントの値の部分を示しています。

{
  "schema": { 1
    "type": "struct",
    "fields": [
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "id"
          },
          {
            "type": "string",
            "optional": false,
            "field": "first_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "last_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "email"
          }
        ],
        "optional": true,
        "name": "mysql-server-1.inventory.customers.Value", 2
        "field": "before"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "id"
          },
          {
            "type": "string",
            "optional": false,
            "field": "first_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "last_name"
          },
          {
            "type": "string",
            "optional": false,
            "field": "email"
          }
        ],
        "optional": true,
        "name": "mysql-server-1.inventory.customers.Value",
        "field": "after"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "string",
            "optional": false,
            "field": "version"
          },
          {
            "type": "string",
            "optional": false,
            "field": "connector"
          },
          {
            "type": "string",
            "optional": false,
            "field": "name"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "ts_ms"
          },
          {
            "type": "boolean",
            "optional": true,
            "default": false,
            "field": "snapshot"
          },
          {
            "type": "string",
            "optional": false,
            "field": "db"
          },
          {
            "type": "string",
            "optional": true,
            "field": "table"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "server_id"
          },
          {
            "type": "string",
            "optional": true,
            "field": "gtid"
          },
          {
            "type": "string",
            "optional": false,
            "field": "file"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "pos"
          },
          {
            "type": "int32",
            "optional": false,
            "field": "row"
          },
          {
            "type": "int64",
            "optional": true,
            "field": "thread"
          },
          {
            "type": "string",
            "optional": true,
            "field": "query"
          }
        ],
        "optional": false,
        "name": "io.debezium.connector.mysql.Source", 3
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "mysql-server-1.inventory.customers.Envelope" 4
  },
  "payload": { 5
    "op": "c", 6
    "ts_ms": 1465491411815, 7
    "before": null, 8
    "after": { 9
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": { 10
      "version": "1.5.4.Final",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 0,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 0,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 154,
      "row": 0,
      "thread": 7,
      "query": "INSERT INTO customers (first_name, last_name, email) VALUES ('Anne', 'Kretchmar', 'annek@noanswer.org')"
    }
  }
}

表5.5 作成 イベント値フィールドの説明

項目フィールド名説明

1

schema

値のペイロードの構造を記述する、値のスキーマ。変更イベントの値スキーマは、コネクターが特定のテーブルに生成するすべての変更イベントで同じになります。

2

name

schema セクションで、各 name フィールドは、値のペイロードのフィールドに対するスキーマを指定します。

mysql-server-1.inventory.customers.Value はペイロードの before および after フィールドのスキーマです。このスキーマは customers テーブルに固有です。

before および after フィールドのスキーマ名は logicalName.tableName.Value の形式で、スキーマ名がデータベースで一意になるようにします。つまり、Avro コンバーター を使用する場合、各論理ソースの各テーブルの Avro スキーマには独自の進化と履歴があります。

3

name

io.debezium.connector.mysql.Source はペイロードの source フィールドのスキーマです。このスキーマは MySQL コネクターに固有です。コネクターは生成するすべてのイベントにこれを使用します。

4

name

mysql-server-1.inventory.customers.Envelope は、ペイロードの全体的な構造のスキーマです。mysql-server-1 はコネクター名、inventory はデータベース、customers はテーブルです。

5

payload

値の実際のデータ。これは、変更イベントが提供する情報です。

イベントの JSON 表現はそれが記述する行よりもはるかに大きいように見えることがあります。これは、JSON 表現にはメッセージのスキーマ部分とペイロード部分を含める必要があるためです。しかし、Avro コンバーター を使用すると、コネクターが Kafka トピックにストリーミングするメッセージのサイズを大幅に小さくすることができます。

6

op

コネクターによってイベントが生成される原因となった操作の型を記述する必須文字列。この例では、c は操作によって行が作成されたことを示しています。有効な値は次のとおりです。

  • c = create (作成)
  • u = update (更新)
  • d = delete (削除)
  • r = read (読み取り、スナップショットのみに適用)

7

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

8

before

イベント発生前の行の状態を指定する任意のフィールド。この例のように、op フィールドが create (作成) の c である場合、この変更イベントは新しい内容に対するものであるため、beforenull になります。

9

after

イベント発生後の行の状態を指定する任意のフィールド。この例では、after フィールドには新しい行の idfirst_namelast_name、および email 列の値が含まれます。

10

source

イベントのソースメタデータを記述する必須のフィールド。このフィールドには、イベントの発生元、イベントの発生順序、およびイベントが同じトランザクションの一部であるかどうかなど、このイベントと他のイベントを比較するために使用できる情報が含まれています。ソースメタデータには以下が含まれています。

  • Debezium バージョン
  • コネクター名
  • イベントが記録された binlog 名
  • binlog の位置
  • イベント内の行
  • イベントがスナップショットの一部であるか
  • 新しい行が含まれるデータベースおよびテーブルの名前
  • イベントを作成した MySQL スレッドの ID (スナップショット以外)
  • MySQL サーバー ID (利用可能な場合)
  • データベースに変更が加えられた時点のタイムスタンプ

binlog_rows_query_log_events MySQL 設定オプションが有効で、コネクター設定 include.query プロパティーが有効な場合、source フィールドは、変更イベントの起因となった元の SQL ステートメントが含まれる query フィールドも提供します。

更新イベント

サンプル customers テーブルにある更新の変更イベントの値には、そのテーブルの 作成 イベントと同じスキーマがあります。同様に、イベント値のペイロードは同じ構造を持ちます。ただし、イベント値ペイロードでは 更新 イベントに異なる値が含まれます。以下は、コネクターによって customers テーブルでの更新に生成されるイベントの変更イベント値の例になります。

{
  "schema": { ... },
  "payload": {
    "before": { 1
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": { 2
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": { 3
      "version": "1.5.4.Final",
      "name": "mysql-server-1",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 1465581029100,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 223344,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 484,
      "row": 0,
      "thread": 7,
      "query": "UPDATE customers SET first_name='Anne Marie' WHERE id=1004"
    },
    "op": "u", 4
    "ts_ms": 1465581029523 5
  }
}

表5.6 更新 イベント値フィールドの説明

項目フィールド名説明

1

before

イベント発生前の行の状態を指定する任意のフィールド。更新 イベント値の before フィールドには、各テーブル列のフィールドと、データベースのコミット前にその列にあった値が含まれます。この例では、first_name の値は Anne. です。

2

after

イベント発生後の行の状態を指定する任意のフィールド。beforeafter の構造を比較すると、この行への更新内容を判断できます。この例では、first_name の値は Anne Marie になりました。

3

source

イベントのソースメタデータを記述する必須のフィールド。source フィールド構造には create イベントと同じフィールドがありますが、一部の値が異なります。たとえば、更新 イベントは binlog の異なる位置から発生します。ソースメタデータには以下が含まれています。

  • Debezium バージョン
  • コネクター名
  • イベントが記録された binlog 名
  • binlog の位置
  • イベント内の行
  • イベントがスナップショットの一部であるか
  • 更新された行が含まれるデータベースおよびテーブルの名前
  • イベントを作成した MySQL スレッドの ID (スナップショット以外)
  • MySQL サーバー ID (利用可能な場合)
  • データベースに変更が加えられた時点のタイムスタンプ

binlog_rows_query_log_events MySQL 設定オプションが有効で、コネクター設定 include.query プロパティーが有効な場合、source フィールドは、変更イベントの起因となった元の SQL ステートメントが含まれる query フィールドも提供します。

4

op

操作の型を記述する必須の文字列。更新 イベントの値では、op フィールドの値は u で、更新によってこの行が変更したことを示します。

5

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

注記

行のプライマリーキー/一意キーの列を更新すると、行のキーの値が変更されます。キーが変更されると、3 つ のイベントが Debezium によって出力されます。3 つのイベントとは、DELETE イベント、行の古いキーを持つ 廃棄 (tombstone)、およびそれに続く行の新しいキーを持つイベントです。詳細は次のセクションで説明します。

プライマリーキーの更新

行のプライマリーキーフィールドを変更する UPDATE 操作は、プライマリーキーの変更と呼ばれます。プライマリーキーの変更では、UPDATE イベントレコードの代わりにコネクターが古いキーの DELETE イベントレコードと、新しい (更新された) キーの CREATE イベントレコードを出力します。これらのイベントには通常の構造と内容があり、イベントごとにプライマリーキーの変更に関連するメッセージヘッダーがあります。

  • DELETE イベントレコードには、メッセージヘッダーとして __debezium.newkey があります。このヘッダーの値は、更新された行の新しいプライマリーキーです。
  • CREATE イベントレコードには、メッセージヘッダーとして __debezium.oldkey があります。このヘッダーの値は、更新された行にあった以前の (古い) プライマリーキーです。

削除 イベント

削除 変更イベントの値は、同じテーブルの 作成 および 更新 イベントと同じ schema の部分になります。サンプル customers テーブルの 削除 イベントの payload 部分は以下のようになります。

{
  "schema": { ... },
  "payload": {
    "before": { 1
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": null, 2
    "source": { 3
      "version": "1.5.4.Final",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 1465581902300,
      "snapshot": false,
      "db": "inventory",
      "table": "customers",
      "server_id": 223344,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 805,
      "row": 0,
      "thread": 7,
      "query": "DELETE FROM customers WHERE id=1004"
    },
    "op": "d", 4
    "ts_ms": 1465581902461 5
  }
}

表5.7 削除 イベント値フィールドの説明

項目フィールド名説明

1

before

イベント発生前の行の状態を指定する任意のフィールド。削除 イベント値の before フィールドには、データベースのコミットで削除される前に行にあった値が含まれます。

2

after

イベント発生後の行の状態を指定する任意のフィールド。削除 イベント値の after フィールドは null で、行が存在しないことを示します。

3

source

イベントのソースメタデータを記述する必須のフィールド。削除 イベント値の source フィールド構造は、同じテーブルの 作成 および 更新 イベントと同じになります。多くの source フィールドの値も同じです。削除 イベント値では、ts_ms および pos フィールドの値や、その他の値が変更された可能性があります。ただし、削除 イベント値の source フィールドは、同じメタデータを提供します。

  • Debezium バージョン
  • コネクター名
  • イベントが記録された binlog 名
  • binlog の位置
  • イベント内の行
  • イベントがスナップショットの一部であるか
  • 更新された行が含まれるデータベースおよびテーブルの名前
  • イベントを作成した MySQL スレッドの ID (スナップショット以外)
  • MySQL サーバー ID (利用可能な場合)
  • データベースに変更が加えられた時点のタイムスタンプ

binlog_rows_query_log_events MySQL 設定オプションが有効で、コネクター設定 include.query プロパティーが有効な場合、source フィールドは、変更イベントの起因となった元の SQL ステートメントが含まれる query フィールドも提供します。

4

op

操作の型を記述する必須の文字列。op フィールドの値は d で、行が削除されたことを示します。

5

ts_ms

コネクターがイベントを処理した時間を表示する任意のフィールド。この時間は、Kafka Connect タスクを実行している JVM のシステムクロックを基にします。

source オブジェクトで、ts_ms は変更がデータベースに加えられた時間を示します。payload.source.ts_ms の値を payload.ts_ms の値と比較することにより、ソースデータベースの更新と Debezium との間の遅延を判断できます。

削除 変更イベントレコードは、この行の削除を処理するために必要な情報を持つコンシューマーを提供します。コンシューマーによっては、削除を適切に処理するために古い値が必要になることがあるため、古い値が含まれます。

MySQL コネクターイベントは、Kafka のログコンパクション と動作するように設計されています。ログコンパクションにより、少なくとも各キーの最新のメッセージが保持される限り、一部の古いメッセージを削除できます。これにより、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できるようにするとともに、Kafka がストレージ領域を確保できるようにします。

廃棄 (tombstone) イベント

行が削除された場合でも、Kafka は同じキーを持つ以前のメッセージをすべて削除できるため、削除 イベントの値はログコンパクションで動作します。ただし、Kafka が同じキーを持つすべてのメッセージを削除するには、メッセージの値が null である必要があります。これを可能にするために、Debezium の MySQL コネクターは 削除 イベントを出力した後に、同じキーと null の値を持つ特別な廃棄 (tombstone) イベントを出力します。

5.3. Debezium MySQL コネクターによるデータ型のマッピング方法

Debezium MySQL コネクターは、行が存在するテーブルのように構造化されたイベントで行への変更を表します。イベントには、各列の値のフィールドが含まれます。その列の MySQL データ型は、イベントの値を表す方法を指定します。

文字列を格納する列は、文字セットと照合順序を使用して MySQL に定義されます。MySQL コネクターは、binlog イベントの列値のバイナリー表現を読み取るときに、列の文字セットを使用します。

コネクターは MySQL データ型を リテラル 型および セマンティック 型の両方にマップできます。

  • リテラル型: Kafka Connect スキーマタイプを使用して値がどのように表されるか。
  • セマンティック型: Kafka Connect スキーマがどのようにフィールド (スキーマ名) の意味をキャプチャーするか。

詳細は以下を参照してください。

基本型

以下の表は、コネクターによる基本的な MySQL データ型のマッピング方法を示しています。

表5.8 基本型のマッピングの説明

MySQL 型リテラル型セマンティック型

BOOLEAN, BOOL

BOOLEAN

該当なし

BIT(1)

BOOLEAN

該当なし

BIT(>1)

BYTES

io.debezium.data.Bits
length schema パラメーターには、ビット数を表す整数が含まれます。byte[] にはビットが リトルエンディアン 形式で含まれ、指定数のビットが含まれるようにサイズが指定されます。たとえば、n がビットの場合は以下のようになります。
numBytes = n/8 + (n%8== 0 ? 0 : 1)

TINYINT

INT16

該当なし

SMALLINT[(M)]

INT16

該当なし

MEDIUMINT[(M)]

INT32

該当なし

INT, INTEGER[(M)]

INT32

該当なし

BIGINT[(M)]

INT64

該当なし

REAL[(M,D)]

FLOAT32

該当なし

FLOAT[(M,D)]

FLOAT64

該当なし

DOUBLE[(M,D)]

FLOAT64

該当なし

CHAR(M)]

STRING

該当なし

VARCHAR(M)]

STRING

該当なし

BINARY(M)]

BYTES または STRING

該当なし
binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

VARBINARY(M)]

BYTES または STRING

該当なし
binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

TINYBLOB

BYTES または STRING

該当なし
binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

TINYTEXT

STRING

該当なし

BLOB

BYTES または STRING

該当なし
binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

TEXT

STRING

該当なし

MEDIUMBLOB

BYTES または STRING

該当なし
binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

MEDIUMTEXT

STRING

該当なし

LONGBLOB

BYTES または STRING

該当なし
binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

LONGTEXT

STRING

該当なし

JSON

STRING

io.debezium.data.Json
JSON ドキュメント、アレイ、またはスケーラーの文字列表現が含まれます。

ENUM

STRING

io.debezium.data.Enum
allowed スキーマパラメーターには、許可される値のコンマ区切りリストが含まれます。

SET

STRING

io.debezium.data.EnumSet
allowed スキーマパラメーターには、許可される値のコンマ区切りリストが含まれます。

YEAR[(2|4)]

INT32

io.debezium.time.Year

TIMESTAMP[(M)]

STRING

io.debezium.time.ZonedTimestamp
マイクロ秒の精度を持つ ISO 8601 形式。MySQL では、M0-6 の範囲にすることができます。

時間型

TIMESTAMP データ型を除き、MySQL の時間型は time.precision.mode コネクター設定プロパティーの値によって異なります。デフォルト値が CURRENT_TIMESTAMP または NOW として指定される TIMESTAMP 列では、Kafka Connect スキーマのデフォルト値として値 1970-01-01 00:00:00 が使用されます。

MySQL では、ゼロの値は null よりも優先されることがあるため、DATEDATETIME、および TIMESTAMP 列にゼロの値を使用できます。MySQL コネクターは、列定義で null 値が許可される場合はゼロの値を null 値として表し、列で null 値が許可されない場合はエポック日として表します。

タイムゾーンのない時間型

DATETIME 型は、「2018-01-13 09:48:27」のようにローカルの日時を表します。タイムゾーンの情報は含まれません。このような列は、UTC を使用して列の精度に基づいてエポックミリ秒またはマイクロ秒に変換されます。TIMESTAMP 型は、タイムゾーン情報のないタイムスタンプを表します。これは、書き込み時に MySQL によってサーバー (またはセッション) の現在のタイムゾーンから UTC に変換され、値を読み戻すときに UTC からサーバー (またはセッション) の現在のタイムゾーンに変換されます。以下に例を示します。

  • 2018-06-20 06:37:03 の値を持つ DATETIME1529476623000 になります。
  • 2018-06-20 06:37:03 の値を持つ TIMESTAMP2018-06-20T13:37:03Z になります。

このような列は、サーバー (またはセッション) の現在のタイムゾーンに基づいて、UTC の同等の io.debezium.time.ZonedTimestamp に変換されます。タイムゾーンは、デフォルトでサーバーからクエリーされます。これに失敗した場合は、データベース serverTimezone MySQL 設定オプションで明示的に指定される必要があります。たとえば、データベースのタイムゾーン (グローバルなタイムゾーンまたは serverTimezone オプションを使用してコネクターのために設定) が「America/Los_Angeles」である場合、値「2018-06-20T13:37:03Z」を持つ ZonedTimestamp によって TIMESTAMP 値の「2018-06-20 06:37:03」が表されます。

Kafka Connect および Debezium を実行している JVM のタイムゾーンは、これらの変換には影響しません。

時間値に関連するプロパティーの詳細は、MySQL コネクター設定プロパティー のドキュメントを参照してください。

time.precision.mode=adaptive_time_microseconds(default)

MySQL コネクターは、イベントがデータベースの値を正確に表すようにするため、列のデータ型定義に基づいてリテラル型とセマンテック型を判断します。すべての時間フィールドはマイクロ秒単位です。正しくキャプチャーされる TIME フィールドの値は、範囲が 00:00:00.000000 から 23:59:59.999999 までの正の値です。

表5.9 time.precision.mode=adaptive_time_microseconds の場合のマッピング

MySQL 型リテラル型セマンティック型

DATE

INT32

io.debezium.time.Date
エポックからの日数を表します。

TIME[(M)]

INT64

io.debezium.time.MicroTime
時間の値をマイクロ秒単位で表し、タイムゾーン情報は含まれません。MySQL では、M0-6 の範囲にすることができます。

DATETIME, DATETIME(0), DATETIME(1), DATETIME(2), DATETIME(3)

INT64

io.debezium.time.Timestamp
エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

DATETIME(4), DATETIME(5), DATETIME(6)

INT64

io.debezium.time.MicroTimestamp
エポックからの経過時間をマイクロ秒で表し、タイムゾーン情報は含まれません。

time.precision.mode=connect

MySQL コネクターは定義された Kafka Connect の論理型を使用します。この方法はデフォルトの方法よりも精度が低く、データベース列に 3 を超える 少数秒の精度値がある場合は、イベントの精度が低くなる可能性があります。00:00:00.000 から 23:59:59.999 までの値のみを処理できます。テーブルの TIME の値が、必ずサポートされる範囲内になるようにすることができる場合のみ、time.precision.mode=connect を設定します。connect 設定は、今後の Debezium バージョンで削除される予定です。

表5.10 time.precision.mode=connect の場合のマッピング

MySQL 型リテラル型セマンティック型

DATE

INT32

org.apache.kafka.connect.data.Date
エポックからの日数を表します。

TIME[(M)]

INT64

org.apache.kafka.connect.data.Time
午前 0 時以降の時間値をマイクロ秒で表し、タイムゾーン情報は含まれません。

DATETIME[(M)]

INT64

org.apache.kafka.connect.data.Timestamp
エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

10 進数型

Debezium コネクターは、decimal.handling.mode コネクター設定プロパティー の設定にしたがって 10 進数を処理します。

decimal.handling.mode=precise

表5.11 decimal.handing.mode=precise の場合のマッピング

MySQL 型リテラル型セマンティック型

NUMERIC[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal
scale スキーマパラメーターには、小数点を移動した桁数を表す整数が含まれます。

DECIMAL[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal
scale スキーマパラメーターには、小数点を移動した桁数を表す整数が含まれます。

decimal.handling.mode=double

表5.12 decimal.handing.mode=double の場合のマッピング

MySQL 型リテラル型セマンティック型

NUMERIC[(M[,D])]

FLOAT64

該当なし

DECIMAL[(M[,D])]

FLOAT64

該当なし

decimal.handling.mode=string

表5.13 decimal.handing.mode=string の場合のマッピング

MySQL 型リテラル型セマンティック型

NUMERIC[(M[,D])]

STRING

該当なし

DECIMAL[(M[,D])]

STRING

該当なし

ブール値

MySQL は、特定の方法で BOOLEAN の値を内部で処理します。BOOLEAN 列は、内部で TINYINT(1) データ型にマッピングされます。ストリーミング中にテーブルが作成されると、Debezium は元の DDL を受信するため、適切な BOOLEAN マッピングが使用されます。スナップショット中、Debezium は SHOW CREATE TABLE を実行して、BOOLEANTINYINT(1) の両コラムに TINYINT(1) を返すテーブル定義を取得します。その後、Debezium は元の型のマッピングを取得する方法はないため、TINYINT(1) にマッピングします。

以下は ConfigMap の例になります。

converters=boolean
boolean.type=io.debezium.connector.mysql.converters.TinyIntOneToBooleanConverter
boolean.selector=db1.table1.*, db1.table2.column1

空間型

現在、Debezium MySQL コネクターは以下の空間データ型をサポートしています。

表5.14 空間型マッピングの説明

MySQL 型リテラル型セマンティック型

GEOMETRY,
LINESTRING,
POLYGON,
MULTIPOINT,
MULTILINESTRING,
MULTIPOLYGON,
GEOMETRYCOLLECTION

STRUCT

io.debezium.data.geometry.Geometry
次の 2 つのフィールドを持つ構造が含まれます。

  • srid (INT32: 構造に保存されたジオメトリーオブジェクトの型を定義する、空間参照システム ID。
  • wkb (BYTES): wkb (Well-Known-Binary) 形式でエンコードされたジオメトリーオブジェクトのバイナリー表現。詳細は、「Open Geospatial Consortium」を参照してください。

5.4. Debezium コネクターを実行するための MySQL の設定

Debezium をインストールおよび実行する前に、一部の MySQL 設定タスクが必要になります。

詳細は以下を参照してください。

5.4.1. Debezium コネクターの MySQL ユーザーの作成

Debezium MySQL コネクターには MySQL ユーザーアカウントが必要です。この MySQL ユーザーは、Debezium MySQL コネクターが変更をキャプチャーするすべてのデータベースに対して適切なパーミッションを持っている必要があります。

前提条件

  • MySQL サーバー。
  • SQL コマンドの基本知識。

手順

  1. MySQL ユーザーを作成します。

    mysql> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
  2. 必要なパーミッションをユーザーに付与します。

    mysql> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';

    以下の表はパーミッションについて説明しています。

    重要

    グローバル読み取りロックを許可しない Amazon RDS や Amazon Aurora などのホストオプションを使用している場合、テーブルレベルのロックを使用して 整合性スナップショット を作成します。この場合、作成するユーザーに LOCK TABLES パーミッションも付与する必要があります。詳細は、「スナップショット」を参照してください。

  3. ユーザーのパーミッションの最終処理を行います。

    mysql> FLUSH PRIVILEGES;

表5.15 ユーザーパーミッションの説明

キーワード説明

SELECT

コネクターがデータベースのテーブルから行を選択できるようにします。これは、スナップショットを実行する場合にのみ使用されます。

RELOAD

内部キャッシュのクリアまたはリロード、テーブルのフラッシュ、またはロックの取得を行う FLUSH ステートメントをコネクターが使用できるようにします。これは、スナップショットを実行する場合にのみ使用されます。

SHOW DATABASES

SHOW DATABASE ステートメントを実行して、コネクターがデータベース名を確認できるようにします。これは、スナップショットを実行する場合にのみ使用されます。

REPLICATION SLAVE

コネクターが MySQL サーバーの binlog に接続し、読み取りできるようにします。

REPLICATION CLIENT

コネクターが以下のステートメントを使用できるようにします。

  • SHOW MASTER STATUS
  • SHOW SLAVE STATUS
  • SHOW BINARY LOGS

これは必ずコネクターに必要です。

ON

パーミッションが適用されるデータベースを指定します。

TO 'user'

パーミッションを付与するユーザーを指定します。

IDENTIFIED BY 'password'

ユーザーの MySQL パスワードを指定します。

5.4.2. Debezium の MySQL binlog の有効化

MySQL レプリケーションのバイナリーロギングを有効にする必要があります。バイナリーログは、変更を伝播するためにレプリケーションツールのトランザクション更新を記録します。

前提条件

  • MySQL サーバー。
  • 適切な MySQL ユーザーの権限。

手順

  1. log-bin オプションがすでにオンになっているかどうかを確認します。

    mysql> SELECT variable_value as "BINARY LOGGING STATUS (log-bin) ::"
    FROM information_schema.global_variables WHERE variable_name='log_bin';
  2. OFF の場合は、以下に説明するプロパティーで MySQL サーバー設定ファイルを設定します。

    server-id         = 223344
    log_bin           = mysql-bin
    binlog_format     = ROW
    binlog_row_image  = FULL
    expire_logs_days  = 10
  3. 再度 binlog の状態をチェックして、変更を確認します。

    mysql> SELECT variable_value as "BINARY LOGGING STATUS (log-bin) ::"
    FROM information_schema.global_variables WHERE variable_name='log_bin';

表5.16 MySQL binlog 設定プロパティーの説明

プロパティー説明

server-id

server-id の値は、MySQL クラスターの各サーバーおよびレプリケーションクライアントに対して一意である必要があります。MySQL コネクターの設定中に、Debezium によって一意のサーバー ID がコネクターに割り当てられます。

log_bin

log_bin の値は、binlog ファイルのシーケンスのベース名です。

binlog_format

binlog-formatROW または row に設定される必要があります。

binlog_row_image

binlog_row_imageFULL または full に設定される必要があります。

expire_logs_days

これは、binlog ファイルが自動的に削除される日数です。デフォルトは 0 で、自動的に削除されません。実際の環境に見合った値を設定します。「MySQL による binlog ファイルのパージ」を参照してください。

5.4.3. Debezium の MySQL グローバルトランザクション識別子の有効化

グローバルトランザクション識別子 (GTID) は、クラスター内のサーバーで発生するトランザクションを一意に識別します。Debezium MySQL コネクターには必要ありませんが、GTID を使用すると、レプリケーションを単純化し、プライマリーサーバーとレプリカサーバーの一貫性が保たれるかどうかを簡単に確認することができます。

GTID は MySQL 5.6.5 以降で利用できます。詳細は MySQL のドキュメント を参照してください。

前提条件

  • MySQL サーバー。
  • SQL コマンドの基本知識。
  • MySQL 設定ファイルへのアクセス。

手順

  1. gtid_mode を有効にします。

    mysql> gtid_mode=ON
  2. enforce_gtid_consistency を有効にします。

    mysql> enforce_gtid_consistency=ON
  3. 変更を確認します。

    mysql> show global variables like '%GTID%';

結果

+--------------------------+-------+
| Variable_name            | Value |
+--------------------------+-------+
| enforce_gtid_consistency | ON    |
| gtid_mode                | ON    |
+--------------------------+-------+

表5.17 GTID オプションの説明

オプション説明

gtid_mode

MySQL サーバーの GTID モードが有効かどうかを指定するブール値。

  • ON = 有効
  • OFF = 無効

enforce_gtid_consistency

トランザクションに安全な方法でログに記録できるステートメントの実行を許可することにより、サーバーが GTID の整合性を強制するかどうかを指定するブール値。GTID を使用する場合に必須です。

  • ON = 有効
  • OFF = 無効

5.4.4. Debezium の MySQL セッションタイムアウトの設定

大規模なデータベースに対して最初の整合性スナップショットが作成されると、テーブルの読み込み時に、確立された接続がタイムアウトする可能性があります。MySQL 設定ファイルで interactive_timeout および wait_timeout を設定すると、この動作の発生を防ぐことができます。

前提条件

  • MySQL サーバー。
  • SQL コマンドの基本知識。
  • MySQL 設定ファイルへのアクセス。

手順

  1. interactive_timeout を設定します。

    mysql> interactive_timeout=<duration-in-seconds>
  2. wait_timeout を設定します。

    mysql> wait_timeout=<duration-in-seconds>

表5.18 MySQL セッションタイムアウトオプションの説明

オプション説明

interactive_timeout

サーバーが対話的な接続を閉じる前にアクティビティーの発生を待つ時間 (秒単位)。詳細は MySQL のドキュメント を参照してください。

wait_timeout

サーバーが非対話的な接続を閉じる前にアクティビティーの発生を待つ時間 (秒単位)。詳細は MySQL のドキュメント を参照してください。

5.4.5. Debezium MySQL コネクターのクエリーログイベントの有効化

各 binlog イベントの元の SQL ステートメントを確認したい場合があります。MySQL 設定ファイルで binlog_rows_query_log_events オプションを有効にすると、これを行うことができます。

このオプションは、MySQL 5.6 以降で利用できます。

前提条件

  • MySQL サーバー。
  • SQL コマンドの基本知識。
  • MySQL 設定ファイルへのアクセス。

手順

  • binlog_rows_query_log_events を有効にします。

    mysql> binlog_rows_query_log_events=ON

    binlog_rows_query_log_events は、binlog エントリーに SQL ステートメントが含まれるようにするためのサポートを有効または無効にする値に設定されます。

    • ON = 有効
    • OFF = 無効

5.5. Debezium MySQL コネクターのデプロイ

Debezium MySQL コネクターをデプロイするには、コネクターファイルを Kafka Connect に追加し、コネクターを実行するカスタムコンテナーを作成して、続いてコネクター設定をコンテナーに追加します。Debezium MySQL コネクターのデプロイに関する詳細は、以下を参照してください。

5.5.1. Debezium MySQL コネクターのデプロイ

Debezium MySQL コネクターをデプロイするには、Debezium コネクターアーカイブが含まれるカスタム Kafka Connect コンテナーイメージをビルドし、続いてこのコンテナーイメージをコンテナーレジストリーにプッシュする必要があります。その後、以下のカスタムリソース (CR) を作成する必要があります。

  • Kafka Connect インスタンスを定義する KafkaConnect CR。CR の image プロパティーは、Debezium コネクターを実行するために作成するコンテナーイメージの名前を指定します。この CR を、Red Hat AMQ Streams がデプロイされている OpenShift インスタンスに適用します。AMQ Streams は、Apache Kafka を OpenShift に取り入れる Operator およびイメージを提供します。
  • Debezium MySQL コネクターを定義する KafkaConnector CR。この CR を KafkaConnect CR を適用するのと同じ OpenShift インスタンスに適用します。

前提条件

  • MySQL が稼働状態にあり、Debezium コネクターと連携するように MySQL を設定する 手順を完了している必要があります。
  • AMQ Streams が OpenShift にデプロイされ、Apache Kafka および Kafka Connect を実行している。詳細は、『Deploying and Upgrading AMQ Streams on OpenShift』を参照してください。
  • Podman または Docker がインストールされている。
  • Debezium コネクターを実行するコンテナーを追加する予定のコンテナーレジストリー (quay.iodocker.io など) でコンテナーを作成および管理するアカウントとパーミッションを持っている。

手順

  1. Kafka Connect の Debezium MySQL コンテナーを作成します。

    1. Debezium MySQL コネクターアーカイブ をダウンロードします。
    2. Debezium MySQL コネクターアーカイブを展開して、コネクタープラグインのディレクトリー構造を作成します。以下に例を示します。

      ./my-plugins/
      ├── debezium-connector-mysql
      │   ├── ...
    3. registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0 をベースイメージとして使用する Docker ファイルを作成します。たとえば、ターミナルウィンドウに以下を入力し、my-plugins をプラグインディレクトリーの名前に置き換えます。

      cat <<EOF >debezium-container-for-mysql.yaml 1
      FROM registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0
      USER root:root
      COPY ./<my-plugins>/ /opt/kafka/plugins/ 2
      USER 1001
      EOF
      1 1 1 1 1 1
      任意のファイル名を指定できます。
      2 2 2 2 2 2
      my-plugins をプラグインディレクトリーの名前に置き換えます。

      このコマンドは、現在のディレクトリーに debezium-container-for-mysql.yaml という名前の Docker ファイルを作成します。

    4. 前のステップで作成した debezium-container-for-mysql.yaml Docker ファイルからコンテナーイメージをビルドします。ファイルを含むディレクトリーから、ターミナルウィンドウを開き、以下のコマンドのいずれかを入力します。

      podman build -t debezium-container-for-mysql:latest .
      docker build -t debezium-container-for-mysql:latest .

      上記のコマンドは、debezium-container-for-mysql という名前のコンテナーイメージをビルドします。

    5. カスタムイメージを quay.io などのコンテナーレジストリーまたは内部のコンテナーレジストリーにプッシュします。コンテナーレジストリーは、イメージをデプロイする OpenShift インスタンスで利用できる必要があります。以下のいずれかのコマンドを実行します。

      podman push <myregistry.io>/debezium-container-for-mysql:latest
      docker push <myregistry.io>/debezium-container-for-mysql:latest
    6. 新しい Debezium MySQL KafkaConnect カスタムリソース (CR) を作成します。たとえば、以下の例のように、annotations および image プロパティーを指定する dbz-connect.yaml という名前の KafkaConnect CR を作成します。

      apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnect
      metadata:
        name: my-connect-cluster
        annotations:
          strimzi.io/use-connector-resources: "true" 1
      spec:
        #...
        image: debezium-container-for-mysql  2
      1
      KafkaConnector リソースはこの Kafka Connect クラスターでコネクターを設定するために使用されることを、metadata.annotations は Cluster Operator に示します。
      2
      spec.image は Debezium コネクターを実行するために作成したイメージの名前を指定します。このプロパティーによって Cluster Operator の STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 変数がオーバーライドされます。
    7. 以下のコマンドを入力して、KafkaConnect CR を OpenShift Kafka Connect 環境に適用します。

      oc create -f dbz-connect.yaml

      このコマンドは、Debezium コネクターを実行するために作成したイメージの名前を指定する Kafka Connect インスタンスを追加します。

  2. Debezium MySQL コネクターインスタンスを設定する KafkaConnector カスタムリソースを作成します。

    コネクターの設定プロパティーを指定する .yaml ファイルで Debezium MySQL コネクターを設定します。コネクター設定は、Debezium に対して、スキーマおよびテーブルのサブセットにイベントを生成するよう指示する可能性があり、または機密性の高い、大きすぎる、または不必要な指定のコラムで Debezium が値を無視、マスク、または切り捨てするようにプロパティーを設定する可能性もあります。

    以下の例は、ポート 3306 で MySQL ホスト 192.168.99.100 に接続し、inventory データベースへの変更をキャプチャーする Debezium コネクターを設定します。dbserver1 はサーバーの論理名です。

    MySQL inventory-connector.yaml

      apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnector
      metadata:
        name: inventory-connector  1
        labels:
          strimzi.io/cluster: my-connect-cluster
      spec:
        class: io.debezium.connector.mysql.MySqlConnector
        tasksMax: 1  2
        config:  3
          database.hostname: mysql  4
          database.port: 3306
          database.user: debezium
          database.password: dbz
          database.server.id: 184054  5
          database.server.name: dbserver1 6
          database.include.list: inventory  7
          database.history.kafka.bootstrap.servers: my-cluster-kafka-bootstrap:9092  8
          database.history.kafka.topic: schema-changes.inventory  9

    表5.19 コネクター設定の説明

    項目説明

    1

    コネクターの名前。

    2

    1 度に 1 つのタスクのみが動作する必要があります。MySQL コネクターは MySQL サーバーの binlog を読み取るため、単一のコネクタータスクを使用することで、順序とイベントの処理が適切に行われるようになります。Kafka Connect サービスはコネクターを使用して作業を行う 1 つ以上のタスクを開始し、実行中のタスクを自動的に Kafka Connect サービスのクラスター全体に分散します。いずれかのサービスが停止またはクラッシュすると、これらのタスクは稼働中のサービスに再分散されます。

    3

    コネクターの設定。

    4

    データベースホスト。MySQL サーバーを実行しているコンテナーの名前です (mysql)。

    5

    コネクターの一意の ID。

    6

    MySQL サーバーまたはクラスターの論理名。この名前は、変更イベントレコードを受信するすべての Kafka トピックのプレフィックスとして使用されます。

    7

    inventory データベースの変更のみがキャプチャーされます。

    8

    DDL ステートメントをデータベース履歴トピックに書き込み、復元するためにコネクターによって使用される Kafka ブローカーのリスト。再起動時に、コネクターが読み取りを開始すべき時点で binlog に存在したデータベースのスキーマを復元します。

    9

    データベース履歴トピックの名前。このトピックは内部使用のみを目的としており、コンシューマーが使用しないようにしてください。

  3. Kafka Connect でコネクターインスタンスを作成します。たとえば、KafkaConnector リソースを inventory-connector.yaml ファイルに保存した場合は、以下のコマンドを実行します。

    oc apply -f inventory-connector.yaml

    上記のコマンドにより inventory-connector が登録され、コネクターは KafkaConnector CR で定義された inventory データベースに対して実行を開始します。

  4. コネクターが作成され、起動されたことを確認します。

    1. Kafka Connect ログ出力を表示して、コネクターが作成され、指定データベースの変更のキャプチャーが開始されたことを確認します。

      oc logs $(oc get pods -o name -l strimzi.io/cluster=my-connect-cluster)
    2. ログの出力を確認し、Debezium が初回のスナップショットを実行することを確認します。ログには、以下のメッセージと同様の出力が表示されます。

      ... INFO Starting snapshot for ...
      ... INFO Snapshot is using user 'debezium' ...

      コネクターがエラーがなく正常に起動すると、コネクターが変更をキャプチャーする各テーブルのトピックが作成されます。CR のサンプルでは、include.list プロパティーに指定されたテーブルのトピックがあります。ダウンストリームアプリケーションは、これらのトピックをサブスクライブできます。

    3. 以下のコマンドを実行して、コネクターによってトピックが作成されたことを検証します。

      oc get kafkatopics

Debezium MySQL コネクターに設定できる設定プロパティーの完全リストは、「MySQL コネクター設定プロパティー」を参照してください。

結果

コネクターが起動すると、コネクターが設定された MySQL データベースの 整合性スナップショットが実行 されます。その後、コネクターは行レベルの操作のデータ変更イベントの生成を開始し、変更イベントレコードを Kafka トピックにストリーミングします。

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

Debezium MySQL コネクターには、アプリケーションに適したコネクター動作を実現するために使用できる設定プロパティーが多数あります。多くのプロパティーにはデフォルト値があります。プロパティーに関する情報は、以下のように構成されています。

以下の設定プロパティーは、デフォルト値がない場合は必須です。

表5.20 必要な Debezium MySQL コネクター設定プロパティー

プロパティーデフォルト説明

name

 

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

connector.class

 

コネクターの Java クラスの名前。MySQL コネクターには常に io.debezium.connector.mysql.MySqlConnector を指定します。

tasks.max

1

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

database.hostname

 

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

database.port

3306

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

database.user

 

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

database.password

 

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

database.server.name

 

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

database.server.id

random

このデータベースクライアントの数値 ID。MySQL クラスターで現在稼働しているすべてのデータベースプロセスで一意である必要があります。このコネクターは、MySQL データベースクラスターを (この一意の ID を持つ) 別のサーバーとして結合するため、binlog を読み取ることができます。デフォルトでは、5400 から 6400 までの乱数が生成されますが、値を明示的に設定することが推奨されます。

database.include.list

空の文字列

変更をキャプチャーするデータベースの名前と一致する正規表現のコンマ区切りリスト (任意)。コネクターは、名前が database.include.list にないデータベースの変更をキャプチャーしません。デフォルトでは、コネクターはすべてのデータベースの変更をキャプチャーします。また、database.exclude.list コネクター設定プロパティーは設定しないでください。

database.exclude.list

空の文字列

変更をキャプチャーしないデータベースの名前と一致する正規表現のコンマ区切りリスト (任意)。コネクターは、名前が database.exclude.list にないデータベースの変更をキャプチャーします。また、database.include.list コネクター設定プロパティーは設定しないでください。

table.include.list

空の文字列

変更をキャプチャーするテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト (任意)。コネクターは table.include.list に含まれていないテーブルの変更をキャプチャーしません。各識別子の形式は databaseName.tableName です。デフォルトでは、コネクターは変更がキャプチャーされる各データベースのシステムでないすべてのテーブルの変更をキャプチャーします。また、table.exclude.list コネクター設定プロパティーは指定しないでください。

table.exclude.list

空の文字列

変更をキャプチャーしないテーブルの完全修飾テーブル識別子と一致する正規表現のコンマ区切りリスト (任意)。コネクターは table.exclude.list に含まれていないテーブルの変更をキャプチャーします。各識別子の形式は databaseName.tableName です。また、table.include.list コネクター設定プロパティーは指定しないでください。

column.exclude.list

空の文字列

変更イベントレコード値から除外する列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は databaseName.tableName.columnName です。

column.include.list

空の文字列

変更イベントレコード値に含める列の完全修飾名と一致する正規表現のコンマ区切りリスト (任意)。列の完全修飾名の形式は databaseName.tableName.columnName です。

column.truncate.to._length_.chars

該当なし

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

column.mask.with._length_.chars

該当なし

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

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

該当なし

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

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

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

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

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

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

column.propagate.source.type

該当なし

出力された変更イベントレコードの該当するフィールドスキーマに元の型および長さをパラメーターとして追加する必要がある列の完全修飾名と一致する、正規表現のコンマ区切りリスト (任意)。以下のスキーマパラメーターは、それぞれ可変幅型の元の型名および長さを伝達するために使用されます。

__Debezium.source.column.type

__Debezium.source.column.length

__Debezium.source.column.scale

これらは、それぞれ可変幅型の元の型名と長さを伝達するために使用されます。これは、シンクデータベースの対応する列を適切にサイズ調整するのに便利です。列の完全修飾名の形式は以下のいずれかになります。

databaseName.tableName.columnName

databaseName.schemaName.tableName.columnName

datatype.propagate.source.type

該当なし

出力された変更イベントレコードの該当するフィールドスキーマに元の型および長さをパラメーターとして追加する必要がある列のデータベース固有のデータ型名と一致する、正規表現のコンマ区切りリスト (任意)。以下のスキーマパラメーターは、それぞれ可変幅型の元の型名および長さを伝搬するために使用されます。

__debezium.source.column.type

__debezium.source.column.length

__debezium.source.column.scale

これらは、それぞれ可変幅型の元の型名と長さを伝達するために使用されます。これは、シンクデータベースの対応する列を適切にサイズ調整するのに便利です。完全修飾データ型名の形式は以下のいずれかになります。

databaseName.tableName.typeName

databaseName.schemaName.tableName.typeName

MySQL 固有のデータ型名のリストは「MySQL コネクターによるデータ型のマッピング方法」を参照してください。

time.precision.mode

adaptive_time_microseconds

時間、日付、およびタイムスタンプは、異なる精度の種類で表すことができます。

adaptive_time_microseconds (デフォルト)は、データベース列の型を基にして、ミリ秒、マイクロ秒、または nanosecond の精度値のいずれかを使用して、データベース列の組み込み表現を使用して、日付、日時、およびタイムスタンプ値をキャプチャーして、常に時間とタイムスタンプ値をキャプチャーできます。


connect データベース列の精度に関係なく、ミリ秒の精度を使用する日付およびタイムスタンプ。

decimal.handling.mode

precise

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

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

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

string は、値をフォーマットされた文字列としてエンコードしますが、実際に型のセマンティック情報は失われます。

bigint.unsigned.handling.mode

long

変更イベントで BIGINT UNSIGNED 列を表す方法を指定します。可能な設定:

long は Java の long を使用して値を表します。これは、精度を提供しない可能性がありますが、コンシューマーでの使用が簡単です。long 通常、推奨される設定です。

precisejava.math.BigDecimal を使用して値を表し、バイナリー表現と Kafka Connect の org.apache.kafka.connect.data.Decimal タイプを使用して変更イベントでエンコードされます。2^63 を超える値は long を使用して提供できないため、このような値を使用する場合はこの設定を使用します。

include.schema.changes

true

コネクターがデータベーススキーマの変更を、データベースサーバー ID と同じ名前の Kafka トピックに公開するかどうかを指定するブール値。各スキーマの変更はデータベース名が含まれるキーを使用して記録され、その値には DDL ステートメントが含まれます。これは、コネクターがデータベース履歴を内部で記録する方法には依存しません。

include.query

false

変更イベントを生成した元の SQL クエリーがコネクターに含まれる必要があるかどうかを指定するブール値。

このオプションを true に設定した場合は、binlog_rows_query_log_events オプションを ON に設定して MySQL を設定することもできます。include.querytrue の場合、スナップショットプロセスが生成するイベントに対するクエリーは存在しません。

include.querytrue に設定すると、変更イベントに元の SQL ステートメントを含めることで明示的に除外またはマスクされたテーブルまたはフィールドが公開される可能性があります。そのため、デフォルト設定は false です。

event.deserialization.failure.handling.mode

fail

binlog イベントのデシリアライズ中にコネクターがどのように例外に反応するかを指定します。

fail は例外を伝播し、問題のあるイベントとその binlog オフセットを示し、コネクターを停止させます。

warn は問題のあるイベントとその binlog オフセットをログに記録し、イベントをスキップします。

ignore は問題のあるイベントを渡し、何もログに記録しません。

inconsistent.schema.handling.mode

fail

内部スキーマ表現に存在しないテーブルに関連する binlog イベントに対してコネクターがどのように反応する必要があるかを指定します。つまり、内部表現はデータベースと一貫性がありません。

fail は問題のあるイベントとその binlog オフセットを示す例外をスローし、コネクターを停止させます。

warn は問題のあるイベントとその binlog オフセットをログに記録し、イベントをスキップします。

skip は問題のあるイベントを渡し、何もログに記録しません。

max.queue.size

8192

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

max.batch.size

2048

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

max.queue.size.in.bytes

0

ブロッキングキューの最大サイズ (バイト単位) の long 値。この機能はデフォルトで無効になっています。正の long 値が設定されると有効になります。

poll.interval.ms

1000

コネクターがイベントのバッチの処理を開始する前に、新しい変更イベントの発生を待つ期間をミリ秒単位で指定する正の整数値。デフォルトは 1000 ミリ秒 (1 秒) です。

connect.timeout.ms

30000

コネクターが MySQL データベースサーバーへの接続を試行した後、タイムアウトするまでの最大の待機期間をミリ秒単位で指定する正の整数値。デフォルトは 30 秒です。

gtid.source.includes

 

MySQL サーバーで binlog の位置を見つけるために使用される GTID セットのソース UUID に一致する、正規表現のコンマ区切りリスト。これらの include パターンのいずれかに一致するソースを持つ GTID の範囲のみが使用されます。gtid.source.excludes の設定は指定しないでください。

gtid.source.excludes

 

MySQL サーバーで binlog の位置を見つけるために使用される GTID セットのソース UUID に一致する、正規表現のコンマ区切りリスト。これらすべての exclude パターンに一致しないソースを持つ GTID の範囲のみが使用されます。gtid.source.includes の値は指定しないでください。

tombstones.on.delete

true

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

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

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

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

message.key.columns

該当なし

テーブルの列名と一致する正規表現が含まれるテーブルのセミコロン区切りのリスト。コネクターは、一致する列の値を Kafka トピックに送信する変更イベントレコードのキーフィールドにマップします。これは、テーブルにプライマリーキーがない場合や、プライマリーキーではないフィールドに応じて Kafka トピックで変更イベントレコードを順序付ける場合に便利です。

セミコロンでエントリーを区切ります。完全修飾テーブル名とその正規表現の間にコロンを挿入します。形式(明確にするためにスペースを表示)は以下のとおりです。

database-name . table-name : regexp ; …​

例:

dbA.table_a:regex_1;dbB.table_b:regex_2;dbC.table_c:regex_3

table_aid 列があり、regex_1^i で始まる列と一致( iで始まるすべての列と一致))、コネクターはコネクターが Kafka に送信する変更イベントのキーフィールドにマップします。id table_a

binary.handling.mode

bytes

バイナリー列 (例: blobbinaryvarbinary) を変更イベントでどのように表すかを指定します。可能な設定:

bytes はバイナリーデータをバイト配列として表します。

base64 はバイナリーデータを base64 でエンコードされた文字列として表します。

hex はバイナリーデータを 16 進エンコード(base16)文字列として表します。

高度な MySQL コネクター設定プロパティー

以下の表は、高度な MySQL コネクタープロパティー について説明しています。これらのプロパティーのデフォルト値を変更する必要はほとんどありません。そのため、コネクター設定にデフォルト値を指定する必要はありません。

表5.21 MySQL コネクターの高度な設定プロパティーの説明

プロパティーデフォルト説明

connect.keep.alive

true

MySQL サーバー/クラスターへの接続を確実に維持するために、別のスレッドを使用するかどうかを指定するブール値。

table.ignore.builtin

true

組み込みシステムテーブルを無視するかどうかを指定するブール値。これは、テーブルの include および exclude リストに関係なく適用されます。デフォルトでは、システムテーブルは変更がキャプチャーされないように除外され、システムテーブルに変更が加えられてもイベントは生成されません。

database.ssl.mode

disabled

暗号化された接続を使用するかどうかを指定します。可能な設定:

disabled は暗号化されていない接続の使用を指定します。

preferred は、サーバーがセキュアな接続に対応している場合は、暗号化された接続を確立します。サーバーがセキュアな接続に対応していない場合は、暗号化されていない接続にフォールバックします。

required は暗号化された接続を確立し、何らかの理由で暗号化された接続を確立します。

verify_carequired のように動作しますが、設定された認証局(CA)証明書に対してサーバー TLS 証明書を検証し、サーバーの TLS 証明書が有効な CA 証明書と一致しない場合は失敗します。

verify_identityverify_ca と同様に動作しますが、追加のサーバー証明書がリモート接続のホストと一致することを検証します。

snapshot.mode

initial

コネクターの起動時にスナップショットを実行するための基準を指定します。可能な設定:

initial - コネクターは、論理サーバー名に対してオフセットが記録されていない場合にのみスナップショットを実行します。

when_needed - コネクターは必要に応じてスナップショットを実行します。つまり、オフセットがない場合や、以前に記録されたオフセットが、サーバーで利用できない binlog の場所または GTID を指定する場合などです。

never - コネクターはスナップショットを使用しません。論理サーバー名での初回起動時に、コネクターは binlog の最初から読み取りします。この動作は注意して設定してください。これは、binlog にデータベースの全履歴が含まれることが保証されている場合のみ有効です。

schema_only: コネクターはデータではなく、スキーマのスナップショットを実行します。この設定は、トピックにデータの整合性スナップショットが含まれる必要がなく、コネクターの開始以降の変更のみが含まれる必要がある場合に便利です。

schema_only_recovery: これは、すでに変更をキャプチャーするコネクターのリカバリー設定です。この設定により、コネクターを再起動すると、破損または損失したデータベース履歴トピックのリカバリーが可能になります。これを定期的に設定して、予想外に増加しているデータベース履歴トピックを「クリーンアップ」することができます。データベース履歴トピックは無期限に保持する必要があります。

snapshot.locking.mode

minimal

コネクターがグローバル MySQL 読み込みロックを保持するかどうか、およびその期間を制御します。これにより、コネクターによるスナップショットの実行中にデータベースが更新されないようにします。可能な設定:

minimal - コネクターはスナップショットの最初の部分のみグローバル読み取りロックを保持します。その間、コネクターはデータベーススキーマとその他のメタデータを読み取ります。スナップショットの残りの作業では、各テーブルから全行を選択する必要があります。REPEATABLE READ トランザクションを使用すると、コネクターは一貫した方法でこれを行うことができます。これは、グローバル読み取りロックが保持されなくなり、その他の MySQL クライアントがデータベースを更新している場合でも該当します。

minimal_percona - コネクターは、スナップショットの最初の部分のみのグローバルバックアップロックを保持します。その間、コネクターはデータベーススキーマおよびその他のメタデータを読み取ります。スナップショットの残りの作業では、各テーブルから全行を選択する必要があります。REPEATABLE READ トランザクションを使用すると、コネクターは一貫した方法でこれを行うことができます。これは、グローバルバックアップロックが保持されなくなり、その他の MySQL クライアントがデータベースを更新している場合でも該当します。このモードはテーブルをディスクにフラッシュせず、長時間実行される読み取りによってブロックされず、Percona Server でのみ利用できます。

extended: スナップショットの実行中にすべての書き込みをブロックします。MySQL が REPEATABLE READ セマンティックから除外する操作を送信するクライアントがある場合は、この設定を使用します。

none: スナップショットの実行中にコネクターがテーブルロックを取得できないようにします。この設定はすべてのスナップショットモードで許可されますが、スナップショットの実行中にスキーマの変更がない場合に 限り、安全に使用できます。MyISAM エンジンで定義されたテーブルの場合、MyISAM によってテーブルロックが取得されるようにこのプロパティーが設定されていても、テーブルはロックされます。この動作は、行レベルのロックを取得する InnoDB エンジンの動作とは異なります。

snapshot.include.collection.list

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

スナップショットを作成したい table.include.list に指定されたスキーマの名前と一致する正規表現のコンマ区切りリスト (任意)。

snapshot.select.statement.overrides

 

スナップショットに含まれるテーブル行を制御します。このプロパティーはスナップショットにのみ影響します。binlog からキャプチャーされたイベントには影響しません。databaseName.tableName の形式で完全修飾テーブル名のコンマ区切りリストを指定します。

指定するテーブルごとに、別の設定プロパティー snapshot.select.statement.overrides.DB_NAME.TABLE_NAME も指定します。たとえば、他の設定プロパティーの名前は snapshot.select.statement.overrides.customers.orders のようになります。このプロパティーを、スナップショットに必要な行のみを取得する SELECT ステートメントに設定します。コネクターがスナップショットを実行すると、この SELECT ステートメントを実行して、そのテーブルからデータを取得します。

これらのプロパティーの設定に使用可能なユースケースは、大規模な追加専用のテーブルです。スナップショットを開始する場所や、以前のスナップショットが中断された場合にスナップショットを再開する場所を設定する SELECT ステートメントを指定できます。

min.row.count.to.stream.results

1000

スナップショットの実行中、コネクターは変更をキャプチャーするように設定されている各テーブルにクエリーを実行します。コネクターは各クエリーの結果を使用して、そのテーブルのすべての行のデータが含まれる読み取りイベントを生成します。このプロパティーは、MySQL コネクターがテーブルの結果をメモリーに格納するか、またはストリーミングを行うかを決定します。メモリーへの格納はすばやく処理できますが、大量のメモリーを必要とします。ストリーミングを行うと、処理は遅くなりますが、非常に大きなテーブルにも対応できます。このプロパティーの設定は、コネクターが結果のストリーミングを行う前にテーブルに含まれる必要がある行の最小数を指定します。

すべてのテーブルサイズチェックを省略し、スナップショットの実行中に常にすべての結果をストリーミングするには、このプロパティーを 0 に設定します。

heartbeat.interval.ms

0

コネクターがハートビートメッセージを Kafka トピックに送信する頻度を制御します。デフォルトの動作では、コネクターはハートビートメッセージを送信しません。

ハートビートメッセージは、コネクターがデータベースから変更イベントを受信しているかどうかを監視するのに便利です。ハートビートメッセージは、コネクターの再起動時に再送信する必要がある変更イベントの数を減らすのに役立つ可能性があります。ハートビートメッセージを送信するには、このプロパティーを、ハートビートメッセージの間隔をミリ秒単位で示す正の整数に設定します。

heartbeat.topics.prefix

__debezium-heartbeat

コネクターがハートビートメッセージを送信するトピックの名前を制御します。トピック名のパターンは次のようになります。
heartbeat.topics.prefix. server.name

たとえば、データベースサーバー名が
の場合、デフォルトのトピック名は fulfillment になります。__debezium-heartbeat.fulfillment

database.initial.statements

 

トランザクションログを読み取る接続ではなく、データベースへの JDBC 接続が確立されたときに実行される SQL ステートメントのセミコロン区切りのリスト。SQL ステートメントでセミコロンを区切り文字としてではなく文字として指定する場合は、2 つのセミコロン(;;)を使用します。

コネクターは独自の判断で JDBC 接続を確立する可能性があるため、このプロパティーはセッションパラメーターの設定専用です。DML ステートメントを実行するものではありません。

snapshot.delay.ms

 

コネクターの起動時にスナップショットを実行するまでコネクターが待つ必要がある間隔 (ミリ秒単位)。クラスターで複数のコネクターを起動する場合、このプロパティーは、コネクターのリバランスが行われる原因となるスナップショットの中断を防ぐのに役立ちます。

snapshot.fetch.size

 

スナップショットの実行中、コネクターは行のバッチでテーブルの内容を読み取ります。このプロパティーは、バッチの行の最大数を指定します。

snapshot.lock.timeout.ms

10000

スナップショットの実行時に、テーブルロックを取得するまで待つ最大時間 (ミリ秒単位) を指定する正の整数。コネクターがこの期間にテーブルロックを取得できないと、スナップショットは失敗します。「Debezium MySQL コネクターによるデータベーススナップショットの実行方法」を参照してください。

enable.time.adjuster

true

コネクターによって 2 桁の西暦が 4 桁の西暦に変換されるかどうかを示すブール値。変換が完全にデータベースに委譲されると false に設定されます。

MySQL では、2 桁の数値または 4 桁の数値のいずれかで年の値を挿入できます。2 桁の値の場合は、値は 1970 - 2069 の範囲の年にマッピングされます。デフォルトの動作では、コネクターは変換を行いません。

sanitize.field.names

true コネクター設定が key.converter または value.converter プロパティーを Avro コンバーターに設定する場合。
false に設定します。

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

skipped.operations

 

ストリーミング中にスキップする操作の型のコンマ区切りリスト。値には c (挿入/作成)、u (更新)、d (削除) を使用することができます。デフォルトでは、操作はスキップされません。

provide.transaction.metadata

false

コネクターがトランザクション境界でイベントを生成し、トランザクションメタデータで変更イベントエンベロープを強化するかどうかを決定します。これを行う場合は true を指定します。詳細は、「トランザクションメタデータ」を参照してください。

Debezium コネクターデータベース履歴設定プロパティー

Debezium は、コネクターがスキーマ履歴トピックと対話する方法を制御する database.history.* プロパティーのセットを提供します。

以下の表で、Debezium コネクターを設定するための database.history プロパティーを説明します。

表5.22 コネクターデータベース履歴設定プロパティー

プロパティーデフォルト説明

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 です。

プロデューサーおよびコンシューマークライアントを設定するためのパススルーデータベース履歴プロパティー


Debezium は Kafka プロデューサーを使用して、データベース履歴トピックにスキーマ変更を書き込みます。同様に、コネクターの起動時に、Kafka コンシューマーを使用してデータベース履歴トピックから読み取ります。database.history.producer.* および database.history.consumer.* プレフィックスで始まるパススルー設定プロパティーのセットに値を割り当てて、Kafka プロデューサーおよびコンシューマークライアントの設定を定義します。パススループロデューサーおよびコンシューマーデータベース履歴プロパティーは、以下の例のようにこれらのクライアントが Kafka ブローカーとの接続をセキュリティー保護する方法など、さまざまな動作を制御します。

database.history.producer.security.protocol=SSL
database.history.producer.ssl.keystore.location=/var/private/ssl/kafka.server.keystore.jks
database.history.producer.ssl.keystore.password=test1234
database.history.producer.ssl.truststore.location=/var/private/ssl/kafka.server.truststore.jks
database.history.producer.ssl.truststore.password=test1234
database.history.producer.ssl.key.password=test1234

database.history.consumer.security.protocol=SSL
database.history.consumer.ssl.keystore.location=/var/private/ssl/kafka.server.keystore.jks
database.history.consumer.ssl.keystore.password=test1234
database.history.consumer.ssl.truststore.location=/var/private/ssl/kafka.server.truststore.jks
database.history.consumer.ssl.truststore.password=test1234
database.history.consumer.ssl.key.password=test1234

Debezium は、プロパティーを Kafka クライアントに渡す前に、プロパティー名から接頭辞を取り除きます。

Kafka プロデューサー設定プロパティー および Kafka コンシューマー設定プロパティー の詳細は、Kafka のドキュメントを参照してください。

Debezium コネクターパススルーデータベースドライバー設定プロパティー

Debezium コネクターは、データベースドライバーのパススルー設定を提供します。パススルーデータベースプロパティーはプレフィックス database.* で始まります。たとえば、コネクターは database.foobar=false などのプロパティーを JDBC URL に渡します。

データベース履歴クライアントのパススループロパティー の場合と同様に、Debezium はプロパティーからプレフィックスを取り除き、データベースドライバーに渡します。

5.6. Debezium MySQL コネクターのパフォーマンスの監視

Debezium MySQL コネクターは、Zookeeper、Kafka、および Kafka Connect によって提供される JMX メトリクスの組み込みサポートに加えて、3 種類のメトリクスを提供します。

Debezium モニタリングのドキュメント では、JMX を使用してこれらのメトリクスを公開する方法の詳細を提供します。

5.6.1. MySQL データベースのスナップショット作成時の Debezium の監視

MBeandebezium.mysql:type=connector-metrics,context=snapshot,server=<database.server.name> です。

属性説明

LastEvent

string

コネクターが読み取りした最後のスナップショットイベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取りおよび処理してからの経過時間 (ミリ秒単位)。

TotalNumberOfEventsSeen

long

前回の開始またはリセット以降にコネクターで確認されたイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定された include/exclude リストのフィルタリングルールによってフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルの一覧。

QueueTotalCapacity

int

snapshotter とメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの長さ。

QueueRemainingCapacity

int

snapshotter とメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの空き容量。

TotalTableCount

int

スナップショットに含まれているテーブルの合計数。

RemainingTableCount

int

スナップショットによってまだコピーされていないテーブルの数。

SnapshotRunning

boolean

スナップショットが起動されたかどうか。

SnapshotAborted

boolean

スナップショットが中断されたかどうか。

SnapshotCompleted

boolean

スナップショットが完了したかどうか。

SnapshotDurationInSeconds

long

スナップショットが完了したかどうかに関わらず、これまでスナップショットにかかった時間 (秒単位)。

RowsScanned

Map<String, Long>

スナップショットの各テーブルに対してスキャンされる行数が含まれるマップ。テーブルは、処理中に増分がマップに追加されます。スキャンされた 10,000 行ごとに、テーブルの完成時に更新されます。

MaxQueueSizeInBytes

long

キューの最大バッファー (バイト単位)。max.queue.size.in.bytes が正の long 値で渡された場合に有効になります。

CurrentQueueSizeInBytes

long

キュー内のレコードの現在のデータ (バイト単位)。

Debezium MySQL コネクターは、HoldingGlobalLock カスタムスナップショットメトリクスも提供します。このメトリクスは、コネクターが現在グローバルまたはテーブル書き込みロックを保持するかどうかを示すブール値に設定されます。

5.6.2. Debezium MySQL コネクターレコードストリーミングの監視

MBeandebezium.mysql:type=connector-metrics,context=streaming,server=<database.server.name> です。

トランザクション関連の属性は、binlog イベントのバッファーが有効になっている場合にのみ利用できます。詳細は、「高度な MySQL コネクター設定プロパティー」の binlog.buffer.size を参照してください。

属性説明

LastEvent

string

コネクターが読み取られた最後のストリーミングイベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取りおよび処理してからの経過時間 (ミリ秒単位)。

TotalNumberOfEventsSeen

long

前回の開始またはリセット以降にコネクターで確認されたイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定された include/exclude リストのフィルタリングルールによってフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルの一覧。

QueueTotalCapacity

int

ストリーマーとメイン Kafka Connect ループの間でイベントを渡すために使用されるキューの長さ。

QueueRemainingCapacity

int

ストリーマーとメインの Kafka Connect ループの間でイベントを渡すために使用されるキューの空き容量。

Connected

boolean

コネクターが現在データベースサーバーに接続されているかどうかを示すフラグ。

MilliSecondsBehindSource

long

最後の変更イベントのタイムスタンプとそれを処理するコネクターとの間の期間 (ミリ秒単位)。この値は、データベースサーバーとコネクターが稼働しているマシンのクロック間の差異に対応します。

NumberOfCommittedTransactions

long

コミットされた処理済みトランザクションの数。

SourceEventPosition

Map<String, String>

最後に受信したイベントの位置。

LastTransactionId

string

最後に処理されたトランザクションのトランザクション識別子。

MaxQueueSizeInBytes

long

キューの最大バッファー (バイト単位)。

CurrentQueueSizeInBytes

long

キュー内のレコードの現在のデータ (バイト単位)。

Debezium MySQL コネクターは、以下の追加のストリーミングメトリクスも提供します。

表5.23 追加のストリーミングメトリクスの説明

属性説明

BinlogFilename

string

コネクターによって最後に読み取られた binlog ファイルの名前。

BinlogPosition

long

コネクターによって読み取られた binlog 内の最新の位置 (バイト単位)。

IsGtidModeEnabled

boolean

コネクターが現在 MySQL サーバーから GTID を追跡しているかどうかを示すフラグ。

GtidSet

string

binlog の読み取り時にコネクターによって処理される最新の GTID セットの文字列表現。

NumberOfSkippedEvents

long

MySQL コネクターによってスキップされたイベントの数。通常、MySQL の binlog からの不正形式のイベントまたは解析不可能なイベントが原因で、イベントがスキップされます。

NumberOfDisconnects

long

MySQL コネクターによる切断の数。

NumberOfRolledBackTransactions

long

ロールバックされ、ストリーミングされなかった処理済みトランザクションの数。

NumberOfNotWellFormedTransactions

long

想定された BEGIN + COMMIT/ROLLBACK のプロトコルに準拠していないトランザクションの数。この値は、通常の条件下では 0 である必要があります。

NumberOfLargeTransactions

long

先読みバッファーに適合しないトランザクションの数。パフォーマンスを最適化するには、この値をNumberOfCommittedTransactions および NumberOfRolledBackTransactions よりも大幅に小さくする必要があります。

5.6.3. Debezium MySQL コネクターのスキーマ履歴の監視

MBeandebezium.mysql:type=connector-metrics,context=schema-history,server=<database.server.name> です。

属性説明

Status

string

データベース履歴の状態を示す STOPPEDRECOVERING (ストレージから履歴を復元)、または RUNNING のいずれか。

RecoveryStartTime

long

リカバリーが開始された時点のエポック秒の時間。

ChangesRecovered

long

リカバリーフェーズ中に読み取られた変更の数。

ChangesApplied

long

リカバリーおよびランタイム中に適用されるスキーマ変更の合計数。

MilliSecondsSinceLast​RecoveredChange

long

最後の変更が履歴ストアから復元された時点からの経過時間 (ミリ秒単位)。

MilliSecondsSinceLast​AppliedChange

long

最後の変更が適用された時点からの経過時間 (ミリ秒単位)。

LastRecoveredChange

string

履歴ストアから復元された最後の変更の文字列表現。

LastAppliedChange

string

最後に適用された変更の文字列表現。

5.7. Debezium MySQL コネクターによる障害および問題の処理方法

Debezium は、複数のアップストリームデータベースのすべての変更をキャプチャーする分散システムであり、イベントの見逃しや損失は発生しません。システムが正常に操作している場合や、慎重に管理されている場合は、Debezium は変更イベントレコードごとに 1 度だけ 配信します。

障害が発生しても、システムはイベントを失いません。ただし、障害から復旧している間は、変更イベントが繰り返えされる可能性があります。このような正常でない状態では、Debezium は Kafka と同様に、変更イベントを 少なくとも 1 回 配信します。

詳細は以下を参照してください。

設定および起動エラー

以下の状況では、起動時にコネクターが失敗し、エラーまたは例外がログに記録され、実行が停止されます。

  • コネクターの設定が無効である。
  • 指定の接続パラメーターを使用してコネクターを MySQL サーバーに接続できない。
  • MySQL に履歴がない binlog の位置でコネクターが再起動を試行する。

このような場合、エラーメッセージには問題の詳細が含まれ、推奨される回避策も含まれることがあります。設定の修正したり、MySQL の問題に対処した後、コネクターを再起動します。

MySQL が使用不可能になる

MySQL サーバーが利用できなくなると、Debezium MySQL コネクターはエラーで失敗し、コネクターが停止します。サーバーが再び使用できるようになったら、コネクターを再起動します。

ただし、高可用性 MySQL クラスターで GTID が有効になっている場合は、コネクターをすぐに再起動できます。これはクラスターの別の MySQL サーバーに接続し、最後のトランザクションを表すサーバーの binlog の場所を特定し、その特定の場所から新しいサーバーの binlog の読み取りを開始します。

GTID が有効になっていない場合、コネクターは接続した MySQL サーバーのみの binlog の位置を記録します。正しい binlog の位置から再起動するには、その特定のサーバーに再接続する必要があります。

Kafka Connect が正常に停止する

Kafka Connect が正常に停止すると、Debezium MySQL コネクタータスクが停止され、新しい Kafka Connect プロセスで再起動される間に短い遅延が発生します。

Kafka Connect プロセスがクラッシュする

Kafka Connect がクラッシュすると、プロセスが停止し、最後に処理されたオフセットが記録されずに Debezium MySQL コネクタータスクが終了します。分散モードでは、Kafka Connect は他のプロセスでコネクタータスクを再起動します。ただし、MySQL コネクターは以前のプロセスで記録された最後のオフセットから再開します。つまり、代替のタスクによってクラッシュ前に処理された同じイベントの一部が生成され、重複したイベントが作成される可能性があります。

各変更イベントメッセージには、重複イベントの特定に使用できるソース固有の情報が含まれます。以下に例を示します。

  • イベント元
  • MySQL サーバーのイベント時間
  • binlog ファイル名と位置
  • GTID (使用されている場合)

Kafka が使用不可能になる

Kafka Connect フレームワークは、Kafka プロデューサー API を使用して Debezium 変更イベントを記録します。Kafka ブローカーが利用できなくなると、Debezium MySQL コネクターは接続が再確立されるまで一時停止され、一時停止した位置で再開されます。

MySQL が binlog ファイルをパージする

Debezium MySQL コネクターが長時間停止すると、MySQL サーバーは古い binlog ファイルをパージするため、コネクターの最後の位置が失われる可能性があります。コネクターが再起動すると、MySQL サーバーに開始点がなくなり、コネクターは別の最初のスナップショットを実行します。スナップショットが無効の場合、コネクターはエラーによって失敗します。

MySQL コネクターが最初のスナップショットを実行する方法に関する詳細は「Debezium MySQL コネクターによるデータベーススナップショットの実行方法」を参照してください。

第6章 Oracle 用 Debezium コネクター (開発者プレビュー)

Debezium の Oracle コネクターは、コネクターの実行中に追加されたテーブルなど、Oracle サーバーのデータベースで発生する行レベルの変更をキャプチャーし、記録します。コネクターを設定して、スキーマとテーブルの特定サブセットの変更イベントを出力するか、特定の列の値を無視、マスク、または切り捨てできます。

Debezium は、ネイティブ LogMiner データベースパッケージを使用して Oracle から変更イベントを取得します。

重要

Debezium Oracle コネクターは開発者プレビュー機能です。開発者プレビューの機能は、最新の技術をいち早く提供して、開発段階で機能のテストやフィードバックの収集を可能にするために提供されます。開発者プレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat は開発者プレビュー機能を実稼働環境に実装することは推奨しません。この機能に関してサポートが必要な場合には、Debezium コミュニティー と連携できます。

Debezium Oracle コネクターの使用に関する情報および手順は、以下のように整理されています。

6.1. Debezium Oracle コネクターの仕組み

Debezium Oracle コネクターを最適に設定および実行するには、コネクターによるスナップショットの実行方法、変更イベントのストリーム方法、Kafka トピック名の決定方法、およびメタデータの使用方法を理解すると便利です。

詳細は以下を参照してください。

6.1.1. Debezium Oracle コネクターによるデータベーススナップショットの実行方法

通常、Oracle サーバーの redo ログは、データベースの完全な履歴を保持しないように設定されています。そのため、Debezium Oracle コネクターはデータベースの全履歴をログから取得できません。コネクターがデータベースの現在の状態のベースラインを確立できるようにするには、コネクターが最初に起動すると、データベースの初期 整合性スナップショット を実行します。

snapshot.mode コネクター設定プロパティーの値を設定することで、コネクターがスナップショットを作成する方法をカスタマイズできます。デフォルトでは、コネクターのスナップショットモードは initial に設定されます。

初期スナップショットを作成するためのデフォルトのコネクターワークフロー

スナップショットモードがデフォルトに設定されている場合、コネクターは以下のタスクを完了してスナップショットを作成します。

  1. キャプチャーするテーブルを決定します。
  2. 監視される各テーブルで EXCLUSIVE MODE ロックを取得し、スナップショットの作成時に構造が変更されないようにします。Debezium は短期間のみロックを保持します。
  3. サーバーの redo ログから現在のシステム変更番号 (SCN) の位置を読み取ります。
  4. 関連するテーブルすべての構造をキャプチャーします。
  5. ステップ 2 で取得したロックを解放します。
  6. ステップ 3(SELECT * FROM …​ AS OF SCN 123)で読み込まれた SCN の位置で、関連するデータベーステーブルおよびスキーマをすべてスキャンし、各行の READ イベントを生成し、イベントレコードをテーブル固有の Kafka トピックに書き込みます。
  7. コネクターオフセットにスナップショットの正常な完了を記録します。

スナップショットプロセスが開始されたら、コネクターの障害、リバランス、またはその他の理由でプロセスが中断された場合には、コネクターの再起動後にプロセスが再開されます。コネクターによって初期スナップショットが完了した後、ステップ 3 で読み取られた位置からストリーミングが続行され、更新を見逃しません。何らかの理由でコネクターが再び停止した場合、再起動後に、以前停止した場所から変更のストリーミングが再開されます。

表6.1 snapshot.mode コネクター設定プロパティーの設定

設定説明

initial

コネクターは、「初期スナップショット作成のデフォルトフロー」で説明されているように、データベースのスナップショットを実行します。スナップショットの完了後、コネクターは後続のデータベースの変更についてのイベントレコードのストリーミングを開始します。

schema_only

コネクターは関連するすべてのテーブルの構造をキャプチャーし、「スナップショットのデフォルトワークフロー」に記載されるすべてのステップを実行します。ただし、コネクターの起動時点でのデータセットを表す READ イベントは作成されません (ステップ 6)。

6.1.2. Debezium Oracle 変更イベントレコードを受信する Kafka トピックのデフォルト名

デフォルトの動作では、Debezium Oracle コネクターは 1 つのテーブルの INSERTUPDATE、および DELETE 操作すべてのイベントを 1 つの Kafka トピックに書き込みます。Kafka トピックの命名規則は次のとおりです。

serverName.schemaName.tableName

たとえば、fulfillment がサーバー名、inventory がスキーマ名で、データベースに orderscustomers、および products という名前のテーブルが含まれる場合、Debezium Oracle コネクターはデータベースの各テーブルごとに以下の Kafka トピックにイベントを出力します。

fulfillment.inventory.orders
fulfillment.inventory.customers
fulfillment.inventory.products

6.1.3. Debezium Oracle コネクターによるデータベーススキーマの変更の公開方法

Debezium Oracle コネクターは、スキーマ変更の履歴をデータベース履歴トピックに保存します。このトピックは内部コネクターの状態を反映するため、直接使用しないでください。アプリケーションがスキーマの変更に関する通知を必要とする場合は、パブリックスキーマの変更トピックから情報を取得する必要があります。コネクターは、<serverName> という名前の Kafka トピックにスキーマ変更イベントを書き込みます。ここで、serverNamedatabase.server.name 設定プロパティーに指定されたコネクターの名前になります。

Debezium は、新しいテーブルからデータをストリーミングするたびに、このトピックに新しいメッセージを出力します。

メッセージには、テーブルスキーマの論理表現が含まれます。

例: スキーマ変更トピックに出力されたメッセージ

以下の例は、JSON 形式の一般的なスキーマ変更メッセージを示しています。

{
  "schema": {
  ...
  },
  "payload": {
    "source": {
      "version": "1.5.4.Final",
      "connector": "oracle",
      "name": "server1",
      "ts_ms": 1588252618953,
      "snapshot": "true",
      "db": "ORCLPDB1",
      "schema": "DEBEZIUM",
      "table": "CUSTOMERS",
      "txId" : null,
      "scn" : "1513734",
      "commit_scn": "1513734",
      "lcr_position" : null
    },
    "databaseName": "ORCLPDB1", 1
    "schemaName": "DEBEZIUM", //
    "ddl": "CREATE TABLE \"DEBEZIUM\".\"CUSTOMERS\" \n   (    \"ID\" NUMBER(9,0) NOT NULL ENABLE, \n    \"FIRST_NAME\" VARCHAR2(255), \n    \"LAST_NAME" VARCHAR2(255), \n    \"EMAIL\" VARCHAR2(255), \n     PRIMARY KEY (\"ID\") ENABLE, \n     SUPPLEMENTAL LOG DATA (ALL) COLUMNS\n   ) SEGMENT CREATION IMMEDIATE \n  PCTFREE 10 PCTUSED 40 INITRANS 1 MAXTRANS 255 \n NOCOMPRESS LOGGING\n  STORAGE(INITIAL 65536 NEXT 1048576 MINEXTENTS 1 MAXEXTENTS 2147483645\n  PCTINCREASE 0 FREELISTS 1 FREELIST GROUPS 1\n  BUFFER_POOL DEFAULT FLASH_CACHE DEFAULT CELL_FLASH_CACHE DEFAULT)\n  TABLESPACE \"USERS\" ", 2
    "tableChanges": [ 3
      {
        "type": "CREATE", 4
        "id": "\"ORCLPDB1\".\"DEBEZIUM\".\"CUSTOMERS\"", 5
        "table": { 6
          "defaultCharsetName": null,
          "primaryKeyColumnNames": [ 7
            "ID"
          ],
          "columns": [ 8
            {
              "name": "ID",
              "jdbcType": 2,
              "nativeType": null,
              "typeName": "NUMBER",
              "typeExpression": "NUMBER",
              "charsetName": null,
              "length": 9,
              "scale": 0,
              "position": 1,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "FIRST_NAME",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "VARCHAR2",
              "typeExpression": "VARCHAR2",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 2,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "LAST_NAME",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "VARCHAR2",
              "typeExpression": "VARCHAR2",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 3,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "EMAIL",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "VARCHAR2",
              "typeExpression": "VARCHAR2",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 4,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            }
          ]
        }
      }
    ]
  }
}

表6.2 スキーマ変更トピックに出力されたメッセージのフィールドの説明

項目フィールド名説明

1

databaseName
schemaName

変更が含まれるデータベースとスキーマを識別します。

2

ddl

このフィールドには、スキーマの変更を行う DDL が含まれます。

3

tableChanges

DDL コマンドによって生成されるスキーマの変更が含まれる 1 つ以上の項目の配列。

4

type

変更の種類を説明します。値は以下のいずれかになります。

CREATE
テーブルの作成
ALTER
テーブルの変更
DROP
テーブルの削除

5

id

作成、変更、または破棄されたテーブルの完全な識別子。

6

table

適用された変更後のテーブルメタデータを表します。

7

primaryKeyColumnNames

テーブルのプライマリーキーを構成する列のリスト。

8

columns

変更されたテーブルの各列のメタデータ。

コネクターがスキーマ変更トピックに送信するメッセージは、スキーマ変更が含まれるデータベースの名前と同じメッセージキーを使用します。以下の例では、payload フィールドにキーが含まれます。

{
  "schema": {
    "type": "struct",
    "fields": [
      {
        "type": "string",
        "optional": false,
        "field": "databaseName"
      }
    ],
    "optional": false,
    "name": "io.debezium.connector.oracle.SchemaChangeKey"
  },
  "payload": {
    "databaseName": "ORCLPDB1"
  }
}

6.1.4. トランザクション境界を表す Debezium Oracle コネクターによって生成されたイベント

Debezium は、トランザクションメタデータ境界を表し、データ変更イベントメッセージをエンリッチするイベントを生成できます。

データベーストランザクションは、キーワード BEGIN および END で囲まれたステートメントブロックによって表されます。Debezium は、すべてのトランザクションで BEGIN および END 区切り文字のトランザクション境界イベントを生成します。トランザクション境界イベントには以下のフィールドが含まれます。

status
BEGIN または END
id
一意のトランザクション識別子の文字列表現。
event_count (END イベント用)
トランザクションによって出力されるイベントの合計数。
data_collections (END イベント用)
指定のデータコレクションからの変更によって出力されたイベントの数を提供する data_collectionevent_count のペアの配列。

以下の例は、典型的なトランザクション境界メッセージを示しています。

例: Oracle コネクタートランザクション境界イベント

{
  "status": "BEGIN",
  "id": "5.6.641",
  "event_count": null,
  "data_collections": null
}

{
  "status": "END",
  "id": "5.6.641",
  "event_count": 2,
  "data_collections": [
    {
      "data_collection": "ORCLPDB1.DEBEZIUM.CUSTOMER",
      "event_count": 1
    },
    {
      "data_collection": "ORCLPDB1.DEBEZIUM.ORDER",
      "event_count": 1
    }
  ]
}

トランザクションイベントは、<database.server.name>.transaction という名前のトピックに書き込まれます。

6.1.4.1. 変更データイベントのエンリッチメント

トランザクションメタデータを有効にすると、データメッセージ Envelope は新しい transaction フィールドでエンリッチされます。このフィールドは、複合フィールドの形式ですべてのイベントに関する情報を提供します。

id
一意のトランザクション識別子の文字列表現。
total_order
トランザクションによって生成されたすべてのイベントを対象とするイベントの絶対位置。
data_collection_order
トランザクションによって出力されたすべてのイベントを対象とするイベントのデータコレクションごとの位置。

以下の例は、典型的なトランザクションイベントメッセージを示しています。

{
  "before": null,
  "after": {
    "pk": "2",
    "aa": "1"
  },
  "source": {
...
  },
  "op": "c",
  "ts_ms": "1580390884335",
  "transaction": {
    "id": "5.6.641",
    "total_order": "1",
    "data_collection_order": "1"
  }
}

6.2. Debezium Oracle コネクターのデータ変更イベントの説明

Oracle コネクターが出力するデータ変更イベントはすべてキーと値を持ちます。キーと値の構造は、変更イベントの起点となるテーブルによって異なります。Debezium がトピック名を構成する方法の詳細は、「トピック名」を参照してください。

警告

Debezium Oracle コネクターは、すべての Kafka Connect スキーマ名有効な Avro スキーマ名 になるようにします。つまり、論理サーバー名はアルファベットまたはアンダースコア ([a-z、A-Z、_]) で始まり、論理サーバー名の残りの文字ならびにスキーマおよびテーブル名のすべての文字は英数字またはアンダースコア ([a-z、A-Z、0-9、_]) でなければなりません。コネクターは無効な文字をアンダースコア文字に自動的に置き換えます。

複数の論理サーバー名、スキーマ名、またはテーブル名を唯一区別する文字が無効な文字の場合、それらの文字がアンダースコアと置き換えられ、予期せぬ名前の競合が生じる場合があります。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリーム を中心として設計されています。ただし、これらのイベントの構造は時間の経過とともに変化する可能性があり、トピックコンシューマーによる処理が困難になることがあります。ミュータブルなイベント構造の処理を容易にするために、Kafka Connect の各イベントが自己完結型になります。すべてのメッセージキーと値には、スキーマペイロード の 2 つの部分があります。スキーマはペイロードの構造を記述しますが、ペイロードには実際のデータが含まれます。

警告

SYSSYSTEM、またはコネクターユーザーアカウントによって実行される変更は、コネクターによってキャプチャーされません。

以下のトピックでは、データ変更イベントの詳細を示しています。

6.2.1. Debezium Oracle コネクターの変更イベントのキー

変更されたそれぞれのテーブルについて、変更イベントキーは、イベントの作成時にテーブルのプライマリーキー (または一意なキー制約) の各列にフィールドが存在するように構成されます。

たとえば、inventory データベーススキーマに定義されている customers テーブルには、以下の変更イベントキーが含まれる場合があります。

CREATE TABLE customers (
  id NUMBER(9) GENERATED BY DEFAULT ON NULL AS IDENTITY (START WITH 1001) NOT NULL PRIMARY KEY,
  first_name VARCHAR2(255) NOT NULL,
  last_name VARCHAR2(255) NOT NULL,
  email VARCHAR2(255) NOT NULL UNIQUE
);

database.server.name 設定プロパティーの値が server1 に設定された場合、データベースの customers テーブルで発生するすべての変更イベントの JSON 表現には以下のキー構造があります。

{
    "schema": {
        "type": "struct",
        "fields": [
            {
                "type": "int32",
                "optional": false,
                "field": "ID"
            }
        ],
        "optional": false,
        "name": "server1.INVENTORY.CUSTOMERS.Key"
    },
    "payload": {
        "ID": 1004
    }
}

キーの schema 部分には、キー部分の内容を記述する Kafka Connect スキーマが含まれます。上記の例では、payload の値はオプションではありません。構造は server1.DEBEZIUM.CUSTOMERS.Key という名前のスキーマによって定義され、タイプ int32id という名前の必須フィールドが 1 つあります。キーの payload フィールドの値は、これが単一の id フィールド (その値は 1004) を持つ構造 (JSON のオブジェクト) であることを示しています。

そのため、id プライマリーキー列の値が 1004 である inventory.customers テーブルの行 (server1 という名前のコネクターからの出力) を説明するものとしてこのキーを解釈できます。

6.2.2. Debezium Oracle コネクターの変更イベントの値

メッセージキーと同様に、変更イベントメッセージの値には スキーマ セクションと ペイロード セクションがあります。Oracle コネクターによって生成されたすべての変更イベント値のペイロードセクションには、以下のフィールドを含む エンベロープ 構造があります。

op
操作のタイプを記述する文字列値が含まれる必須フィールド。Oracle コネクターの値は、c (作成または挿入)、u (更新)、d (削除)、および r (読み取り、スナップショットの場合) です。
before

任意のフィールド。存在する場合は、イベント発生の行の状態が含まれます。構造は、server1 コネクターが inventory.customers テーブルのすべての行に使用する server1.INVENTORY.CUSTOMERS.Value Kafka Connect スキーマによって記述されます。

警告

このフィールドとその要素を利用できるかどうかは、テーブルに適用する Supplemental Logging 設定により大きく左右されます。

after
任意のフィールド。存在する場合は、イベント発生 の行の状態が含まれます。構造は、before で使用されるのと同じ server1.INVENTORY.CUSTOMERS.Value Kafka Connect スキーマによって記述されます。
source

イベントのソースメタデータを記述する構造が含まれる必須のフィールドです。Oracle の場合、これには以下のフィールドが含まれます。Debezium のバージョン、コネクター名、イベントが継続中のスナップショットの一部であるかどうか、トランザクション ID (スナップショット中でない)、変更時の SCN、および (スナップショット作成中)、およびソースデータベースでレコードが変更された時点を示すタイムスタンプ (スナップショットの作成中は、スナップショットの時点)。

ヒント

commit_scn フィールドはオプションで、変更イベントが参加するトランザクションコミットの SCN を記述します。このフィールドは、LogMiner 接続アダプターを使用している場合にのみ表示されます。

ts_ms
任意のフィールド。存在する場合は、コネクターがイベントを処理した時間 (Kafka Connect タスクを実行する JVM のシステムクロックを使用) が含まれます。

当然ながら、イベントメッセージの値の スキーマ の部分には、このエンベロープ構造と、その中のネストされたフィールドを記述するスキーマが含まれています。

作成 イベント

customers テーブルの 作成 イベントの値がどのようになるか見てみましょう。

{
    "schema": {
        "type": "struct",
        "fields": [
            {
                "type": "struct",
                "fields": [
                    {
                        "type": "int32",
                        "optional": false,
                        "field": "ID"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "FIRST_NAME"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "LAST_NAME"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "EMAIL"
                    }
                ],
                "optional": true,
                "name": "server1.DEBEZIUM.CUSTOMERS.Value",
                "field": "before"
            },
            {
                "type": "struct",
                "fields": [
                    {
                        "type": "int32",
                        "optional": false,
                        "field": "ID"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "FIRST_NAME"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "LAST_NAME"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "EMAIL"
                    }
                ],
                "optional": true,
                "name": "server1.DEBEZIUM.CUSTOMERS.Value",
                "field": "after"
            },
            {
                "type": "struct",
                "fields": [
                    {
                        "type": "string",
                        "optional": true,
                        "field": "version"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "name"
                    },
                    {
                        "type": "int64",
                        "optional": true,
                        "field": "ts_ms"
                    },
                    {
                        "type": "string",
                        "optional": true,
                        "field": "txId"
                    },
                    {
                        "type": "string",
                        "optional": true,
                        "field": "scn"
                    },
                    {
                        "type": "string",
                        "optional": true,
                        "field": "commit_scn"
                    },
                    {
                        "type": "boolean",
                        "optional": true,
                        "field": "snapshot"
                    }
                ],
                "optional": false,
                "name": "io.debezium.connector.oracle.Source",
                "field": "source"
            },
            {
                "type": "string",
                "optional": false,
                "field": "op"
            },
            {
                "type": "int64",
                "optional": true,
                "field": "ts_ms"
            }
        ],
        "optional": false,
        "name": "server1.DEBEZIUM.CUSTOMERS.Envelope"
    },
    "payload": {
        "before": null,
        "after": {
            "ID": 1004,
            "FIRST_NAME": "Anne",
            "LAST_NAME": "Kretchmar",
            "EMAIL": "annek@noanswer.org"
        },
        "source": {
            "version": "1.5.4.Final",
            "name": "server1",
            "ts_ms": 1520085154000,
            "txId": "6.28.807",
            "scn": "2122185",
            "commit_scn": "2122185",
            "snapshot": false
        },
        "op": "c",
        "ts_ms": 1532592105975
    }
}

前述のイベントの schema の部分を調べます。以下のスキーマがどのように定義されているかを確認できます。

  • エンベロープ
  • source 構造 (Oracle コネクターに固有のもので、すべてのイベントで再利用されます)。
  • before および after フィールドのテーブル固有のスキーマ。
ヒント

before および after フィールドのスキーマの名前は <logicalName>.<schemaName>.<tableName>.Value の形式であるため、他のすべてのテーブルのスキーマから完全に独立しています。つまり、Avro コンバーター を使用する場合、得られる各 論理ソース各テーブル の Avro スキーマには独自の進化と履歴があります。

このイベントの payload 部分は、イベントに関する情報を提供します。これは、行が作成され (op=c)、after フィールドの値に、行の IDFIRST_NAMELAST_NAME、および EMAIL 列に挿入された値が含まれていることを表しています。

ヒント

デフォルトでは、イベントの JSON 表現はそれが記述する行よりもはるかに大きくなります。これは、JSON 表現にはメッセージの スキーマ 部分と ペイロード 部分を含める必要があるためです。Avro コンバーター を使用して、コネクターが Kafka トピックに書き込むメッセージのサイズを大幅に小さくすることができます。

更新イベント

このテーブルの 更新 変更イベントの値は、作成 イベントと同じ スキーマ を持ちます。ペイロードは同じ構造を使用しますが、異なる値を保持します。以下は例になります。

{
    "schema": { ... },
    "payload": {
        "before": {
            "ID": 1004,
            "FIRST_NAME": "Anne",
            "LAST_NAME": "Kretchmar",
            "EMAIL": "annek@noanswer.org"
        },
        "after": {
            "ID": 1004,
            "FIRST_NAME": "Anne",
            "LAST_NAME": "Kretchmar",
            "EMAIL": "anne@example.com"
        },
        "source": {
            "version": "1.5.4.Final",
            "name": "server1",
            "ts_ms": 1520085811000,
            "txId": "6.9.809",
            "scn": "2125544",
            "commit_scn": "2125544",
            "snapshot": false
        },
        "op": "u",
        "ts_ms": 1532592713485
    }
}

更新 イベントの値を 作成 (挿入) イベントと比較して、payload セクションの以下の違いに注意してください。

  • op フィールドの値は u になっており、更新によってこの行が変更されたことを示しています。
  • before フィールドは、データベースのコミット前の行と値の状態を表しています。
  • after フィールドは、更新された行の状態を表し、EMAIL の値が anne@example.com になっているのが分かります。
  • source フィールドの構造には以前と同じフィールドがありますが、このイベントは redo ログの別の位置からのものなので、値は異なります。
  • ts_ms は、Debezium がこのイベントを処理したタイムスタンプを表します。

payload セクションは、他のいくつかの便利な情報を示します。たとえば、beforeafter 構造を比較することで、コミットの結果として行がどのように変更されたかを判断できます。source 構造は、この変更の Oracle の記録に関する情報を提供し、トレース性を提供します。また、本トピックおよび他のトピックの他のイベントとの関連で、このイベントがいつ発生したかも分かります。発生の前後関係、あるいは他のイベントと同じコミットの一部として発生したかが分かります。

注記

行のプライマリーキー/一意キーの列が更新されると、行のキーの値が変更されます。その結果、Debezium は更新後に 3 つの イベントを出力します。

削除 イベント

これまで、作成 および 更新 イベントの例を見てきました。ここで、同じテーブルの 削除 イベントの値を見てみましょう。作成更新 イベントの場合と同様、delete イベントの場合、値の schema の部分はまったく同じです。

{
    "schema": { ... },
    "payload": {
        "before": {
            "ID": 1004,
            "FIRST_NAME": "Anne",
            "LAST_NAME": "Kretchmar",
            "EMAIL": "anne@example.com"
        },
        "after": null,
        "source": {
            "version": "1.5.4.Final",
            "name": "server1",
            "ts_ms": 1520085153000,
            "txId": "6.28.807",
            "scn": "2122184",
            "commit_scn": "2122184",
            "snapshot": false
        },
        "op": "d",
        "ts_ms": 1532592105960
    }
}

payload の部分を確認すると、作成 または 更新 イベントのペイロードと比較して、多数の差異があります。

  • op フィールドの値は d になっており、この行が削除されたことを示しています。
  • before フィールドは、データベースのコミットで削除した行の状態を表しています。
  • after フィールドは null で、行が存在しないことを示します。
  • source フィールド構造には以前と同じ値が多数ありますが、ts_msscn、および txId フィールドは更新されています。
  • ts_ms は、Debezium がこのイベントを処理したタイムスタンプを表します。

このイベントは、コンシューマーがこの行の削除を処理するのに使用できるあらゆる種類の情報を提供します。

Oracle コネクターのイベントは、Kafka ログコンパクション と動作するように設計されています。これにより、すべてのキーで少なくとも最新のメッセージが保持される限り、古いメッセージを削除できます。これにより、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できるようにするとともに、Kafka がストレージ領域を開放できるようにします。

行が削除された場合でも、Kafka は同じキーを持つ以前のメッセージをすべて削除できるため、上述の 削除 イベントの値は引き続きログコンパクションで動作します。同じキーを共有する すべてのメッセージ を削除するよう Kafka に指示するには、メッセージの値を null に設定する必要があります。これを可能にするには、デフォルトでは Debezium の Oracle コネクターは、必ず値が null の同じキーを持つ特別な 廃棄 イベントで 削除 イベントに従います。コネクタープロパティー tombstones.on.delete を設定すると、デフォルトの動作を変更できます。

6.3. Debezium Oracle コネクターによるデータ型のマッピング方法

テーブル行で発生する変更を表すには、Debezium Oracle コネクターは、行が存在するテーブルのように構造化された変更イベントを出力します。イベントには、各列の値のフィールドが含まれます。列の値は、列の Oracle データ型に従って表現されます。以下のセクションでは、oracle データ型をイベントフィールドの リテラル型 および セマンティック型 にマッピングする方法を説明します。

リテラル型
Kafka Connect スキーマ型 INT8INT16INT32INT64FLOAT32FLOAT64BOOLEANSTRINGBYTESARRAYMAP、および STRUCT を使用して、値をリテラルで表す方法を記述します。
セマンティック型
フィールドの Kafka Connect スキーマの名前を使用して、Kafka Connect スキーマがフィールドの 意味 をキャプチャーする方法を記述します。

詳細は以下を参照してください。

文字型

以下の表は、コネクターによる基本文字型のマッピング方法を説明しています。

表6.3 Oracle の基本文字型のマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

CHAR[(M)]

STRING

該当なし

NCHAR[(M)]

STRING

該当なし

NVARCHAR2[(M)]

STRING

該当なし

VARCHAR[(M)]

STRING

該当なし

VARCHAR2[(M)]

STRING

該当なし

バイナリーおよび文字 LOB 型

以下の表は、コネクターによるバイナリーおよび文字 LOB 型のマッピング方法を説明しています。

表6.4 Oracle バイナリーおよび文字 LOB 型のマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

BLOB

該当なし

このデータ型はサポートされていません。

CLOB

該当なし

このデータ型はサポートされていません。

LONG

該当なし

このデータ型はサポートされていません。

LONG RAW

該当なし

このデータ型はサポートされていません。

NCLOB

該当なし

このデータ型はサポートされていません。

RAW

該当なし

このデータ型はサポートされていません。

数値型

以下の表は、コネクターによる数値型のマッピング方法を説明しています。

表6.5 Oracle 数値データ型のマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

BINARY_FLOAT

FLOAT32

該当なし

BINARY_DOUBLE

FLOAT64

該当なし

DECIMAL[(P, S)]

BYTES / INT8 / INT16 / INT32 / INT64

org.apache.kafka.connect.data.Decimal BYTES

を使用して NUMBER に同等の処理を行う場合(S は DECIMALのデフォルトは 0 であることに注意してください)。

DOUBLE PRECISION

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる scale 型の INT32 と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドを持つ構造が含まれます。

FLOAT[(P)]

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる scale 型の INT32 と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドを持つ構造が含まれます。

INTEGERINT

BYTES

org.apache.kafka.connect.data.Decimal

INTEGER Oracle から NUMBER(38,0)にマッピングされるため、INT 型よりも大きな値を保持することができます。

NUMBER[(P[, *])]

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる scale 型の INT32 と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドを持つ構造が含まれます。

NUMBER(P, S <= 0)

INT8 / INT16 / INT32 / INT64

スケールが 0 の NUMBER 列は、整数値を表します。負のスケーリングは、Oracle の丸めを示しています。たとえば、-2 のスケールでは数百ものになります。

精度とスケーリングに応じて、以下の一致する Kafka Connect 整数型の 1 つが選択されます。

  • P - S < 3、INT8
  • P - S < 5、INT16
  • P - S < 10、INT32
  • P - S < 19、INT64
  • P - S >= 19、BYTES (org.apache.kafka.connect.data.Decimal)

NUMBER(P, S > 0)

BYTES

org.apache.kafka.connect.data.Decimal

NUMERIC[(P, S)]

BYTES / INT8 / INT16 / INT32 / INT64

org.apache.kafka.connect.data.Decimal BYTES

を使用して NUMBER に同等の処理を行う場合(S は NUMERICのデフォルトは 0 であることに注意してください)。

SMALLINT

BYTES

org.apache.kafka.connect.data.Decimal

SMALLINT Oracle から NUMBER(38,0)にマッピングされるため、INT 型よりも大きな値を保持することができます。

REAL

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる scale 型の INT32 と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドを持つ構造が含まれます。

ブール値型

Oracle は、BOOLEAN データ型をネイティブにサポートしていませんが、論理 BOOLEAN データ型の概念をシミュレートするために、特定のセマンティクスと他のデータ型を使用するのは一般的な方法です。

Operator は、追加設定なしで NumberOneToBooleanConverter カスタムコンバーターを設定することができます。このコンバーターは、すべての NUMBER(1) 列を BOOLEAN にマッピングするか、または selector パラメーターが設定されている場合、正規表現のコンマ区切りリストを使用して列のサブセットを列挙できます。

以下は ConfigMap の例になります。

converters=boolean
boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter
boolean.selector=.*MYTABLE.FLAG,.*.IS_ARCHIVED

10 進数型

Oracle コネクター設定プロパティーの設定 decimal.handling.mode は、コネクターが 10 進数型をマッピングする方法を決定します。

decimal.handling.mode プロパティーが precise に設定された場合、コネクターはすべての DECIMAL および NUMERIC 列に Kafka Connect の org.apache.kafka.connect.data.Decimal 論理型を使用します。これはデフォルトのモードです。

ただし、decimal.handling.mode プロパティーが double に設定された場合、コネクターは値をスキーマ型 FLOAT64 の Java double 値として表します。

string オプションを使用するように decimal.handling.mode 設定プロパティーを設定することもできます。プロパティーを string に設定すると、コネクターは DECIMAL および NUMERIC の値をスキーマ型 STRING のフォーマットされた文字列表現として表します。

時間型

Oracle の INTERVALTIMESTAMP WITH TIME ZONE、および TIMESTAMP WITH LOCAL TIME ZONE データ型を除き、他の時間型は time.precision.mode 設定プロパティーの値によって異なります。

time.precision.mode 設定プロパティーが adaptive (デフォルト) に設定された場合、コネクターは列のデータ型を基に時間型のリテラルおよびセマンティック型を決定し、イベントが正確にデータベースの値を表すようにします。

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

DATE

INT64

io.debezium.time.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

INTERVAL DAY[(M)] TO SECOND

FLOAT64

io.debezium.time.MicroDuration

毎月平均に 365.25 / 12.0 式を使用する間隔のマイクロ秒数。

INTERVAL YEAR[(M)] TO MONTH

FLOAT64

io.debezium.time.MicroDuration

毎月平均に 365.25 / 12.0 式を使用する間隔のマイクロ秒数。

TIMESTAMP(0 - 3)

INT64

io.debezium.time.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP, TIMESTAMP(4 - 6)

INT64

io.debezium.time.MicroTimestamp

エポックからの経過時間をマイクロ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP(7 - 9)

INT64

io.debezium.time.NanoTimestamp

エポックからの経過時間をナノ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP WITH TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

タイムゾーン情報を含むタイムスタンプの文字列表現。

TIMESTAMP WITH LOCAL TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

UTC でのタイムスタンプの文字列表現。

time.precision.mode 設定プロパティーが connect に設定された場合、コネクターは事前定義された Kafka Connect の論理型を使用します。これは、コンシューマーが組み込みの Kafka Connect の論理型のみを認識し、可変精度の時間値を処理できない場合に便利です。Oracle がサポートする精度レベルは、Kafka Connect の論理型がサポートするレベルを超過するため、time.precision.modeconnect に設定すると、データベース列の 少数秒精度 の値が 3 よりも大きい場合に、精度の喪失 生じます。

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

DATE

INT32

org.apache.kafka.connect.data.Date

エポックからの日数を表します。

INTERVAL DAY[(M)] TO SECOND

FLOAT64

io.debezium.time.MicroDuration

毎月平均に 365.25 / 12.0 式を使用する間隔のマイクロ秒数。

INTERVAL YEAR[(M)] TO MONTH

FLOAT64

io.debezium.time.MicroDuration

毎月平均に 365.25 / 12.0 式を使用する間隔のマイクロ秒数。

TIMESTAMP(0 - 3)

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP(4 - 6)

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP(7 - 9)

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP WITH TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

タイムゾーン情報を含むタイムスタンプの文字列表現。

TIMESTAMP WITH LOCAL TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

UTC でのタイムスタンプの文字列表現。

6.4. Debezium と連携する Oracle の設定

Oracle を Debezium Oracle コネクターと使用するように設定するには、以下の手順が必要です。以下の手順は、コンテナーデータベースと少なくとも 1 つのプラグ可能なデータベースと共にマルチテナンシー設定を使用することを前提としています。マルチテナント設定を使用しない場合は、以下の手順を調整する必要がある場合があります。

Vagrant を使用して仮想マシンで Oracle を設定する方法は、Debezium Vagrant Box for Oracle database GitHub リポジトリーを参照してください。

Debezium コネクターと使用するために Oracle を設定する場合の詳細は、以下を参照してください。

6.4.1. Debezium で使用できるように Oracle データベースの準備

Oracle LogMiner に必要な設定

ORACLE_SID=ORACLCDB dbz_oracle sqlplus /nolog

CONNECT sys/top_secret AS SYSDBA
alter system set db_recovery_file_dest_size = 10G;
alter system set db_recovery_file_dest = '/opt/oracle/oradata/recovery_area' scope=spfile;
shutdown immediate
startup mount
alter database archivelog;
alter database open;
-- Should now "Database log mode: Archive Mode"
archive log list

exit;

さらに、データ変更が変更されたデータベース行の before 状態をキャプチャーするには、キャプチャーされたテーブルまたはデータベースに対して補助ロギングを有効にする必要があります。以下は、これを特定の表で設定する方法を示しています。これは、Oracle redo ログにキャプチャーされる情報量を最小限に抑えるのに理想的な選択です。

ALTER TABLE inventory.customers ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;

最小の補助ロギングをデータベースレベルで有効にする必要があります。これは、以下のように設定することができます。

ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;

6.4.2. Debezium Oracle コネクター用の Oracle ユーザーの作成

Debezium Oracle コネクターが変更イベントをキャプチャーするには、特定のパーミッションを持つ Oracle LogMiner ユーザーとして実行する必要があります。以下の例は、マルチテナントデータベースモデルで、コネクターの Oracle ユーザーアカウントを作成するための SQL を示しています。

警告

コネクターは、SYSSYSTEM、またはコネクターユーザーアカウントによって行われるデータベースの変更をキャプチャーしません。

コネクターの LogMiner ユーザーの作成

sqlplus sys/top_secret@//localhost:1521/ORCLCDB as sysdba
  CREATE TABLESPACE logminer_tbs DATAFILE '/opt/oracle/oradata/ORCLCDB/logminer_tbs.dbf'
    SIZE 25M REUSE AUTOEXTEND ON MAXSIZE UNLIMITED;
  exit;

sqlplus sys/top_secret@//localhost:1521/ORCLPDB1 as sysdba
  CREATE TABLESPACE logminer_tbs DATAFILE '/opt/oracle/oradata/ORCLCDB/ORCLPDB1/logminer_tbs.dbf'
    SIZE 25M REUSE AUTOEXTEND ON MAXSIZE UNLIMITED;
  exit;

sqlplus sys/top_secret@//localhost:1521/ORCLCDB as sysdba

  CREATE USER c##dbzuser IDENTIFIED BY dbz
    DEFAULT TABLESPACE logminer_tbs
    QUOTA UNLIMITED ON logminer_tbs
    CONTAINER=ALL;

  GRANT CREATE SESSION TO c##dbzuser CONTAINER=ALL;
  GRANT SET CONTAINER TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$DATABASE to c##dbzuser CONTAINER=ALL;
  GRANT FLASHBACK ANY TABLE TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ANY TABLE TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT_CATALOG_ROLE TO c##dbzuser CONTAINER=ALL;
  GRANT EXECUTE_CATALOG_ROLE TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ANY TRANSACTION TO c##dbzuser CONTAINER=ALL;
  GRANT LOGMINING TO c##dbzuser CONTAINER=ALL;

  GRANT CREATE TABLE TO c##dbzuser CONTAINER=ALL;
  GRANT LOCK ANY TABLE TO c##dbzuser CONTAINER=ALL;
  GRANT ALTER ANY TABLE TO c##dbzuser CONTAINER=ALL;
  GRANT CREATE SEQUENCE TO c##dbzuser CONTAINER=ALL;

  GRANT EXECUTE ON DBMS_LOGMNR TO c##dbzuser CONTAINER=ALL;
  GRANT EXECUTE ON DBMS_LOGMNR_D TO c##dbzuser CONTAINER=ALL;

  GRANT SELECT ON V_$LOG TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$LOG_HISTORY TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$LOGMNR_LOGS TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$LOGMNR_CONTENTS TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$LOGMNR_PARAMETERS TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$LOGFILE TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$ARCHIVED_LOG TO c##dbzuser CONTAINER=ALL;
  GRANT SELECT ON V_$ARCHIVE_DEST_STATUS TO c##dbzuser CONTAINER=ALL;

  exit;

6.5. Debezium Oracle コネクターのデプロイ

Debezium Oracle コネクターをデプロイするには、コネクターファイルを Kafka Connect に追加し、コネクターを実行するカスタムコンテナーを作成して、続いてコネクター設定をコンテナーに追加します。Debezium Oracle コネクターのデプロイに関する詳細は、以下を参照してください。

6.5.1. Oracle JDBC ドライバーの取得

Debezium Oracle コネクターには、Oracle データベースに接続するための Oracle JDBC ドライバー (ojdbc8.jar) が必要です。ライセンス要件により、必要なドライバーファイルは Debezium Oracle コネクターアーカイブには含まれていません。必要なドライバーファイルを Oracle から直接ダウンロードし、Kafka Connect 環境に追加する必要があります。以下の手順では、Oracle Instant Client をダウンロードし、ドライバーを抽出する方法を説明します。

手順

  1. ブラウザーから、お使いのオペレーティングシステム用の Oracle Instant Client パッケージ をダウンロードします。
  2. アーカイブを展開してから、instantclient_<version> ディレクトリーを開きます。

    以下に例を示します。

    instantclient_21_1/
    ├── adrci
    ├── BASIC_LITE_LICENSE
    ├── BASIC_LITE_README
    ├── genezi
    ├── libclntshcore.so -> libclntshcore.so.21.1
    ├── libclntshcore.so.12.1 -> libclntshcore.so.21.1
    
    ...
    
    ├── ojdbc8.jar
    ├── ucp.jar
    ├── uidrvci
    └── xstreams.jar
    Copy the `ojdbc8.jar` file to the `_<kafka_home>_/libs` directory.

6.5.2. Debezium Oracle コネクターのデプロイ

Debezium Oracle コネクターをデプロイするには、Debezium コネクターアーカイブが含まれるカスタム Kafka Connect コンテナーイメージをビルドし、続いてこのコンテナーイメージをコンテナーレジストリーにプッシュする必要があります。その後、以下のカスタムリソース (CR) を作成する必要があります。

  • Kafka Connect インスタンスを定義する KafkaConnect CR。CR の image プロパティーは、Debezium コネクターを実行するために作成するコンテナーイメージの名前を指定します。この CR を、Red Hat AMQ Streams がデプロイされている OpenShift インスタンスに適用します。AMQ Streams は、Apache Kafka を OpenShift に取り入れる Operator およびイメージを提供します。
  • Debezium Oracle コネクターを定義する KafkaConnector CR。この CR を KafkaConnect CR を適用するのと同じ OpenShift インスタンスに適用します。

    .Prerequisites
  • Oracle Database が稼働状態にあり、Debezium コネクターと連携するように Oracle を設定する 手順を完了している必要があります。
  • AMQ Streams が OpenShift にデプロイされ、Apache Kafka および Kafka Connect を実行している。詳細は、『Deploying and Upgrading AMQ Streams on OpenShift』を参照してください。
  • Podman または Docker がインストールされている。
  • Debezium コネクターを実行するコンテナーを追加する予定のコンテナーレジストリー (quay.iodocker.io など) でコンテナーを作成および管理するアカウントとパーミッションを持っている。
  • Oracle JDBC ドライバーのコピーがある。ライセンス要件により、Debezium Oracle コネクターには必要な JDBC ドライバーファイルが含まれていません。

    詳細は、「Oracle JDBC ドライバーの取得」を参照してください。

手順

  1. Kafka Connect の Debezium Oracle コンテナーを作成します。

    1. Debezium Oracle コネクターアーカイブ をダウンロードします。
    2. Debezium Oracle コネクターアーカイブを展開して、コネクタープラグインのディレクトリー構造を作成します。以下に例を示します。

      ./my-plugins/
      ├── debezium-connector-oracle
      │   ├── ...
    3. registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0 をベースイメージとして使用する Dockerfile を作成します。たとえば、ターミナルウィンドウに以下を入力し、my-plugins をプラグインディレクトリーの名前に置き換えます。

      cat <<EOF >debezium-container-for-oracle.yaml 1
      FROM registry.redhat.io/amq7/amq-streams-kafka-28-rhel8:1.8.0
      USER root:root
      COPY ./<my-plugins>/ /opt/kafka/plugins/ 2
      USER 1001
      EOF
      1 1 1
      任意のファイル名を指定できます。
      2 2 2
      my-plugins をプラグインディレクトリーの名前に置き換えます。

      このコマンドは、現在のディレクトリーに debezium-container-for-oracle.yaml という名前の Docker ファイルを作成します。

    4. 前のステップで作成した debezium-container-for-oracle.yaml Docker ファイルからコンテナーイメージをビルドします。ファイルを含むディレクトリーから、ターミナルウィンドウを開き、以下のコマンドのいずれかを入力します。

      podman build -t debezium-container-for-oracle:latest .
      docker build -t debezium-container-for-oracle:latest .

      上記のコマンドは、debezium-container-for-oracle という名前のコンテナーイメージをビルドします。

    5. カスタムイメージを quay.io などのコンテナーレジストリーまたは内部のコンテナーレジストリーにプッシュします。コンテナーレジストリーは、イメージをデプロイする OpenShift インスタンスで利用できる必要があります。以下のいずれかのコマンドを実行します。

      podman push <myregistry.io>/debezium-container-for-oracle:latest
      docker push <myregistry.io>/debezium-container-for-oracle:latest
    6. 新しい Debezium Oracle KafkaConnect カスタムリソース (CR) を作成します。たとえば、以下の例のように、annotations および image プロパティーを指定する dbz-connect.yaml という名前の KafkaConnect CR を作成します。

      apiVersion: kafka.strimzi.io/v1beta2
      kind: KafkaConnect
      metadata:
        name: my-connect-cluster
        annotations:
          strimzi.io/use-connector-resources: "true" 1
      spec:
        #...
        image: debezium-container-for-oracle  2
      1
      KafkaConnector リソースはこの Kafka Connect クラスターでコネクターを設定するために使用されることを、metadata.annotations は Cluster Operator に示します。
      2
      spec.image は Debezium コネクターを実行するために作成したイメージの名前を指定します。このプロパティーによって Cluster Operator の STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 変数がオーバーライドされます。
    7. 以下のコマンドを入力して、KafkaConnect CR を OpenShift Kafka Connect 環境に適用します。

      oc create -f dbz-connect.yaml

      このコマンドは、Debezium コネクターを実行するために作成したイメージの名前を指定する Kafka Connect インスタンスを追加します。

  2. Debezium Oracle コネクターインスタンスを設定する KafkaConnector カスタムリソースを作成します。

    コネクターの設定プロパティーを指定する .yaml ファイルで Debezium Oracle コネクターを設定します。コネクター設定は、Debezium に対して、スキーマおよびテーブルのサブセットにイベントを生成するよう指示する可能性があり、または機密性の高い、大きすぎる、または不必要な指定のコラムで Debezium が値を無視、マスク、または切り捨てするようにプロパティーを設定する可能性もあります。

    以下の例では、ポート 1521 で Oracle ホスト IP アドレスに接続する Debezium コネクターを設定します。このホストには ORCLCDB という名前のデータベースがあり、server1 はサーバーの論理名です。

    Oracle inventory-connector.yaml

    apiVersion: kafka.strimzi.io/v1beta2
    kind: KafkaConnector
    metadata:
      name: inventory-connector 1
      labels:
        strimzi.io/cluster: my-connect-cluster
      annotations:
        strimzi.io/use-connector-resources: 'true'
    spec:
      class: io.debezium.connector.oracle.OracleConnector 2
      config:
        database.hostname: <oracle_ip_address> 3
        database.port: 1521 4
        database.user: c##dbzuser 5
        database.password: dbz 6
        database.dbname: ORCLCDB 7
        database.pdb.name : ORCLPDB1, 8
        database.server.name: server1 9
        database.history.kafka.bootstrap.servers: kafka:9092 10
        database.history.kafka.topic: schema-changes.inventory 11

    表6.6 コネクター設定の説明

    項目説明

    1

    Kafka Connect サービスに登録する場合のコネクターの名前。

    2

    この Oracle コネクタークラスの名前。

    3

    Oracle インスタンスのアドレス。

    4

    Oracle インスタンスのポート番号。

    5

    コネクターのユーザーの作成」で指定した Oracle ユーザーの名前。

    6

    コネクターのユーザーの作成」で指定した Oracle ユーザーのパスワード。

    7

    変更をキャプチャーするデータベースの名前。

    8

    コネクターが変更をキャプチャーする Oracle のプラグ可能なデータベースの名前。コンテナーデータベース (CDB) のインストールでのみ使用されます。

    9

    コネクターが変更をキャプチャーする Oracle データベースサーバーの namespace を識別および提供する論理名。

    10

    DDL ステートメントをデータベース履歴トピックに書き込み、復元するためにコネクターによって使用される Kafka ブローカーのリスト。

    11

    コネクターが DDL ステートメントを書き、復元するデータベース履歴トピックの名前。このトピックは内部使用のみを目的としており、コンシューマーが使用しないようにしてください。

  3. Kafka Connect でコネクターインスタンスを作成します。たとえば、KafkaConnector リソースを inventory-connector.yaml ファイルに保存した場合は、以下のコマンドを実行します。

    oc apply -f inventory-connector.yaml

    上記のコマンドにより inventory-connector が登録され、コネクターは KafkaConnector CR で定義された server1 データベースに対して実行を開始します。

  4. コネクターが作成され、起動されたことを確認します。

    1. Kafka Connect ログ出力を表示して、コネクターが作成され、指定データベースの変更のキャプチャーが開始されたことを確認します。

      oc logs $(oc get pods -o name -l strimzi.io/cluster=my-connect-cluster)
    2. ログの出力を確認し、Debezium が初回のスナップショットを実行することを確認します。ログには、以下のメッセージと同様の出力が表示されます。

      ... INFO Starting snapshot for ...
      ... INFO Snapshot is using user 'c##dbzuser' ...

      コネクターがエラーがなく正常に起動すると、コネクターが変更をキャプチャーする各テーブルのトピックが作成されます。ダウンストリームアプリケーションは、これらのトピックをサブスクライブできます。

    3. 以下のコマンドを実行して、コネクターによってトピックが作成されたことを検証します。

      oc get kafkatopics

Debezium Oracle コネクターに設定できる設定プロパティーの完全リストは、「Oracle コネクタープロパティー」を参照してください。

結果

コネクターが起動すると、コネクターが設定された Oracle データベースの 整合性スナップショットが実行 されます。その後、コネクターは行レベルの操作のデータ変更イベントの生成を開始し、変更イベントレコードを Kafka トピックにストリーミングします。

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

Debezium Oracle コネクターには、アプリケーションに適したコネクター動作を実現するために使用できる設定プロパティーが多数あります。多くのプロパティーにはデフォルト値があります。プロパティーに関する情報は、以下のように構成されています。

必要な 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

デフォルトなし

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

database.pdb.name

デフォルトなし

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

database.server.name

デフォルトなし

コネクターが変更をキャプチャーする Oracle データベースサーバーの namespace を識別および提供する論理名。設定した値は、コネクターが出力するすべての Kafka トピック名のプレフィックスとして使用されます。Debezium 環境のすべてのコネクターで一意となる論理名を指定します。英数字、ハイフン、およびアンダースコアが有効な文字です。

database.connection.adapter

logminer

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

logminer (デフォルト)
コネクターはネイティブの Oracle LogMiner API を使用します。
xstream
コネクターは Oracle XStreams API を使用します。

snapshot.mode

Initial

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

initial
スナップショットには、キャプチャーされたテーブルの構造およびデータが含まれます。この値を指定して、キャプチャーされたテーブルからのデータの完全な表現でトピックを設定します。
schema_only
スナップショットには、キャプチャーされたテーブルの構造だけが含まれます。スナップショット後に発生する変更に対してのみ、コネクターにデータを取得させる場合は、この値を指定します。

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

snapshot.select.statement.overrides

デフォルトなし

スナップショットに含めるテーブル行を指定します。
このプロパティーには、完全修飾テーブル (<schema_name.table_name>) のコンマ区切りリストが含まれます。各テーブルの select ステートメントは、テーブルごとに 1 つずつ追加の設定プロパティーで指定され、ID snapshot.select.statement.overrides.[<schema_name>].[<table_name>] によって識別されます。これらのプロパティーの値は、スナップショットの実行中に特定のテーブルからデータを取得するときに使用する SELECT ステートメントです。大規模な追加のみのテーブルで可能なユースケースとしては、以前のスナップショットが中断された場合にスナップショットの開始(再開)を開始(再開)します。
注意: この設定は、スナップショットにのみ影響します。ログの読み取り中にコネクターがキャプチャーするイベントには適用されません。

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

デフォルトなし

監視するテーブルの完全修飾テーブル識別子と一致する正規表現の任意のコンマ区切りリスト。包含リストに含まれていないテーブルは、監視から除外されます。各識別子の形式は <schema_name>.<table_name> です。デフォルトでは、コネクターは監視される各データベースのシステム以外のテーブルをすべて監視します。このプロパティーは、table.exclude.list と併用しないでください。LogMiner 実装を使用する場合は、このプロパティーと POSIX 正規表現のみを使用します。

table.exclude.list

デフォルトなし

監視から除外するテーブルの完全修飾テーブル識別子と一致する正規表現の任意のコンマ区切りリスト。コネクターは、除外リストで指定されていないすべてのテーブルから変更イベントをキャプチャーします。<schema_name>.<table_name> 形式を使用して、各テーブルの識別子を指定します。このプロパティーは、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>

デフォルトなし

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

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

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

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

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

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

decimal.handling.mode

precise

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

precise (デフォルト)
バイナリー形式の変更イベントで表される java.math.BigDecimal の値を使用して、値を正確に表します。
double
double 値を使用して値を表します。double の値を使用すると簡単ですが、精度が失われる可能性があります。
string
値をフォーマットされた文字列としてエンコードします。string オプションを使用すると使用が容易になりますが、実際のタイプに関するセマンティック情報が失われる場合があります。詳細は、10 進数型を参照してください。

event.processing.failure.handling.mode

fail

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

fail
例外を伝搬し (問題のあるイベントのオフセットを示す)、コネクターが停止します。
warn
問題のあるイベントがスキップされます。問題のあるイベントのオフセットはログに記録されます。
skip
問題のあるイベントがスキップされます。

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) イベントが続くかどうかを制御します。以下の値を使用できます。

true
削除操作ごとに、コネクターは 削除 イベントと後続の廃棄 (tombstone) イベントを出力します。
false
削除操作ごとに、コネクターは 削除 イベントのみを出力します。

ソースレコードの削除後に廃棄 (tombstone) イベントを出力すると (デフォルト動作)、Kafka は ログコンパクション が有効なトピックの削除された行のキーを共有するすべてのイベントを完全に削除できます。

message.key.columns

デフォルトなし

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

column.truncate.to.length.chars

デフォルトなし

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

column.mask.with.length.chars

デフォルトなし

文字をアスタリスク (*) に置き換えて、変更イベントメッセージの列名をマスクする正規表現のコンマ区切りリスト (任意)。プロパティーの名前で置き換える文字の数を指定します (例: column.mask.with.8.chars)。長さを正の整数またはゼロとして指定します。次に、マスクを適用する各文字ベースの列名についてリストに正規表現を追加します。pdbName.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 固有のデータ型名のリスト」を参照してください。