サポートコンソール開発者トライアルの開始お問い合わせ

Debezium ユーザーガイド

Preface

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

本ガイドでは、Debezium コネクターの使用について説明します。

第1章 Debezium の概要

Debezium は分散サービスのセットで、データベースの変更をキャプチャーします。アプリケーションはこれらの変更を使用し、これに対応できる。Debezium は、変更イベントレコードの各データベーステーブルの各行レベルの変更をキャプチャーし、これらのレコードを Kafka トピックにストリーミングします。アプリケーションはこれらのストリームを読み取り、変更イベントレコードを生成と同じ順序で提供します。

詳細は、以下のセクションを参照してください。

1.1. Debezium の機能

Debezium は Apache Kafka Connect のソースコネクターのセットで、Changes Data capture(CDC)を使用して異なるデータベースからの変更をサンプリングします。ポーリングやデュアル書き込みなどの他のアプローチとは異なり、Debezium が実装するログベースは以下のようになります。

  • すべてのデータの変更がキャプチャーされるようにする
  • 遅延が非常に低い 変更イベント（例： MySQL または Postgres のミリ秒範囲）を生成する一方で、ポーリングが頻繁に行われる CPU の使用量を増やすのを回避します。
  • データモデルの変更を必要としません（ 「最後の更新」の列など）。
  • 取得が削除可能
  • トランザクション ID などの 古いレコードの状態やメタデータをキャプチャー してクエリーの原因（データベースのケイパビリティーや設定により）をキャプチャーできます。

ログベースのフォントの利点の詳細は、このブログ投稿 を参照してください。

Debezium の実際の変更データキャプチャー機能は、関連する機能およびオプションの範囲で変更されます。

  • スナップショット： オプションで、コネクターが起動し、すべてのログが存在している場合には、データベースの初期スナップショットを取得でき（通常は、データベースがしばらく実行され、トランザクションリカバリーまたはレプリケーションに必要でないトランザクションログを破棄した場合など）。スナップショット用の異なるモードは、スナップショット用として存在します。詳細は確認するために使用する特定のコネクターのドキュメントを参照してください。
  • フィルター - 取得されたスキーマ、テーブル、および列のセットはホワイトリスト/ブラックリストフィルターを使用して設定できます。
  • マスク - 特定の列の値（機密データなど） はマスクできます。
  • 監視： ほとんどのコネクターは JMX を使用して監視できます。
  • 利用できる メッセージ変換： メッセージ ルーティング の場合、新しいレコード状態（リレーショナルコネクター、MongoDB）の抽出、トランザクションアウトボックステーブルから のイベントのルーティング など。

サポートされるすべてのデータベースのリストや、各 コネクターの機能および設定オプションの詳細情報は、コネクターのドキュメント を参照してください。

1.2. Debezium アーキテクチャー

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

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

以下の図は、Debezium に基づいた変更データキャプチャーパイプラインのアーキテクチャーを示しています。

Debezium アーキテクチャー

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

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

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

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

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

変更イベントレコードが Apache Kafka にある後に、Kafka Connect の eco-system の異なるコネクターは、Elasticsearch、データ拒否、解析システム、Infinispan などのキャッシュなどの他のシステムやデータベースにレコードをストリーミングできます。選択したシンクコネクターによっては、Debezium の 新しいレコード状態抽出 変換の設定が必要になる場合があります。この Kafka Connect SMT は、Debezium の変更イベントからシンクコネクターに after 構造を伝播します。これは、デフォルトで伝播される詳細変更イベントレコードの代わりに使用されます。

第2章 MySQL 用 Debezium コネクター

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

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

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

2.1. MySQL コネクターの仕組みの概要

Debezium MySQL コネクターはテーブルの構造を追跡し、スナップショットを実行し、binlog イベントを Debezium 変更イベント、Kafka に記録されるレコードに変換します。

2.1.1. MySQL コネクターがデータベーススキーマを使用する方法

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

これを処理するため、MySQL は binlog にデータへの行レベルの変更と、データベースに適用される DDL ステートメントが含まれます。コネクターが binlog を読み取り、これらの DDL ステートメントを渡すと、それらを解析して各テーブルのスキーマのメモリー内表現を更新します。コネクターはこのスキーマ表現を使用して、それぞれの挿入、更新、または削除時にテーブルの構造を特定し、適切な変更イベントを生成します。コネクターは、個別のデータベース履歴 Kafka トピックで、各 DDL ステートメントが表示される binlog の位置とともにすべての DDL ステートメントを記録します。

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

このデータベース履歴トピックは、コネクターが使用するためにのみ使用されます。コネクターは任意で、コンシューマーアプリケーション向けの異なるトピックでスキーマ変更イベントを生成できます。これは、MySQL コネクターがスキーマ変更トピックを処理する方法 に説明されています。

MySQL コネクターが、gh-ost やなどのスキーマ変更ツールの変更をキャプチャーする際に、移行プロセス中に作成 pt-online-schema-change されたヘルパーテーブルをホワイトリストのテーブルに含める必要があります。

ダウンストリームシステムでは、一時テーブルによって生成されたメッセージが必要ない場合は、単純なメッセージ変換を書き込んで適用して、それらをフィルターすることができます。

トピックの命名規則の詳細は、「 MySQL コネクターおよび Kafka トピック 」を参照してください。

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

Debezium MySQL コネクターが最初に起動すると、データベースの初期 一貫性のあるスナップショット を実行します。以下のフローは、このスナップショットがどのように完了するかを説明します。

注記

これは、snapshot.mode プロパティー initial でとして設定されるデフォルトのスナップショットモードです。他のスナップショットモードについては、MySQL コネクター設定プロパティー をご確認ください。

コネクター
手順アクション

1

他のデータベースクライアントによる 書き込み をブロックする グローバル読み取りロック を取得します。

注記

このスナップショット自体は、binlog の位置とテーブルスキーマの読み取りの試行に干渉する可能性がある他のクライアントが DDL を適用できないようにする訳ではありません。グローバル読み取りロックは、後でリリースされる前に binlog の位置が読み込まれる間に保持されます。

2

繰り返し可能な読み取りセマンティクス でトランザクションを開始し、トランザクション内のすべての後続の読み取りが 一貫したスナップショット に対して実行されるようにします。

3

現在の binlog 位置を読み取ります。

4

コネクターの設定によって許可されるデータベースおよびテーブルのスキーマを読み取ります。

5

グローバル読み取りロック を解放します。これにより、他のデータベースクライアントがデータベースに書き込むことができるようになります。

6

必要なすべての CREATE…​ ステートメントを含む DDL 変更をスキーマ変更トピック DROP…​ に書き込みます。

注記

これは該当する場合に発生します。

7

データベーステーブルをスキャンし、各行に関連するテーブル固有の Kafka トピックで CREATE イベントを生成します。

8

トランザクションをコミットします。

9

コネクターオフセットで完了したスナップショットを記録します。

2.1.2.1. コネクターが失敗した場合、どうなりますか？

初期のスナップショット 作成中にコネクターが失敗するか、停止するか、またはリバランスされると、コネクターは再起動後に新しいスナップショットを作成します。意図しない スナップショット が完了すると、Debezium MySQL コネクターは binlog 内の同じ位置から再起動するため、更新が失われないようにします。

注記

コネクターが長い期間停止すると、MySQL は古い binlog ファイルをパージする可能性があり、コネクターの位置は失われます。位置が失われた場合、コネクターは開始位置のために 最初のスナップショット に戻ります。Debezium MySQL コネクターのトラブルシューティングに関する詳細は、「 MySQL connector common issues 」を参照してください。

2.1.2.2. グローバル読み取りロックが許可されていない場合は？

一部の環境では、グローバル読み取りロック が許可されない場合があります。Debezium MySQL コネクターがグローバル読み取りロックが許可されないことを検出すると、コネクターは代わりにテーブルレベルのロックを使用して、この方法でスナップショットを実行します。

重要

ユーザーには LOCK_TABLES 権限が必要です。

コネクター
手順アクション

1

繰り返し可能な読み取りセマンティクス でトランザクションを開始し、トランザクション内のすべての後続の読み取りが 一貫したスナップショット に対して実行されるようにします。

2

データベースおよびテーブルの名前を読み取り、フィルタリングします。

3

現在の binlog 位置を読み取ります。

4

コネクターの設定によって許可されるデータベースおよびテーブルのスキーマを読み取ります。

5

必要なすべての CREATE…​ ステートメントを含む DDL 変更をスキーマ変更トピック DROP…​ に書き込みます。

注記

これは該当する場合に発生します。

6

データベーステーブルをスキャンし、各行に関連するテーブル固有の Kafka トピックで CREATE イベントを生成します。

7

トランザクションをコミットします。

8

テーブルレベルのロックを解放します。

9

コネクターオフセットで完了したスナップショットを記録します。

2.1.3. MySQL コネクターによるスキーマ変更のトピックの処理方法

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

重要

スキーマ変更イベント の使用を選択した場合は、スキーマ変更トピックを使用し、データベースの履歴トピックは使用し ない でください。

注記

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

2.1.3.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_sec"
          },
          {
            "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": "0.10.0.Beta4",
      "name": "mysql-server-1",
      "server_id": 0,
      "ts_sec": 0,
      "gtid": null,
      "file": "mysql-bin.000003",
      "pos": 154,
      "row": 0,
      "snapshot": true,
      "thread": null,
      "db": null,
      "table": null,
      "query": null
    }
  }
}
2.1.3.1.1. スキーマ変更のトピックに関する重要なヒント

この ddl フィールドには複数の DDL ステートメントを含めることができます。すべてのステートメントは databaseName フィールドのデータベースに適用され、データベースで適用された順序と同じ順序で表示されます。source フィールドは、テーブル固有のトピックに書き込まれた標準データ変更イベントとして構成されます。このフィールドは、異なるトピックでイベントを関連付けるのに役立ちます。 

....
    "payload": {
        "databaseName": "inventory",
        "ddl": "CREATE TABLE products ( id INTEGER NOT NULL AUTO_INCREMENT PRIMARY KEY,...
        "source" : {
            ....
        }
    }
....
クライアントが 複数のデータベースに DDL ステートメントを送信する場合はどうすればよいです か？
  • MySQL がアトミックに適用される場合、コネクターは DDL ステートメントを順番に取得し、データベースを基にグループ化し、各グループのスキーマ変更イベントを作成します。
  • MySQL が個別に適用される場合、コネクターはステートメントごとに個別のスキーマ変更イベントを作成します。

関連情報

2.1.4. MySQL コネクターイベント

Debezium MySQL コネクターによって生成されたすべてのデータ変更イベントには、キーと値が含まれます。変更イベントキーおよび変更イベント値には、スキーマ とペイロードの構造がスキーマと ペイロード が含まれ、ペイロードにはデータが含まれます。

警告

MySQL コネクターは、すべての Kafka Connect スキーマ名が Avro スキーマ名の形式 に準拠するようにします。これは、ラピン文字やアンダースコアではない文字がアンダースコアに置き換えられているため、論理サーバー名、データベース名、およびテーブル名のコンテナー名がこれらのアンダースコアに置き換えられると予期せぬ競合が生じる可能性があります。

2.1.4.1. Change イベントキー

変更イベントのキーには、イベントの作成時にの PRIMARY KEY （または一意の制約）内の各列のフィールドが含まれる構造があります。例のテーブルとテーブルのスキーマとペイロードがどのように表示されるかを見てみましょう。

テーブルの例

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;

変更イベントキーの例

{
 "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
  }
}

1
は内の内容を schema 説明し payloadます。
2
mysql-server-1.inventory.customers.Key は、がコネクター名で、がデータベースで、が表 mysql-server-1 で inventory ある構造を定義するスキーマの名前 customers です。
3
はオプションで payload はないことを示します。
4
で想定されるフィールドのタイプを指定し payloadます。
5
ペイロード自体（この場合は 1 つの id フィールドのみ）。

このキー inventory.customers は、プライマリーキーコラムに値がであるコネクターの外部に mysql-server-1 id ある行を記述し 1001ます。

2.1.4.2. イベント値の変更

変更イベントの値には、スキーマとペイロードセクションが含まれます。変更イベント値には、3 つのタイプのイベント構造があります。この構造のフィールドは以下で説明され、各変更イベント値の例でマークされます。

確認項目フィールド名説明

1

name

mysql-server-1.inventory.customers.Key は、コネクター名、がデータベースで、がテーブルで mysql-server-1 ある構造を定義 inventory するスキーマの名前 customers です。

2

op

操作のタイプを記述する 必須 の文字列。

値

  • c = create
  • u = 更新
  • d = DELETE
  • r 読み取り（初期スナップショット のみ）

3

before

イベント発生前の行の状態を指定するオプションのフィールド。

4

after

イベント発生後の行の状態を指定するオプションのフィールド。

5

source

以下を含む、イベントのソースメタデータを記述する 必須 フィールドです。

  • Debezium のバージョン
  • コネクター名
  • イベントが記録された binlog 名
  • binlog の位置
  • イベント内の行
  • イベントがスナップショットの一部であった場合
  • 影響を受けるデータベースおよびテーブルの名前
  • イベントを作成する MySQL スレッドの ID（スナップショットのみ）
  • MySQL サーバー ID（利用可能な場合）
  • timestamp
注記

binlog _rows_query_log_events オプションが有効で、コネクターで include.query オプションが有効な場合、イベントを生成した元の SQL ステートメントが含まれる query フィールドが表示されます。

6

ts_ms

コネクターがイベントを処理した時間を表示するオプションのフィールド。

注記

この時間は、Kafka Connect タスクを実行している JVM のシステムクロックに基づいています。

例のテーブルとテーブルのスキーマとペイロードがどのように表示されるかを見てみましょう。

テーブルの例

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;

2.1.4.2.1. イベント値の変更の作成

以下の例は、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",
        "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.product.connector.mysql.Source",
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "mysql-server-1.inventory.customers.Envelope"
  },
  "payload": { 2
    "op": "c",
    "ts_ms": 1465491411815,
    "before": null,
    "after": {
      "id": 1004,
      "first_name": "Anne",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "source": {
      "version": "1.1.2.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')"
    }
  }
}
1
このイベントの 値 の schema 一部は、オペレーションのスキーマ、ソース構造のスキーマ（MySQL コネクターに固有で、すべてのイベントで再利用される）、before および after フィールドのテーブル固有のスキーマを示します。
2
このイベントの 値 の payload 一部には、イベント内の情報が表示され、これは行が作成されたことを記述していること（原因 op=c）、および after フィールドに新たに挿入された行、、id first_name last_name、および email 列の値が含まれます。
2.1.4.2.2. Update change event value

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.1.2.Final",
      "name": "mysql-server-1",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 1465581,
      "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
  }
}

これと 挿入 イベントの値を比較すると、payload セクションにいくつかの違いを確認できます。

1
この before フィールドには、データベースのコミットの前に値が含まれる行の状態が含まれるようになりました。
2
after フィールドは行の更新された状態となり、first_name 値はになりまし Anne Marieた。before と after 構造を比較して、コミットが原因でこの行で実際に何が変更されているかを判断できます。
3
source フィールド構造は以前と同じフィールドを持ちますが、値は異なります（このイベントは binlog の別の位置にあります）。source 構造は、この変更の MySQL の記録に関する情報を表示します（トレース可能性の向上）。また、このイベントや他のトピックの他のイベントと比較し、このイベントが他のイベントとして同じ MySQL コミットの前、後、またはの一部として実行されたかどうかを確認するためにも使用できます。
4
これで op フィールド値はになり u、更新によりこの行が変更されていることを確認できます。
5
この ts_ms フィールドは、Debezium がこのイベントを処理したときにタイムスタンプを表示します。
注記

行のプライマリーキーまたは一意の鍵の列が更新され、Debezium は行のキーが変更され、Debezium は DELETE イベントと行の古いキーを持つ tombstone イベントを出力し、その後の行の新しいキーを含む INSERT イベントを出力します。

2.1.4.2.3. Delete change event value（変更イベント値の削除）

customers テーブルの delete 変更イベントの値は、作成 および 更新 イベントと全く同じスキーマを持ちます。ペイロードは同じですが、異なる値を保持します。以下に例を示します（読みやすさを考慮したフォーマット）。 

{
  "schema": { ... },
  "payload": {
    "before": { 1
      "id": 1004,
      "first_name": "Anne Marie",
      "last_name": "Kretchmar",
      "email": "annek@noanswer.org"
    },
    "after": null, 2
    "source": { 3
      "version": "1.1.2.Final",
      "connector": "mysql",
      "name": "mysql-server-1",
      "ts_ms": 1465581,
      "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
  }
}

作成 および 更新 イベントのペイロードと payload 部分を比較すると、いくつかの違いを確認できます。

1
この before フィールドには、データベースのコミットで削除された行の状態が表示されます。
2
after フィールドは null、行が存在しなくなったことを表しています。
3
source フィールド構造には、ts_sec および pos フィールドが変更された場合を除き、（他のシナリオでファイルが変更された可能性がありました）、以前と同じ値の多くがあります。
4
op フィールド値はになり d、この行が削除されたことを表しています。
5
は ts_ms、Debezium がこのイベントを処理したときにタイムスタンプを表示します。

このイベントは、この行の削除を処理するために必要な情報をコンシューマーに提供します。一部のコンシューマーでは削除を適切に処理するために必要なため、古い値が含まれます。

MySQL コネクターのイベントは、Kafka ログの圧縮 と連携するように設計されています。これにより、すべてのキーの少なくとも最新のメッセージが保持されていれば、古いメッセージを削除することができます。これにより、Kafka はストレージ領域を回収でき、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できます。

行が削除されても、上記の delete イベント値はログの圧縮で機能します。これは、Kafka はその鍵を使用して以前のメッセージをすべて削除できるためです。message 値がの場合 null、Kafka は同じキーを持つすべてのメッセージを削除できることを認識します。これを可能にするため、Debezium の MySQL コネクターは、常に同じキーではなく null 値を持つ特別な tombstone イベントを持つ 削除 イベントにしたがいます。

2.1.5. MySQL コネクターがデータタイプをマップする方法

Debezium MySQL コネクターは、行が存在するテーブルのように構造化されたイベントを持つ行への変更を表します。イベントには、各列値のフィールドが含まれます。その列の MySQL データタイプは、値をイベントでどのように表すかを決定します。

文字列を保存する列は、文字セットと照合で MySQL で定義されます。MySQL コネクターは、binlog イベント内の列値のバイナリー表現を読み取るときに、列の文字セットを使用します。以下の表は、コネクターが MySQL データタイプを リテラル タイプとセマンティクスタイプの両方にマップする方法を示し て います。

  • literal タイプ : Kafka Connect スキーマタイプを使用して値がどのように表されるか
  • semantic type : Kafka Connect スキーマがフィールドの意味をキャプチャーする方法（スキーマ名）
MySQL タイプリテラルタイプセマンティクスタイプ

BOOLEAN, BOOL

BOOLEAN

該当なし

BIT(1)

BOOLEAN

該当なし

BIT(>1)

BYTES

io.debezium.data.Bits

注記

length schema パラメーターには、ビット数を表す整数が含まれます。には little-endian 形式のビットが 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

該当なし

VARBINARY(M)]

BYTES

該当なし

TINYBLOB

BYTES

該当なし

TINYTEXT

STRING

該当なし

BLOB

BYTES

該当なし

TEXT

STRING

該当なし

MEDIUMBLOB

BYTES

該当なし

MEDIUMTEXT

STRING

該当なし

LONGBLOB

BYTES

該当なし

LONGTEXT

STRING

該当なし

JSON

STRING

io.debezium.data.Json

注記

JSON ドキュメント、配列、またはスカラーの文字列表現が含まれます。

ENUM

STRING

io.debezium.data.Enum

注記

allowed schema パラメーターには、許可される値のコンマ区切りリストが含まれます。

SET

STRING

io.debezium.data.EnumSet

注記

allowed schema パラメーターには、許可される値のコンマ区切りリストが含まれます。

YEAR[(2|4)]

INT32

io.debezium.time.Year

TIMESTAMP[(M)]

STRING

io.debezium.time.ZonedTimestamp

注記

ISO 8601 形式（マイクロ秒の精度）MySQL では M、の範囲を使用でき 0-6ます。

2.1.5.1. 一時的な値

TIMESTAMP データタイプを除外する MySQL の一時タイプは、time.precision.mode 設定プロパティーの値によって異なります。デフォルト値は CURRENT_TIMESTAMP or として指定された TIMESTAMP 列の場合 NOW、値 1970-01-01 00:00:00 は Kafka Connect スキーマのデフォルト値として使用されます。

MySQL は、ゼロ値が null 値よりも優先されるため DATE, `DATETIME、、および TIMESTAMP 列の値にゼロ/値を許可します。MySQL コネクターは、列定義が null 値を許可する場合は null 値、またはコラムが null 値を許可しない場合はエポック日としてゼロ値を表します。

タイムゾーンのない一時的な値

DATETIME タイプは、「2018-01-13 09:48:27」などのローカル日時を表します。ご覧のとおり、タイムゾーンの情報はありません。このような列は、UTC を使用して列の精度に基づいてエポックミリ秒またはマイクロ秒に変換されます。TIMESTAMP タイプはタイムゾーン情報がないタイムスタンプを表し、値を書き込む際にサーバー（またはセッションの）タイムゾーンから UTC へ MySQL により変換されます。以下に例を示します。

  • DATETIME の値が 2018-06-20 06:37:03 になり 1529476623000ます。
  • TIMESTAMP の値が 2018-06-20 06:37:03 になり 2018-06-20T13:37:03Zます。

このような列は、サーバー（またはセッション）の現在のタイムゾーンを基に UTC io.debezium.time.ZonedTimestamp で同等の形式に変換されます。デフォルトでは、タイムゾーンはサーバーからクエリーされます。これに失敗する場合、database.serverTimezone コネクター設定プロパティーによって明示的に指定する必要があります。たとえば、データベースのタイムゾーン（グローバルで、またはでコネクターに設定されている場合 database.serverTimezone property）が「America/Los_Angeles」である場合、TIMESTAMP の値「2018-06-20 06:37:03」は「2018-06-20T13:37:03Z」の ZonedTimestamp 値で表されます。

Kafka Connect および Debezium を実行している JVM のタイムゾーンはこれらの変換には影響しないことに注意してください。

用語値に関連するプロパティーの詳細は、MySQL コネクター設定プロパティー のドキュメントを参照してください。

time.precision.mode=adaptive_time_microseconds(default)

MySQL コネクターは、リテラルタイプとセマンティクスタイプを列のデータタイプ定義に基づいて決定し、イベントがデータベースの正確な値を表すようにします。すべての時間フィールドはマイクロ秒単位です。の範囲 TIME にある正の値のみ 00:00:00.000000 を正しくキャプチャー 23:59:59.999999 できます。

MySQL タイプリテラルタイプセマンティクスタイプ

DATE

INT32

io.debezium.time.Date

注記

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

TIME[(M)]

INT64

io.debezium.time.MicroTime

注記

タイムゾーン情報が含まれ、時間の値をマイクロ秒単位で表します。MySQL では M、の範囲を使用でき 0-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ます。を処理 23:59:59.999 できるのは 00:00:00.000 の値だけです。テーブルの TIME 値がサポートされる範囲を超えない場合に time.precision.mode=connect のみ設定します。この connect 設定は、今後の Debezium で削除される予定です。

MySQL タイプリテラルタイプセマンティクスタイプ

DATE

INT32

org.apache.kafka.connect.data.Date

注記

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

TIME[(M)]

INT64

org.apache.kafka.connect.data.Time

注記

中間からの時間（マイクロ秒単位）を表し、タイムゾーン情報が含まれません。

DATETIME[(M)]

INT64

org.apache.kafka.connect.data.Timestamp

注記

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

== 10 進数値

10 進数はプロパティーを使用して処理され decimal.handling.mode ます。

ヒント

詳細は、「 MySQL コネクター設定プロパティー 」を参照してください。

decimal.handling.mode=precise
MySQL タイプリテラルタイプセマンティクスタイプ

NUMERIC[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

注記

scale schema パラメーターには、押す 10 点の数字を表す整数が含まれます。

DECIMAL[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

注記

scale schema パラメーターには、押す 10 点の数字を表す整数が含まれます。

decimal.handling.mode=double
MySQL タイプリテラルタイプセマンティクスタイプ

NUMERIC[(M[,D])]

FLOAT64

該当なし

DECIMAL[(M[,D])]

FLOAT64

該当なし

decimal.handling.mode=string
MySQL タイプリテラルタイプセマンティクスタイプ

NUMERIC[(M[,D])]

STRING

該当なし

DECIMAL[(M[,D])]

STRING

該当なし

2.1.5.2. ブール値

MySQL は特定の方法で BOOLEAN 値を内部で処理します。BOOLEAN 列は内部的に TINYINT(1) datatype にマッピングされます。テーブルがストリーミング中に作成されると、Debezium が元の DDL を受け取るため、適切な BOOLEAN マッピングを使用します。スナップショットの Debezium が SHOW CREATE TABLE を実行してテーブル定義を取得し、そのテーブル定義が BOOLEAN および TINYINT(1) 列 TINYINT(1) の両方に対して返されます。

その後、Debezium には元のタイプマッピングの取得方法がなく、にマッピングされ TINYINT(1)ます。

設定例を以下に示します。 

converters=boolean
boolean.type=io.debezium.connector.mysql.converters.TinyIntOneToBooleanConverter
boolean.selector=db1.table1.*, db1.table2.column1
2.1.5.3. 重要データタイプ

現在、Debezium MySQL コネクターは以下のデータタイプをサポートします。

MySQL タイプリテラルタイプセマンティクスタイプ

GEOMETRY, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION

STRUCT

io.debezium.data.geometry.Geometry

注記

2 つのフィールドが含まれる構造が含まれています。

  • srid (INT32: 構造に格納されるジオメトリーオブジェクトの種類を定義する強力な参照システム ID
  • wkb (BYTES): raw-Known-Binary(wkb)形式でエンコードされたジオメトリーオブジェクトのバイナリー表現。詳細は、Open Geospatial Consortium を参照してください。

2.1.6. MySQL コネクターおよび Kafka トピック

Debezium MySQL コネクターは INSERT UPDATE、イベントを 1 つの DELETE テーブルから 1 つの Kafka トピックに書き込みます。Kafka トピックの命名規則は以下のとおりです。

format

serverName.databaseName.tableName

例2.1 example

サーバー名で、fulfillment は、、およびの 3 つ のテーブル inventory が含まれるデータベース ordersと customersし productsます。Debezium MySQL コネクターはイベントを 3 つの Kafka トピックに生成し、データベースの各テーブルに対して 1 つずつイベントを生成します。 

fulfillment.inventory.orders

fulfillment.inventory.customers

fulfillment.inventory.products

2.1.7. MySQL がサポートするトポロジー

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

Standalone
単一の MySQL サーバーを使用する場合は、Debezium MySQL コネクターがサーバーをモニターできるように、binlog を有効にする（およびオプションで GTIDs が有効になっている）必要があります。バイナリーログは増分 バックアップ としても使用できるため、これは受け入れ可能です。この場合、MySQL コネクターは常に接続し、このスタンドアロン MySQL サーバーインスタンスに従います。
マスターおよびスレーブ

Debezium MySQL コネクターは、マスターまたはスレーブの 1 つ（そのスレーブで binlog が有効になっている場合）に従うことができますが、コネクターはそのサーバーに表示されるクラスターの変更のみを確認します。一般的に、これはマルチマスタートポロジー以外の問題ではありません。

コネクターは、クラスターの各サーバーで異なるサーバーの binlog の位置を記録します。そのため、コネクターは MySQL サーバーインスタンス 1 つのみに従う必要があります。サーバーが失敗した場合は、コネクターを続行する前に再起動または復元する必要があります。

高可用性クラスター
MySQL には多くの 高可用性 ソリューションが存在します。そのため、問題や障害からほぼすぐに復元できます。ほとんどの HA MySQL クラスターは GTID を使用して、スレーブがマスター上のすべての変更を追跡できるようにします。
マルチマスター

マルチマスター MySQL トポロジー は、それぞれが複数のマスターから複製する 1 つ以上の MySQL スレーブを使用します。これは、複数の MySQL クラスターのレプリケーションを集約する強力な方法です。GTID の使用が必要になります。

Debezium MySQL コネクターは、これらのマルチマスター MySQL スレーブをソースとして使用し、w 新規スレーブが古いスレーブにキャッチされていれば、さまざまなマルチマスター MySQL スレーブにフェイルオーバーできます（例： 新しいスレーブは最初のスレーブで最後に確認されたトランザクションをすべて保持します）。コネクターは、新しいマルチマスター MySQL スレーブに再接続して binlog で正しい位置を見つける際に、特定の GTID ソースを include または exclude するように設定できるため、コネクターがデータベースやテーブルのサブセットのみを使用しても機能します。

Hosted

Amazon RDS や Amazon Aurora などのホストオプションを使用するように Debezium MySQL コネクターがサポートされます。

重要

このようなホスト型のオプションでは グローバル読み取りロック が許可されないため、一貫したスナップショット を作成するためにテーブルレベルのロックが使用されます。

2.2. MySQL サーバーの設定

2.2.1. Debezium の MySQL ユーザーの作成

Debezium MySQL コネクターが監視するすべてのデータベースで適切なパーミッションを持つ MySQL ユーザーを定義する必要があります。

前提条件

  • MySQL サーバーが必要です。
  • 基本的な SQL コマンドを知っている必要があります。

手順

  1. MySQL ユーザーを作成します。 
mysql> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
  1. 必要なパーミッションをユーザーに付与します。 
mysql> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';
ヒント

各 パーミッションに記載 されているパーミッションについて参照してください。

重要

グローバル読み取りロックを許可しないホストオプションや Amazon Aurora などのホストオプションを使用している場合、 テーブルレベルのロックを使用して 一貫したスナップショット を作成します。この場合、作成するユーザーに LOCK_TABLES パーミッションを付与する必要もあります。詳細は、「 MySQL コネクターの仕組みの概要 」を参照してください。

  1. ユーザーのパーミッションを確定します。 
mysql> FLUSH PRIVILEGES;
2.2.1.1. 権限の説明
permission/item説明

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'

ユーザーの パスワード を指定します。

2.2.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';
  1. の場合 OFFは、以下のように MySQL サーバー設定ファイルを設定します。
ヒント

各プロパティー に関する情報は「 Binlog 設定プロパティー 」を参照してください。 

server-id         = 223344 1
log_bin           = mysql-bin 2
binlog_format     = ROW 3
binlog_row_image  = FULL 4
expire_logs_days  = 10 5
  1. 再度 binlog ステータスをチェックして変更を確認します。 
mysql> SELECT variable_value as "BINARY LOGGING STATUS (log-bin) ::"
FROM information_schema.global_variables WHERE variable_name='log_bin';
2.2.2.1. Binlog 設定プロパティー
Numberプロパティー説明

1

server-id

の値は、MySQL クラスター内のサーバーおよびレプリケーションクライアントごとに一意である server-id 必要があります。MySQL コネクターを設定すると、コネクターに一意のサーバー ID を割り当てます。

2

log_bin

の値 log_bin は、binlog ファイルのシーケンスのベース名です。

3

binlog_format

は、ROW またはに設定 binlog-format する必要があり rowます。

4

binlog_row_image

は、FULL またはに設定 binlog_row_image する必要があり fullます。

5

expire_logs_days

これは、binlog ファイルの自動削除の日数です。デフォルトはで、自動削除は 0 行われません。

ヒント

環境の要件に一致するように値を設定します。

2.2.3. Debezium の MySQL グローバルトランザクション識別子の有効化

グローバルトランザクション識別子(GTID)は、クラスター内のサーバーで発生するトランザクションを一意に識別します。Debezium MySQL コネクターには不要ですが、GTIDs を使用するとレプリケーションが単純化され、マスターとスレーブのサーバーの整合性がより簡単に確認できるようになります。

注記

GTID は MySQL 5.6.5 以降でのみ利用できます。詳細は MySQL のドキュメント を参照してください。

前提条件

  • MySQL サーバーが必要です。
  • 基本的な SQL コマンドを知っている必要があります。
  • MySQL 設定ファイルにアクセスできる必要があります。

手順

  1. gtid_mode を有効化します。 
mysql> gtid_mode=ON
  1. enforce_gtid_consistency を有効化します。 
mysql> enforce_gtid_consistency=ON
  1. 変更を確認します。 
mysql> show global variables like '%GTID%';

response

+--------------------------+-------+
| Variable_name            | Value |
+--------------------------+-------+
| enforce_gtid_consistency | ON    |
| gtid_mode                | ON    |
+--------------------------+-------+

2.2.3.1. 説明されているオプション
permission/item説明

gtid_mode

MySQL サーバーの GTID モードが有効であるかどうかを指定します。

  • ON = enabled
  • OFF = Disabled

enforce_gtid_consistency

ブール値。サーバーに対して、トランザクションで安全な方法でログインできるステートメントの実行を許可することにより GTID の整合性を強制するかどうかを指示します。GTID の使用時に必要です。

  • ON = enabled
  • OFF = Disabled

2.2.4. Debezium のセッションタイムアウトの設定

大規模なデータベース用に初期一貫性のあるスナップショットを作成すると、テーブルが読み取られる間に確立された接続がタイムアウトする可能性があります。この動作は、MySQL 設定ファイル wait_timeout で interactive_timeout およびを設定して回避できます。

前提条件

  • MySQL サーバーが必要です。
  • 基本的な SQL コマンドを知っている必要があります。
  • MySQL 設定ファイルにアクセスできる必要があります。

手順

  1. interactive_timeout以下を設定します。 
mysql> interactive_timeout=<duration-in-seconds>
  1. wait_timeout以下を設定します。 
mysql> wait_timeout= <duration-in-seconds>
2.2.4.1. 説明されているオプション
permission/item説明

interactive_timeout

対話式接続のアクティビティーをサーバーが待機する秒数。その後閉じます。

ヒント

wait_timeout

非対話接続での動作をサーバーが待機する秒数。その後、サーバーが閉じます。

ヒント

2.2.5. Debezium のクエリーログイベントの有効化

各 binlog イベントに元の SQL ステートメントが表示される場合があります。MySQL 設定ファイルで binlog_rows_query_log_events オプションを有効にすると、これを実行できます。

注記

このオプションは MySQL 5.6 以降でのみ利用できます。

前提条件

  • MySQL サーバーが必要です。
  • 基本的な SQL コマンドを知っている必要があります。
  • MySQL 設定ファイルにアクセスできる必要があります。

手順

  1. binlog_rows_query_log_events を有効化します。 
mysql> binlog_rows_query_log_events=ON
2.2.5.1. 説明されているオプション
permission/item説明

binlog_rows_query_log_events`

binlog エントリーに元の SQL ステートメントを含むサポートを有効/無効にするブール値。

  • ON = enabled
  • OFF = Disabled

2.3. MySQL コネクターのデプロイ

2.3.1. MySQL コネクターのインストール

Debezium MySQL コネクターのインストールは簡単なプロセスで、JAR のみをダウンロードし、Kafka Connect 環境に展開し、プラグインの親ディレクトリーが Kafka Connect 環境に指定されていることを確認してください。

前提条件

手順

  1. Debezium MySQL コネクター をダウンロードします。
  2. ファイルを Kafka Connect 環境に抽出します。
  3. プラグインの親ディレクトリーを Kafka Connect に追加し plugin.pathます。 
plugin.path=/kafka/connect
注記

上記の例では、Debezium MySQL コネクターを /kafka/connect/debezium-connector-mysql パスに抽出していることを前提としています。

  1. Kafka Connect プロセスを再起動します。これにより、新しい JAR が確実に検出されます。

2.3.2. MySQL コネクターの設定

通常、コネクターで使用できる設定プロパティーを使用して、.yaml ファイルで Debezium MySQL コネクターを設定します。

前提条件

手順

  1. .yaml ファイルでコネクター "name" のを設定します。
  2. Debezium MySQL コネクターに必要な設定プロパティーを設定します。
ヒント

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

MySQL コネクターの設定例

  apiVersion: kafka.strimzi.io/v1beta1
  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.whitelist: inventory  7
      database.history.kafka.bootstrap.servers: my-cluster-kafka-bootstrap:9092  8
      database.history.kafka.topic: schema-changes.inventory  9

1 1
コネクターの名前。
2 2
1 度に操作する必要があるタスクは 1 つだけです。MySQL コネクターは MySQL サーバーの読み取りを行うため binlog、単一のコネクタータスクを使用すると適切な順序とイベント処理が確保されます。Kafka Connect サービスはコネクターを使用して作業を行う 1 つ以上のタスクを開始し、Kafka Connect サービスのクラスター全体に実行中のタスクを自動的に分散します。いずれかのサービスが停止またはクラッシュすると、そのタスクは実行中のサービスに再分配されます。
3 3
コネクターの設定。
4 4
データベースホスト。これは、MySQL サーバー(mysql)を実行しているコンテナーの名前です。
5 5 6
一意のサーバー ID および名前。サーバー名は、サーバーの MySQL サーバーまたはクラスターの論理識別子です。この名前は、すべての Kafka トピックの接頭辞として使用されます。
7
inventory データベースの変更のみが検出されます。
8 9
コネクターはこのブローカー（イベントを送信するのと同じブローカー）およびトピック名を使用して、データベーススキーマの履歴を Kafka に保存します。再起動すると、コネクターは、コネクターの読み取りを開始する binlog 際に存在したデータベースのスキーマを復元します。

2.3.3. MySQL コネクター設定プロパティー

ここにリストされている設定プロパティーは、Debezium MySQL コネクターの実行に 必要 です。また、高度な MySQL コネクタープロパティーが あり、デフォルト値はほとんど変更する必要がないため、コネクター設定で指定する必要はありません。

ヒント

Kafka プロデューサーおよびコンシューマーの作成時に、Debezium MySQL コネクターは パススルー 設定をサポートします。本セクション の最後にあるパススループロパティーについての情報 と、パススループロパティーの詳細は Kafka のドキュメント を参照 して ください。

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

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

 

監視対象の特定の MySQL データベースサーバーまたはクラスターの namespace を特定して提供する論理名。このコネクターから成るすべての Kafka トピック名の接頭辞として使用されるため、論理名は他のすべてのコネクター全体で一意にする必要があります。英数字とアンダースコアのみを使用してください。

database.server.id

random

このデータベースクライアントの数値 ID。MySQL クラスター内で現在実行中のすべてのデータベースプロセスで一意でなければなりません。このコネクターは MySQL データベースクラスターを別のサーバー（一意の ID を使用）として参加するため、binlog を読み取ることができます。デフォルトでは、明示的な値を設定することが推奨されますが、5400 から 6400 の間で乱数が生成されます。

database.history.kafka.topic

 

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

database.history​.kafka.bootstrap.servers

 

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

database.whitelist

空の文字列

監視するデータベース名に一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないデータベース名は、監視から除外されます。デフォルトでは、すべてのデータベースが監視されます。とは使用されない場合があり database.blacklistます。

database.blacklist

空の文字列

監視から除外されるデータベース名に一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないデータベース名が監視されます。とは使用されない場合があり database.whitelistます。

table.whitelist

空の文字列

監視するテーブルの完全修飾テーブル識別子と一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないテーブルはすべて監視から除外されます。各識別子は databaseName.tableName の形式です。デフォルトでは、コネクターは監視される各データベースのシステム以外のテーブルをすべて監視します。とは使用されない場合があり table.blacklistます。

table.blacklist

空の文字列

監視から除外されるテーブルの完全修飾テーブル識別子と一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないテーブルはすべて監視されます。各識別子は databaseName.tableName の形式です。とは使用されない場合があり table.whitelistます。

column.blacklist

空の文字列

変更イベントメッセージ値から除外される必要のある列の完全修飾名に一致する正規表現のオプションのコンマ区切りリスト。カラムの完全修飾名は、databaseName.tableName.columnName、または databaseName. schemaName.tableName . columnName の形式です。

column.truncate.to.length.chars

該当なし

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

column.mask.with.length.chars

該当なし

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

column.propagate.source.type

該当なし

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

datatype.propagate.source.type

該当なし

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

time.precision.mode

adaptive_time​_microseconds

時間、日付、およびタイムスタンプは、異なるタイプの精度で表すことができます。たとえば、adaptive_time_microseconds （デフォルト）は、データベース列のタイプに基づいてミリ秒、マイクロ秒、またはナノ秒のいずれかの値を使用して、データベース内で日付、日付、およびタイムスタンプの値を取得します。TIME タイプのフィールドは、connect 常にマイクロ秒としてキャプチャーされるか、または Kafka Connect の組み込み列である時間とタイムスタンプの値を表します。

decimal.handling.mode

precise

コネクターが DECIMAL および NUMERIC 列の値を処理する方法を指定します。precise （デフォルト）は、バイナリー形式で変更イベントを表す java.math.BigDecimal 値を使用して正確に double 表すか、または double 値を使用して表します。これにより精度が失われますが、使用が非常に容易になります。string オプションはフォーマットされた文字列としてエンコードされますが、実際のタイプのセマンティック情報は失われます。

bigint.unsigned.handling.mode

long

BIGINT UNSIGNED コラムが変更イベントで表される方法を指定します。は、バイナリー表現を precise 使用して変更イベントにエンコードされる値を表すために使用します。long （デフォルト）は、Java を使用して値を java.math.BigDecimal 表します org.apache.kafka.connect.data.Decimal。longこれは精度ではなくコンシューマーでの使用がはるかに簡単 long です。通常、は推奨設定です。2^63 を超える値を使用している場合のみ、これらの値はを使用して通知できないため、precise 設定を使用する必要があり longます。

include.schema.changes

true

コネクターがデータベースサーバー ID と同じ名前を持つ Kafka トピックに変更をパブリッシュするかどうかを指定するブール値。各スキーマ変更は、データベース名が含まれるキーを使用して記録され、値には DDL ステートメントが含まれます。これは、コネクターがデータベースの履歴を内部的に記録する方法に依存しません。デフォルトは true です。

include.query

false

変更イベントを生成した元の SQL クエリーをコネクターに含めるかどうかを指定するブール値。
注記： このオプションでは、MySQL を binlog_rows_query_log_events オプションで ON に設定する必要があります。スナップショットプロセスから生成されたイベントについては、クエリーは存在しません。
警告： このオプションを有効にすると、変更イベントに元の SQL ステートメントを含めることで、テーブルまたはフィールドを明示的にブラックリストに登録またはマスクすることができます。このため、このオプションはデフォルトで 'false' に設定されています。

event.processing​.failure.handling.mode

fail

binlog イベントのデシリアライズ中にコネクターが例外に応答する方法を指定します fail （問題のあるイベントとその binlog オフセットを示します）、コネクターが停止します
warn。は、問題のあるイベントをスキップし、問題のあるイベントとその binlog オフセットをログに記録する
skip 原因となります。

inconsistent.schema.handling.mode

fail

コネクターが内部スキーマ表現に存在しないテーブルに関連する binlog イベントに応答する方法を指定します（つまり内部表現はデータベースと一致しません）、例外（問題のあるイベントとその binlog オフセット）を fail スローし、コネクターが停止します
warn。は問題のあるイベントをスキップし、問題のあるイベントとその binlog オフセットをログ
skip に記録します。

max.queue.size

8192

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

max.batch.size

2048

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

poll.interval.ms

1000

新しい変更イベントが表示されるまでコネクターが待機する時間（ミリ秒単位）を指定する正の整数値。デフォルトは 1000 ミリ秒または 1 秒です。

connect.timeout.ms

30000

MySQL データベースサーバーに接続してからタイムアウトするまでにこのコネクターが待機する最大時間（ミリ秒単位）を指定する正の整数値。デフォルトは 30 秒です。

gtid.source.includes

 

MySQL サーバーで binlog の位置を見つけるために使用される GTID のソース UUID と一致する正規表現のコンマ区切りリスト。含まれるパターンの 1 つに一致するソースを持つ GTID 範囲のみが使用されます。とは使用されない場合があり gtid.source.excludesます。

gtid.source.excludes

 

MySQL サーバーで binlog の位置を見つけるために使用される GTID のソース UUID と一致する正規表現のコンマ区切りリスト。これらの除外パターンのいずれも一致しないソースを持つ GTID 範囲のみが使用されます。とは使用されない場合があり gtid.source.includesます。

tombstones.on.delete

true

削除イベントの後に tombstone イベントを生成するかどうかを制御します。
削除操作 true が削除イベントと後続の tombstone イベントによって表される場合。削除イベント false のみを送信する場合。
tombstone イベント（デフォルトの動作）を生成すると、Kafka はソースレコードが削除されると、指定のキーに関連するすべてのイベントを完全に削除できます。

message.key.columns

空の文字列

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

2.3.3.1. 高度な MySQL コネクタープロパティー

以下の表は、高度な MySQL コネクタープロパティーを示してい ます。

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

connect.keep.alive

true

MySQL サーバー/クラスターへの接続を確実に維持するために別のスレッドを使用するかどうかを指定するブール値。

table.ignore.builtin

true

組み込みシステムテーブルを無視するかどうかを指定するブール値。これは、テーブルのホワイトリストまたはブラックリストに関係なく適用されます。デフォルトでは、システムテーブルは監視から除外され、システムテーブルの変更時にイベントは生成されません。

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

100

永続化されたデータのポーリング中にコネクターが待機する最大時間（ミリ秒単位）を指定する整数値。デフォルトは 100ms です。

database.history.kafka.recovery.attempts

4

コネクターリカバリーがエラーを出して失敗するまで、コネクターが永続履歴データの読み取りを試行する最大回数。データを受信してから待機する最大 recovery.attempts 時間 recovery.poll.interval.ms。

database.history.skip.unparseable.ddl

false

コネクターが不適切なデータベースステートメントや不明なデータベースステートメントを無視するか、処理を停止すべきかを指定するブール値。また、演算子に問題を修正させるかどうかを指定するブール値。安全なデフォルトはです false。Skiping は、binlog の処理時にデータの損失や改ざんが発生する可能性があるため、注意して使用してください。

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

false

コネクターがすべての DDL ステートメントを記録する必要があるか、または Debezium によって監視されるテーブルにのみ（フィルター設定を介して true）記録する必要があるかどうかを指定するブール値。安全なデフォルトはです false。この機能は、フィルターの変更時に不足しているデータが必要になる可能性があるため、注意して使用してください。

database.ssl.mode

disabled

暗号化した接続を使用するかどうかを指定します。デフォルトはで disabled、暗号化されていない接続の使用を指定します。

この preferred オプションは、サーバーがセキュアな接続をサポートしますが、暗号化されていない接続にフォールバックする場合は、暗号化された接続を確立します。

required オプションは暗号化された接続を確立しますが、何らかの理由で接続が確立できない場合は失敗します。

verify_ca オプションはのように動作します required が、サーバー TLS 証明書を設定済みの認証局(CA)証明書に対して検証し、有効な CA 証明書に一致しないと失敗します。

verify_identity オプションはのように動作します verify_ca が、サーバー証明書がリモート接続のホストと一致することを確認します。

binlog.buffer.size

0

binlog リーダーによって使用されるルックアヘッドバッファーのサイズ。
特定の条件下では、MySQL binlog に ROLLBACK ステートメントによって終了されたコミットされていないデータが含まれる可能性があります。典型的な例は、保存ポイントを使用したり、単一のトランザクションで一時テーブルと通常のテーブルの変更を混在させたりします。
トランザクションが最初に検出されると、Debezium は binlog の位置をロール転送しようとし、COMMIT またはを見つける ROLLBACK ため、トランザクションの変更がストリーミングされるかどうかを判断できます。バッファーサイズは、トランザクション境界の検索中に Debezium がバッファーできるトランザクションの最大変更数を定義します。トランザクションのサイズがバッファーより大きい場合、Debezium はストリーミング中にバッファーに収まらないイベントを再読み込みし、再度読み直す必要があります。値ではバッファーが 0 無効になります。
デフォルトでは無効になっています。
注記： この機能は、インキュートとして考慮する必要があります。お客様からのフィードバックは必要ですが、完全に上書きされていないことが予想されます。

snapshot.mode

initial

コネクターの起動時にスナップショットを実行する基準を指定します。デフォルトはで initial、ターゲットサーバー名にオフセットが記録されていない場合に限り、コネクターがスナップショットを実行できることを指定します。when_needed オプションでは、コネクターが必要なことを常に起動時にスナップショットを実行するように指定します（オフセットが利用可能でない場合、または以前に記録されたオフセットがサーバーで利用できない binlog の場所または GTID を指定する場合）。never オプションでは、接続がスナップショットを使用せず、最初にターゲットサーバー名を指定して起動すると、binlog の先頭からコネクターが読み取られるように指定します。これは、binlog にデータベースの履歴がすべて含まれていることが保証されているため、注意して使用する必要があります。トピックでデータの一貫したスナップショットを含める必要がなく、コネクターが起動してから変更が必要なのは、コネクターがデータではなく、スキーマのみをスナップショットングする schema_only オプションを使用できます。

schema_only_recovery は、破損または失われたデータベース履歴トピックをリカバリーするための既存のコネクターのリカバリーオプションです。または、予期せずに増大する可能性のあるデータベース履歴トピック（サイレンス保持を必要とする）を定期的に「クリーンアップ」します。

snapshot.locking.mode

minimal

スナップショットの実行中に、コネクターがグローバル MySQL 読み取りロックに保持する期間（データベースの更新を非推奨にする）を制御します。、extendedおよびの 3 つの値 minimalを使用でき noneます。

minimal コネクターは、コネクターがデータベーススキーマやその他のメタデータを読み取り、スナップショットの初期部分のみのグローバル読み取りロックを保持します。スナップショットで残りの作業を行うには、各テーブルからすべての行を選択します。これは、グローバル読み取りロックが保持されなくなったり、その他の MySQL クライアントがデータベースを更新している場合でも、REPEATABLE READ トランザクションを使用して一貫した方法で実行できます。

extended クライアントが REPEATABLE READ セマンティクスから除外する操作を提出する場合、スナップショット全体の書き込みをすべてブロックする方が望ましい場合もあります。このような場合は、このオプションを使用します。

none は、コネクターがスナップショットプロセス中にテーブルロックを取得しないようにします。この値はすべてのスナップショットモードで使用できますが、スナップショットの取得中にスキーマの変更が発生していない場合に 限り、を安全に使用することができます。MyISAM エンジンで定義されたテーブルでは、MyISAM がテーブルロックを取得するため、このプロパティーが設定されている場合でもテーブルはロックされます。この動作は、行レベルのロックを取得する InnoDB エンジンとは異なります。

snapshot.select.statement.overrides

 

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

min.row.count.to.stream.results

1000

スナップショットの操作中に、コネクターは含まれる各テーブルにクエリーを行い、そのテーブル内のすべての行の読み取りイベントを生成します。このパラメーターは、MySQL 接続が、テーブルのすべての結果をメモリーにプルするかどうかを決定します（これは高速ですが、大量のメモリーを必要とする）か、結果をストリーミングするか（速度は低くなりますが、非常に大きなテーブルで機能します）。この値は、コネクターが結果をストリーミングする前に表に含める必要のある行数の最小数を指定し、デフォルトは 1,000 です。すべてのテーブルサイズチェックを省略し、スナップショット中にすべての結果をストリームするには、このパラメーターを「0」に設定します。

heartbeat.interval.ms

0

ハートビートメッセージを送信する頻度を制御します。
このプロパティーには、コネクターがハートビートメッセージをハートビートトピックに送信する頻度を定義する間隔（ミリ秒単位）が含まれます。ハートビートメッセージを送信しないよう 0 に、このパラメーターをに設定します。
デフォルトでは無効です。

heartbeat.topics.prefix

__debezium-heartbeat

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

database.initial.statements

 

データベースへの JDBC 接続（トランザクションログ読み取り接続ではなく）が確立されたときに実行する SQL ステートメントのセミコロン区切りリスト。セミコロン(';')を区切り文字として使用し、セミコロンを文字として使用する場合は 2 倍のセミコロン(';')を使用します。
注記： コネクターは、独自の判断で JDBC 接続を確立する可能性があるため、これは通常セッションパラメーターの設定のみに使用してくださいが、DML ステートメントの実行には使用しないでください。

snapshot.delay.ms

 

起動後のスナップショットの取得前にコネクターが待機する間隔（ミリ秒単位）
。クラスターで複数のコネクターを起動する際にスナップショットの中断を回避するために使用できます。コネクターのリバランスが発生する可能性があります。

snapshot.fetch.size

 

スナップショットの作成中に、各テーブルから 1 回読み込むべき行の最大数を指定します。コネクターはこのサイズの複数のバッチでテーブルコンテンツを読み取ります。

snapshot.lock.timeout.ms

10000

スナップショット実行時にテーブルロックの取得を待つ最大時間（ミリ秒単位）を指定する正の整数値。この時間帯にテーブルロックを取得できないと、スナップショットは失敗します。「 MySQL コネクターがデータベースのスナップショットを実行する方法 」を参照してください。

enable.time.adjuster

 

MySQL を使用すると、ユーザーは年の値を 2 桁の数字または 4 桁の数字として挿入できます。2 桁の数字の場合は、この値は 2019 - 2069 の範囲に自動的にマッピングされます。これは通常データベースにより行われます。
Debezium が変換を行う必要がある場合には、true （デフォルト）に設定します。
変換 false が完全にデータベースに委譲される場合は、に設定します。

sanitize.field.names

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

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

2.3.3.2. パススルー設定プロパティー

MySQL コネクターは、Kafka プロデューサーおよびコンシューマーの作成時に使用される パススルー設定プロパティー もサポートします。具体的には、データベース履歴に書き込む Kafka プロデューサーの作成時に、接頭辞で始まるすべてのコネクター設定プロパティーが使用さ database.history.producer. れます（接頭辞なし）。コネクターの起動時にデータベース履歴を読み取る Kafka コンシューマーを作成すると、接頭辞で始まるすべてのプロパティーが使用さ database.history.consumer. れます（接頭辞なし）。

たとえば、以下のコネクター設定プロパティーを使用して 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
2.3.3.3. データベースドライバーのパススループロパティー

Kafka プロデューサーおよびコンシューマーのパススループロパティーの他に、データベースドライバーには パススループロパティーがあります。これらのプロパティーには database. 接頭辞が含まれます。たとえば、database.tinyInt1isBit=false は JDBC URL に渡されます。

2.3.4. MySQL コネクターモニタリングメトリクス

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

JMX でこれらのメトリクスを公開する方法については、モニタリングドキュメント を参照してください。

2.3.4.1. スナップショットメトリクス

MBean はです debezium.mysql:type=connector-metrics,context=snapshot,server=<database.server.name>。

属性型説明

TotalTableCount

int

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

RemainingTableCount

int

スナップショットがコピーしたテーブルの数。

HoldingGlobalLock

boolean

コネクターが現在グローバルロックまたはテーブルの書き込みロックを保持しているかどうか。

SnapshotRunning

boolean

スナップショットが起動しているかどうか。

SnapshotAborted

boolean

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

SnapshotCompleted

boolean

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

SnapshotDurationInSeconds

long

スナップショットが完了しなかった場合でも、これまでスナップショットが取得した秒数の合計数。

RowsScanned

Map<String, Long>

スナップショットの各テーブルに対してスキャンされる行数が含まれるマップ。テーブルは処理中にマップに徐々に追加されます。テーブルの完了後にスキャンされた 10,000 行をすべて更新します。

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

2.3.4.2. Binlog メトリクス

MBean はです debezium.mysql:type=connector-metrics,context=binlog,server=<database.server.name>。

注記

トランザクション関連の属性は、binlog イベントバッファーが有効な場合にのみ利用できます。詳細 は、高度なコネクター設定プロパティーの binlog.buffer.size を参照してください。

属性型説明

Connected

boolean

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

BinlogFilename

string

コネクターが最後に読み取られた binlog ファイル名の名前。

BinlogPosition

long

コネクターが読み取る binlog 内の最新の位置（バイト単位）。

IsGtidModeEnabled

boolean

コネクターが現在 MySQL サーバーから GTID を追跡しているかどうかを示すフラグ。

GtidSet

string

binlog の読み取り時にコネクターによって表示される最新の GTID の文字列表現。

LastEvent

string

コネクターが読み取った最後の binlog イベント。

SecondsSinceLastEvent (Obsolete)

long

コネクターが最新のイベントを読み取り、処理したからの秒数。

SecondsBehindMaster (Obsolete)

long

最後のイベントの MySQL タイムスタンプとコネクターの処理の間の秒数。値には、MySQL サーバーと MySQL コネクターが実行されているマシン上のクロックの相違点が反映されます。

MilliSecondsBehindSource

long

最後のイベントの MySQL タイムスタンプとコネクターの処理の間隔（ミリ秒単位）。値には、MySQL サーバーと MySQL コネクターが実行されているマシン上のクロックの相違点が反映されます。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfSkippedEvents

long

MySQL コネクターによって省略されたイベントの数。通常、MySQL の binlog からの不適切なイベントまたは解析不可能なイベントにより、イベントはスキップされます。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

NumberOfDisconnects

long

MySQL コネクターによる接続解除回数。

SourceEventPosition

map<string, string>

最後に受信したイベントのコーディネート。

LastTransactionId

string

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

LastEvent

string

コネクターが読み取った最後の binlog イベント。

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

MonitoredTables

string[]

Debezium によって監視されるテーブルの一覧。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

NumberOfCommittedTransactions

long

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

NumberOfRolledBackTransactions

long

ロールバックされ、ストリーミングされなかった処理されたトランザクションの数。

NumberOfNotWellFormedTransactions

long

予想されるプロトコル BEGIN + COMMIT/ に準拠していないトランザクションの数ROLLBACK。通常 0 の状態でなければなりません。

NumberOfLargeTransactions

long

検索アヘッドバッファーに適していないトランザクションの数。最適なパフォーマンス NumberOfRolledBackTransactions を得るには NumberOfCommittedTransactions、とよりもはるかに小さいはずです。

2.3.4.3. スキーマ履歴メトリクス

MBean はです debezium.mysql:type=connector-metrics,context=schema-history,server=<database.server.name>。

属性型説明

Status

string

STOPPED RECOVERING （ストレージからの履歴をリカバリー）のいずれか。データベース履歴の状態を RUNNING 記述します。

RecoveryStartTime

long

リカバリーの開始時の時間（Eepoch 秒）。

ChangesRecovered

long

リカバリーフェーズで読み込まれた変更の数。

ChangesApplied

long

リカバリー中およびランタイム時のスキーマ変更の合計数。

MilliSecondsSinceLastRecoveredChange

long

最後の変更後に経過したミリ秒数。最後の変更が履歴ストアから復元されました。

MilliSecondsSinceLastAppliedChange

long

最後の変更が適用されてから経過したミリ秒数。

LastRecoveredChange

string

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

LastAppliedChange

string

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

2.4. MySQL コネクターの一般的な問題

2.4.1. 設定および起動エラー

Debezium MySQL コネクターが失敗し、エラーを報告し、以下の起動エラーが発生すると実行を停止します。

  • コネクターの設定は無効です。
  • コネクターは、指定の接続パラメーターを使用して MySQL サーバーに接続できません。
  • コネクターは、MySQL に履歴が利用できない binlog の位置で再起動を試みています。

これらのエラーのいずれかが表示される場合には、エラーメッセージに詳細情報が表示されます。エラーメッセージには、可能な場合は回避策も含まれます。

2.4.2. MySQL が利用できない

MySQL サーバーが利用できなくなると、Debezium MySQL コネクターがエラーを出して失敗し、コネクターが停止します。サーバーが使用できる場合は、コネクターを再起動する必要があります。

2.4.2.1. GTID の使用

GTIDs を有効にして高可用性 MySQL クラスターがある場合は、コネクターがクラスター内の別の MySQL サーバーに接続し、最後のトランザクションを表すサーバーの binlog の場所を見つけ、その特定の場所から新しいサーバーの binlog の読み取りを開始するため、コネクターをすぐに再起動します。

2.4.2.2. GTID を使用しない

GTID を有効にしていない場合は、コネクターは接続されていた MySQL サーバーの binlog の位置のみを記録します。正しい binlog の位置から再起動するには、その特定のサーバーに再接続する必要があります。

2.4.3. Kafka Connect の停止

Kafka Connect が停止すると、問題が発生する 3 つのシナリオがあります。

2.4.3.1. Kafka Connect の正常な停止

Kafka Connect が正常に停止すると、新しい Kafka Connect プロセスで Debezium MySQL コネクタータスクが停止し、再起動するまでに短い遅延が生じます。

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

Kafka Connect がクラッシュすると、プロセスが停止し、直近で処理されたオフセットが記録されずに Debezium MySQL コネクタータスクが終了します。Distributed モードでは、Kafka Connect は他のプロセスでコネクタータスクを再起動します。ただし、MySQL コネクターは、前のプロセスで記録された最後のオフセットから再開します。つまり、代替のタスクにより、クラッシュ前に処理される同じイベントの一部が生成される可能性があり、重複イベントが作成されます。

ヒント

各変更イベントメッセージには、以下のソース固有の情報が含まれます。

  • イベントの作成元
  • MySQL サーバーのイベント時間
  • binlog のファイル名と位置
  • GTID（設定されている場合）
2.4.3.3. Kafka が利用できなくなる

Kafka Connect フレームワークは、Kafka プロデューサー API を使用して Kafka の Debezium 変更イベントを記録します。Kafka ブローカーが利用できなくなると、Debezium MySQL コネクターは、接続が再確立され、コネクターが最後に停止した場所を再開するまで一時停止します。

2.4.4. MySQL が binlog ファイルをパージする

Debezium MySQL コネクターが長すぎると、MySQL サーバーは古い binlog ファイルをパージし、コネクターの最後の位置が失われる可能性があります。コネクターを再起動すると、MySQL サーバーには開始ポイントがなくなり、コネクターが別の初期スナップショットを実行します。スナップショットが無効になっていると、コネクターはエラーを出して失敗します。

ヒント

初期スナップショットの詳細は、「 MySQL コネクターがデータベースのスナップショットを実行する方法」を参照し てください。

第3章 PostgreSQL 用 Debezium コネクター

Debezium の PostgreSQL コネクターは、PostgreSQL データベースのスキーマの行レベルの変更を監視し、記録することができます。

PostgreSQL サーバー/クラスターに最初に接続すると、すべてのスキーマの一貫したスナップショットを読み取ります。スナップショットが完了すると、コネクターは PostgreSQL 9.6 以降にコミットされた変更を継続的にストリーミングし、対応する挿入、更新、および削除イベントを生成します。各テーブルのイベントはすべて個別の Kafka トピックに記録され、アプリケーションやサービスによって簡単に消費されます。

3.1. 概要

PostgreSQL の 論理デコード機能 は、最初にバージョン 9.4 で導入されました。これは、トランザクションログにコミットされた変更の抽出と、出力プラグインによる、ユーザーフレンドリーの変更の処理を可能にするメカニズムです。PostgreSQL サーバーを実行する前に、この出力プラグインをインストールし、クライアントが変更を使用できるようにレプリケーションスロットとともに有効にする必要があります。

PostgreSQL コネクターには、サーバーの変更の読み取りと処理を可能にするために連携する 2 つの異なる部分が含まれています。

  • PostgreSQL サーバーにインストールおよび設定する必要がある論理的なデコード出力プラグイン。
  • PostgreSQL JDBC ドライバー 経由 で PostgreSQL のストリーミングレプリケーションプロトコルを使用して、プラグインによって生成された変更を読み取る Java コード（実際の Kafka Connect コネクター）

コネクターは、受信した各行レベルの挿入、更新、および削除操作の 変更イベント を作成し、各テーブルの変更イベントを別の Kafka トピックに記録します。クライアントアプリケーションは、以下を行うデータベーステーブルに対応する Kafka トピックを読み取り、これらのトピックで表示されるすべての行レベルのイベントに対応します。

PostgreSQL は通常、一定期間後に WAL セグメントをパージします。つまり、コネクターにはデータベースに加えられたすべての変更の完全な履歴がないことを意味します。そのため、PostgreSQL コネクターが最初に特定の PostgreSQL データベースに接続すると、データベーススキーマの 一貫したスナップショット を実行して開始します。コネクターがスナップショットを完了した後も、スナップショットの作成先の正確な時点から変更のストリーミングが継続されます。これにより、全データの一貫したビューから始め、スナップショットの発生中に加えられた変更をすべて失われることなく、読み取りを継続します。

コネクターは失敗を許容します。コネクターは変更を読み取り、イベントを生成すると、各イベントで write-ahead ログの位置を記録します。コネクターが何らかの理由で停止する場合（通信の失敗、ネットワークの問題、クラッシュなど）、再起動すると単に WAL を読み取るだけで停止します。これには、スナップショットが含まれます。再起動すると、コネクターの停止時にスナップショットが完了しなかった場合、スナップショットが新しいスナップショットを開始されます。

3.1.1. 論理的なデコード出力プラグイン

pgoutput 論理デコーダーは、Debezium の Tecnhology Preview リリースでサポートされる唯一の論理デコーダーです。

pgoutputPostgreSQL 10+ の標準的な論理デコードプラグインは Postgres コミュニティーによって保守され、Postgres によって 論理レプリケーション に使用されます。pgoutput プラグインは常に存在し、追加のライブラリーをインストールする必要がなく、コネクターは未処理のレプリケーションイベントストリームをイベントに直接解釈します。

重要

コネクターの機能は、PostgreSQL の論理デコード機能に依存します。コネクターによっても反映される以下の制限に注意してください。

  1. 論理デコードは DDL の変更をサポートしません。これは、コネクターが DDL 変更イベントをコンシューマーに報告できないことを意味します。
  2. 論理デコードレプリケーションスロットはサーバー上でのみサポートされます。つまり、PostgreSQL primary サーバーのクラスターがある場合、コネクターはアクティブな primary サーバーでのみ実行可能となります。warm レプリカ上 hot またはスタンバイレプリカを実行できません。primary サーバーが失敗するか、または降格すると、コネクターは停止します。primary が復元したら、コネクターを再起動することができます。別の PostgreSQL サーバーが昇格された場合は primary、コネクターを再起動する前にコネクター設定を調整する必要があります。障害が発生し た場合のコネクターの動作に関する詳細を確認して ください。
重要

Debezium は現在、UTF-8 文字エンコーディングを持つデータベースのみをサポートしています。1 つのバイト文字エンコーディングでは、拡張 ASCII コード文字が含まれる文字列を正しく処理できません。

3.2. PostgreSQL の設定

このリリースの Debezium は、ネイティブの pgoutput 論理レプリケーションストリームのみをサポートします。pgoutput を使用して PostgreSQL を設定するには、レプリケーションスロットを有効にし、レプリケーションを実行するのに十分な権限を持つユーザーを設定する必要があります。

3.2.1. レプリケーションスロットの設定

PostgreSQL の論理デコードはレプリケーションスロットを使用します。

まず、レプリケーションスロットを設定します。

postgresql.conf

wal_level=logical
max_wal_senders=1
max_replication_slots=1

  • wal_level write-ahead ログで論理デコードを使用するようにサーバーへ指示します。
  • max_wal_senders WAL 変更の処理に最大 1 つのプロセスを使用するように、サーバーに指示します。
  • max_replication_slots WAL 変更をストリーミングするために最大 1 つのレプリケーションスロットを作成できるように、サーバーに指示します。

レプリケーションスロットは、Debezium の停止中であっても Debezium に必要なすべての WAL を維持することが保証されます。このため、レプリケーションスロットを強制的に監視し、ディスク消費量やレプリケーションスロットが長時間未使用のままの場合など発生する可能性のある他の状況を避けることが重要になります。詳細は Postgres のドキュメントを参照してください。

注記

PostgreSQL の write-ahead ログの 設定に関する WAL 設定ドキュメント を読み、理解することを推奨します。

3.2.2. パーミッションの設定

次に、レプリケーションを実行できるデータベースユーザーを設定します。

レプリケーションは、適切なパーミッションを持ち、設定された数のホストに対してのみレプリケーションを実行できます。

ユーザーレプリケーションパーミッションを付与するには、少なくとも REPLICATION およびパーミッションを持つ PostgreSQL ロールを定義し LOGIN ます。以下に例を示します。 

CREATE ROLE name REPLICATION LOGIN;
注記

スーパーユーザーには、上記のロールの両方がデフォルトで設定されます。

最後に、サーバーマシンと PostgreSQL コネクターが実行しているホストとの間でレプリケーションを実行できるように PostgreSQL サーバーを設定します。

pg_hba.conf

local   replication     <youruser>                          trust   1
host    replication     <youruser>  127.0.0.1/32            trust   2
host    replication     <youruser>  ::1/128                 trust   3

1
サーバーに、<youruser> ローカルマシン（サーバーマシンなど）のレプリケーションを許可するように指示します。
2
を使用して、サーバー <youruser> に対して localhost レプリケーションの変更を許可するよう指示します。 IPV4
3
を使用して、サーバー <youruser> に対して localhost レプリケーションの変更を許可するよう指示します。 IPV6
注記

ネットワークマスク の詳細は、PostgreSQL のドキュメント を参照してください。

3.2.3. WAL ディスク容量の消費

特定のケースでは、WAL ファイルが消費する PostgreSQL ディスク領域が急増するか、通常の比で増加する可能性があります。状況を説明する可能性のある理由は 3 つあります。

  • Debezium は、定期的に、処理されたイベントの LSN をデータベースに対して確認します。これは pg_replication_slots スロットテーブルのよう confirmed_flush_lsn に表示されます。データベースはディスク領域の回収を担当し、WAL サイズは restart_lsn 同じテーブルから計算できます。したがって、confirmed_flush_lsn が定期的に増加し、ラグの場合には、データベースは領域を回収する必要 restart_lsn があります。ディスク領域は通常バッチブロックで回収されるため、これは予想される動作であり、ユーザーの側での動作は必要ありません。
  • 監視対象のデータベースには多くの更新がありますが、対象のテーブルやスキーマ、もしくはスキーマに関連するのは、逆累積量のみです。この状況は、heartbeat.interval.ms 設定オプションを使用して定期的なハートビートイベントを有効にすることで簡単に解決できます。
  • PostgreSQL インスタンスには複数のデータベースが含まれ、その 1 つが高トラフィックのデータベースになります。Debezium は、他のデータベースと比較すると、トラフィックの低い別のデータベースを監視します。Debezium は LSN をデータベースごとにレプリケーションスロットが機能するため、Debezium が呼び出されないため、確認することができません。WAL はすべてのデータベースで共有されるため、Debezium が監視するデータベースがイベントを出力するまで拡大する傾向があります。

3 番目の原因を解決するには、

  • heartbeat.interval.ms 設定オプションを使用した定期的なハートビートレコード生成を有効にします。
  • Debezium が追跡するデータベースから変更イベントを定期的に出力します。

その後、別のプロセスはテーブルを定期的に更新します（新しいイベントを挿入するか、すべて同じ行を更新します）。その後、PostgreSQL は、最新の LSN を確認し、データベースが WAL 領域を回収できるようにする Debezium を呼び出します。このタスクは、heartbeat.action.query コネクターオプションを使用して自動化できます（下記参照）。

ヒント

Postgres を使用した AWS RDS のユーザーの場合、3 つ目の原因がアイドル環境で発生する可能性があります。これは、AWS RDS が独自のシステムテーブルに書き込みを行い、頻繁にユーザーに認識されないため（5 分）。イベントを定期的に出力すると、問題は解決されます。

3.2.4. PostgreSQL コネクターの仕組み

3.2.4.1. スナップショット

ほとんどの PostgreSQL サーバーは、WAL セグメントにデータベースの完全な履歴を保持しないように設定されます。そのため、PostgreSQL コネクターは WAL を読み取るだけでデータベースの履歴全体を表示できません。そのため、デフォルトでは、初回起動時にコネクターがデータベースの初期 一貫性のあるスナップショット を実行します。各スナップショットは以下の手順で構成されます（ビルトインスナップショットモードを使用している場合 、 カスタムスナップショットモードはこれをオーバーライドできます）。

  1. SERIALIZABLE、READ ONLY、DEFERRABLE 分離レベルでトランザクションを開始し、 このトランザクション内のすべての後続読み取りがデータの単一のバージョンに対して実行されるようにします。その後のデータの変更や INSERT UPDATE、他のクライアントによる DELETE 操作はこのトランザクションからは認識されません。
  2. 各監視されるテーブルの ACCESS SHARE MODE ロックを取得して、スナップショットの発生中に構成の変更が発生しないようにします。このロックはテーブル UPDATES DELETES を妨げず INSERTS、操作中に実行できないことに注意してください。この手順は、エクスポートされたスナップショットモードを使用してロックなしのスナップショットを許可する場合に省略 されます。
  3. サーバーのトランザクションログの現在の位置を取得します。
  4. データベーステーブルおよびスキーマをすべてスキャンし、各行の READ イベントを生成し、そのイベントを適切なテーブル固有の Kafka トピックに書き込みます。
  5. トランザクションをコミットします。
  6. コネクターオフセットでスナップショットが正常に完了したことを記録します。

コネクターが失敗する場合や、ステップ 1 の開始後、ステップ 6 の完了前にコネクターがリバランスされる場合、コネクターを再起動すると、新しいスナップショットが開始されます。コネクターが最初のスナップショットを完了したら、PostgreSQL コネクターはステップ 3 中に、位置読み取りからストリーミングを継続し、更新をミスしないようにします。コネクターが何らかの理由で再度停止した場合、再起動すると、以前停止した場所から変更のストリーミングが続行されます。

2 つ目のスナップショットモードを使用すると、コネクター は常に スナップショットを実行できます。この動作は、起動時に 常に スナップショットを実行するようにコネクターに指示し、スナップショットが完了したら、上記のシーケンスで手順 3 から変更をストリーミングを継続します。このモードは、一部の WAL セグメントが削除され、利用できなくなったことを把握する場合や、新規プライマリーのプロモート後にクラスター障害が発生した場合に使用できます。これにより、新しいプライマリーの昇格後に行った可能性のある変更がコネクターによって失われないようにし、新しいプライマリーでコネクターが再起動する前に発生する可能性があります。

3 つ目のスナップショットモードは、コネクターがスナップショットを実行し ない ように指示します。新しいコネクターを設定すると、以前保存されたオフセットからの変更のストリーミングが継続される場合、PostgreSQL の論理レプリケーションスロットが最初に作成されたときに開始します。このモードは、対象のすべてのデータが WAL に反映されている場合にのみ役に立つことに注意してください。

4 番目のスナップショットモード は、初期 にデータベーススナップショットを実行してから、他の変更をストリーミングする前に停止します。コネクターが起動していても、停止前にスナップショットが完了しなかった場合、コネクターはスナップショットプロセスを再起動して、スナップショットが完了すると停止します。

エクスポートさ れる 5 番目のスナップショットモードは、レプリケーションスロットが作成された時点に基づいてデータベースのスナップショットを実行します。このモードでは、ロックなしの方法でスナップショットを実行することが非常に優れています。

3.2.4.2. ストリーミングの変更

通常、PostgreSQL コネクターは、接続している PostgreSQL サーバーからの変更の大部分の時間ストリーミングを行います。このメカニズム は、特定の場所（ Log Sequence Numbers または短い LSN）でサーバーのトランザクションログにコミットされる際にクライアントがサーバーからの変更を受け取ることができる PostgreSQL のレプリケーションプロトコルに依存します。

サーバーがトランザクションをコミットすると、別のサーバープロセスが 論理デコードプラグインからコールバック関数を呼び出します。この関数はトランザクションの変更を処理し、それらを特定の形式（Debezium プラグインの場合はProtobuf または JSON）に変換して出力ストリームに書き込み、クライアントが消費できる出力ストリームに書き込みます。

PostgreSQL コネクターは PostgreSQL クライアントとして動作し、これらの変更を受け取ると、イベントが Debezium がイベントの LSN 位置を含むイベントの 作成、更新、または 削除 に変換されます。PostgreSQL コネクターは、これらの変更イベントを Kafka Connect フレームワークに転送し（同じプロセスで実行）、適切な Kafka トピックに非同期的に書き込みます。Kafka Connect は、Debezium に各イベントと共に含まれるソース固有の位置情報の オフセット を使用します。Kafka Connect では、別の Kafka トピックに最新のオフセットが定期的に記録されます。

Kafka Connect が正常にシャットダウンすると、コネクターを停止し、すべてのイベントを Kafka にフラッシュし、各コネクターから受信した最後のオフセットを記録します。再起動すると、Kafka Connect は各コネクターの最後に記録されたオフセットを読み取り、そのコネクターからコネクターを起動します。PostgreSQL コネクターは、各変更イベントに記録された LSN をオフセットとして使用し、再起動時に PostgreSQL サーバーがその位置の直後にイベントを送信するようにします。

注記

PostgreSQL コネクターは、論理デコーダープラグインによって送信されるイベントの一部としてスキーマ情報を取得します。この情報は JDBC メタデータ（サイドチャネル）から取得されるため、唯一の例外は、プライマリーキーを構成する列に関する情報です。（PK コラムの追加、削除、名前変更による）テーブルのプライマリーキー定義が変更された場合、JDBC のプライマリーキー情報が論理デコードイベントの変更データと同期されず、一貫性のないキー構造で少数のメッセージが作成されます。この場合は、コネクターを再起動し、メッセージの再処理により問題が解決されます。この問題を回避するには、主に以下の操作シーケンスを使用して、プライマリーキー構造への更新を Debezium と同期することが推奨されます。

  • データベースまたはアプリケーションを読み取り専用モードに切り替えます。
  • 残りのすべてのイベントを Debezium が処理できるようにします。
  • Debezium の停止
  • プライマリーキー定義の更新
  • データベースまたはアプリケーションを読み取り/書き込み状態にし、Debezium を再び起動します。
3.2.4.3. PostgreSQL 10+ 論理デコードサポート(pgoutput)

PostgreSQL 10+ の時点で、新しい論理レプリケーションストリームモード(pgoutput)が導入されまし た。この論理レプリケーションストリームモードは、PostgreSQL によってネイティブにサポートされます。そのため、このコネクターは、追加のプラグインをインストールすることなくレプリケーションストリームを消費できます。これは、プラグインのインストールがサポートされない、または許可されない環境で特に有用です。

詳細は、「 PostgreSQL の設定 」を参照してください。

3.2.4.4. トピック名

PostgreSQL コネクターは、すべての挿入、更新、および削除のイベントを単一の Kafka トピックに対して書き込みます。デフォルトでは、Kafka トピック名は serverName. schemaName. tableName です。serverName は database.server.name 設定プロパティーで指定されたコネクターの論理名、schemaName は 操作が発生したデータベーススキーマの名前、tableName は操作が発生したデータベーステーブルの名前です。

たとえば、postgres データベースと、、、およびの 4 つのテーブルを含む inventory スキーマを使用した PostgreSQL インストールについて考え products products_on_hand customersてみましょう orders。このデータベースに論理サーバー名が指定された場合 fulfillment、コネクターは以下の 4 つの Kafka トピックでイベントを生成します。

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

一方、テーブルは特定のスキーマの一部ではなく、デフォルトの public PostgreSQL スキーマで作成された場合、Kafka トピックの名前は以下のようになります。

  • fulfillment.public.products
  • fulfillment.public.products_on_hand
  • fulfillment.public.customers
  • fulfillment.public.orders
3.2.4.5. meta Information

PostgreSQL コネクターによって record 生成された各 データベースイベント に加えて、サーバーでイベントが発生した場所、ソースパーティションの名前、およびイベントを配置する Kafka トピックおよびパーティションの名前に関するメタ情報があります。 

"sourcePartition": {
     "server": "fulfillment"
 },
 "sourceOffset": {
     "lsn": "24023128",
     "txId": "555",
     "ts_ms": "1482918357011"
 },
 "kafkaPartition": null

PostgreSQL コネクターは 1 つの Kafka Connect パーティション のみを使用し、生成されたイベントを 1 Kafka パーティションに配置します。そのため、の名前 sourcePartition は常に設定プロパティーの名前に database.server.name 設定されます null。一方、の値はコネクター kafkaPartition が特定の Kafka パーティションを使用しないことを意味します。

メッセージの sourceOffset 一部には、イベントが発生したサーバーの場所に関する情報が含まれます。

  • lsn PostgreSQL ログシーケンス番号 または offset トランザクションログを表します。
  • txId イベントの原因となったサーバートランザクションの識別子を表します。
  • ts_ms トランザクションがコミットされたサーバー時間として Unix Epoch からのマイクロ秒数を表します。
3.2.4.6. イベント

PostgreSQL コネクターによって生成されたすべてのデータ変更イベントにはキーと値がありますが、キーと値の構造は、変更イベントの発生元となるテーブルによって異なります（ トピック名を参照）。

注記

Kafka 0.10 以降、Kafka はオプションでメッセージキーで記録でき、メッセージが作成された（プロデューサーによって録画）、または Kafka によってログに書き込まれる タイムスタンプ を値として指定できます。

警告

PostgreSQL コネクターは、すべての Kafka Connect スキーマ名が 有効な Avro スキーマ名 であることを確認し ます。つまり、論理サーバー名は、ラテン文字またはアンダースコア（例： [a-z,A-Z,_]）で開始し、論理サーバー名の残りの文字と、スキーマおよびテーブル名の残りの文字は、ラテン文字、数字、またはアンダースコア([a-z,A-Z,0-9,\_])で始まる必要があります。そうでない場合には、無効な文字はすべて自動的にアンダースコアに置き換えられます。

これにより、論理サーバー名、スキーマ名、およびテーブル名に他の文字が含まれる場合に予期しない競合が発生し、テーブルのフルネーム間の文字のみが無効となり、アンダースコアに置き換えられます。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリームについて設計されており、これらのイベント の構造は徐々に変わる可能性があります。これはコンシューマーによる対応が困難になる可能性があるため、Kafka Connect による各イベントの自己完結が容易になります。各メッセージキーと値には、スキーマ と ペイロード の 2 つの部分があります。スキーマはペイロードの構造を記述し、ペイロードには実際のデータが含まれます。

3.2.4.6.1. Change イベントのキー

特定のテーブルでは、変更イベントのキーには、イベントの作成時にテーブルのプライマリーキー（または FULL USING INDEX テーブルに REPLICA IDENTITY 設定された一意の鍵制約）内の各列のフィールドが含まれる構造があります。

public データベーススキーマで定義されている customers テーブルについて考えてみましょう。 

CREATE TABLE customers (
  id SERIAL,
  first_name VARCHAR(255) NOT NULL,
  last_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL,
  PRIMARY KEY(id)
);

database.server.name 設定プロパティーに値がある場合 PostgreSQL_server、この定義がある間に customers テーブルのすべての変更イベントは、JSON で使用する同じキー構造に対応します。 

{
  "schema": {
    "type": "struct",
    "name": "PostgreSQL_server.public.customers.Key",
    "optional": false,
    "fields": [
          {
              "name": "id",
              "index": "0",
              "schema": {
                  "type": "INT32",
                  "optional": "false"
              }
          }
      ]
  },
  "payload": {
      "id": "1"
  },
}

キーの schema 部分には、キー部分に含まれるものを記述する Kafka Connect スキーマが含まれます。この場合、payload 値はオプションではなく、という名前のスキーマによって定義される構造で PostgreSQL_server.public.customers.Key、id type という名前の必須フィールドが 1 つあることを意味し int32ます。キーのフィールドの値を確認すると、値が 1 つの payload フィールドを id 持つ構造（JSON 内のオブジェクト）であることが分かり 1ます。

そのため、このキーは、プライマリーキーコラムにの値がである public.customers テーブル（コネクターから出力 PostgreSQL_server）の行を記述する id ものとして解釈し 1ます。

注記

column.blacklist 設定プロパティーを使用するとテーブル列のサブセットのみを取得できますが、プライマリーキーまたは一意のキーのすべての列がイベントのキーに含まれます。

警告

テーブルにプライマリーキーまたは一意の鍵がない場合は、変更イベントのキーは null になります。これは、プライマリーキー制約や一意の鍵制約のないテーブルの行を一意に特定できないため、理にかなっています。

3.2.4.6.2. イベントの値の変更

変更イベントメッセージの値は、より複雑です。メッセージキーと同様に、schema セクションと payload セクションがあります。PostgreSQL コネクターによって生成されるすべての変更イベント値の payload セクションには、以下のフィールドが含まれる 構造 があります。

  • op は、操作のタイプを記述する文字列の値が含まれる必須フィールドです。PostgreSQL コネクターの値は c create（または insert）、u 更新、d 削除、および r 読み取り（スナップショットの場合）になります。
  • before はオプションのフィールドで、イベント発生 前 の行の状態がある場合はその行の状態になります。この構造は、PostgreSQL_server コネクターが public.customers テーブルのすべての行に使用する PostgreSQL_server.public.customers.Value Kafka Connect スキーマによって記述されます。
警告

このフィールドが利用できるかどうかは、各テーブルの REPLICA IDENTITY 設定に大きく依存します。

  • after はオプションのフィールドで、イベント発生 後 の行の状態が含まれる場合です。構造は、で使用される同じ PostgreSQL_server.public.customers.Value Kafka Connect スキーマによって記述され beforeます。
  • source は、イベントのソースメタデータを記述する構造が含まれる必須フィールドです。ここでは、PostgreSQL のフィールドには、Debezium バージョン、コネクター名、影響を受けるデータベースの名前、スキーマ、およびテーブルが含まれます。イベントが継続中のスナップショットの一部であるかどうか、レコードの メタ情報 セクションから同じフィールドが含まれるかどうか。
  • ts_ms は任意で、コネクターがイベントを処理した JVM のシステムクロックを使用して（Kafka Connect タスクを実行している JVM でシステムクロックを使用）。

当然ながら、イベントメッセージ値の スキーマ 部分には、この構造と内部のネストされたフィールドを記述するスキーマが含まれます。

3.2.4.6.3. レプリカ ID

REPLICA IDENTITY は、UPDATE や DELETE イベントが発生した場合に利用できる情報量を決定する PostgreSQL 固有 logical decoding のテーブルレベルの設定です。さらに具体的には、前述のイベントのいずれかが発生するたびに、テーブル列の以前の値に関して利用可能な（ある場合）情報を制御できます。

以下の 4 つの値を使用 REPLICA IDENTITYできます。

  • DEFAULT: UPDATE および DELETE イベントには、変更された値を持つプライマリー列のみが存在する場合に、テーブルのプライマリーキー列の以前の値 UPDATE のみが含まれます。
  • NOTHING - UPDATE および DELETE イベントには、テーブル列のいずれかに以前の値に関する情報が含まれません。
  • FULL - UPDATE および DELETE イベントには、全テーブルの列の以前の値が含まれます。
  • INDEX index name - UPDATE と DELETE イベントに、変更された値を持つインデックスされた列 UPDATE のみが存在する場合に index name、という名前のインデックス定義に含まれるコラムの値が格納されます。
3.2.4.6.4. イベントの作成

イベントの 作成 値を以下の 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": "PostgreSQL_server.inventory.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": "PostgreSQL_server.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": false,
                        "field": "schema"
                    },
                    {
                        "type": "string",
                        "optional": false,
                        "field": "table"
                    },
                    {
                        "type": "int64",
                        "optional": true,
                        "field": "txId"
                    },
                    {
                        "type": "int64",
                        "optional": true,
                        "field": "lsn"
                    },
                    {
                        "type": "int64",
                        "optional": true,
                        "field": "xmin"
                    }
                ],
                "optional": false,
                "name": "io.debezium.connector.postgresql.Source",
                "field": "source"
            },
            {
                "type": "string",
                "optional": false,
                "field": "op"
            },
            {
                "type": "int64",
                "optional": true,
                "field": "ts_ms"
            }
        ],
        "optional": false,
        "name": "PostgreSQL_server.inventory.customers.Envelope"
    },
    "payload": {
        "before": null,
        "after": {
            "id": 1,
            "first_name": "Anne",
            "last_name": "Kretchmar",
            "email": "annek@noanswer.org"
        },
        "source": {
            "version": "1.1.2.Final",
            "connector": "postgresql",
            "name": "PostgreSQL_server",
            "ts_ms": 1559033904863,
            "snapshot": true,
            "db": "postgres",
            "schema": "public",
            "table": "customers",
            "txId": 555,
            "lsn": 24023128,
            "xmin": null
        },
        "op": "c",
        "ts_ms": 1559033904863
    }
}

このイベントの 値 の schema 一部を確認すると、source 構造のスキーマ（PostgreSQL コネクターに固有の スキーマ、before および after フィールドのテーブル固有のスキーマ）が表示されます。

注記

before および after フィールドのスキーマ名は logicalName. schemaName . tableName.Value の形式であるため、他のすべてのテーブルの他のすべてのスキーマから完全に独立した名前になります。

つまり、Avro Converter を使用すると、各 論理ソース の 各テーブル の Avro スキーマは、独自の進化と履歴になります。

このイベントの 値 の payload 一部を確認すると、イベントの情報が表示されます。つまり、行が作成されたこと（つまり op=c）、および after フィールドの値に、新しい挿入された行の、、、id first_name last_nameおよび email 列の値が含まれていることが示されています。

注記

これは、イベントの JSON 表現が記述する行よりもはるかに大きいことが分かります。JSON 表現にはメッセージの スキーマ と ペイロード の部分を含める必要があるため、これは true です。

Avro コンバーターを使用して、Kafka トピックに書き込まれた実際のメッセージのサイズを大幅に縮小することもできます。

3.2.4.6.5. 更新イベント

このテーブルの 更新 変更イベントの値には実際には同じ スキーマ があり、ペイロードは同じですが、異なる値を保持します。以下に例を示します。 

{
    "schema": { ... },
    "payload": {
        "before": {
            "id": 1
        },
        "after": {
            "id": 1,
            "first_name": "Anne Marie",
            "last_name": "Kretchmar",
            "email": "annek@noanswer.org"
        },
        "source": {
            "version": "1.1.2.Final",
            "connector": "postgresql",
            "name": "PostgreSQL_server",
            "ts_ms": 1559033904863,
            "snapshot": null,
            "db": "postgres",
            "schema": "public",
            "table": "customers",
            "txId": 556,
            "lsn": 24023128,
            "xmin": null
        },
        "op": "u",
        "ts_ms": 1465584025523
    }
}

これを insert イベントの値と比較すると、payload セクションにいくつかの違いが表示されます。

  • op フィールド値は u、更新によりこの行が変更されたことを示すようになりました。
  • この before フィールドには、データベースのコミット前に値がある行の状態が表示されますが、プライマリーキーコラムだけが対象になります id。これは、デフォルトで REPLICA IDENTITY であるためです DEFAULT。
注記

行のすべての列の以前の値を表示するには、最初に customers テーブルを変更する必要があります。 ALTER TABLE customers REPLICA IDENTITY FULL

  • この after フィールドには更新された行の状態が使用されるようになりました。ここで、first_name 値は現在の状態であることを確認でき Anne Marieます。
  • source フィールド構造には以前のフィールドと同じフィールドがありますが、このイベントが WAL の別の位置にあるため、値は異なります。
  • は ts_ms、Debezium がこのイベントを処理したタイムスタンプを示しています。

本 payload セクションのみで確認できる点がいくつかあります。コミットにより before、と after 構造を比較して、この行で実際に何が変更されているかを判断できます。この source 構造では、この変更に関する PostgreSQL のレコード（トレース可能性の向上）について説明しますが、重要なことは、このイベントや他のトピックの他のイベントと比較し、他のトピックで発生したイベントが他のイベントとして発生したか、または他のイベントとして同じ PostgreSQL コミットの一部として確認できるようにすることができます。

注記

行のプライマリー/一意キーの列が更新されると、行のキーの値が変更になり、Debezium は行の古いキーを持つ DELETE イベント と、行の新しいキーの INSERT イベント 3 つ のイベントを出力します。

3.2.4.6.6. イベントの削除

そのため、イベントの 作成 および 更新 の例が見られました。ここでは、同じテーブルの 削除 イベントの値を確認します。繰り返し発生すると、値の schema 一部は create イベントおよび 更新 イベントと全く同じになります。 

{
    "schema": { ... },
    "payload": {
        "before": {
            "id": 1
        },
        "after": null,
        "source": {
            "version": "1.1.2.Final",
            "connector": "postgresql",
            "name": "PostgreSQL_server",
            "ts_ms": 1559033904863,
            "snapshot": null,
            "db": "postgres",
            "schema": "public",
            "table": "customers",
            "txId": 556,
            "lsn": 46523128,
            "xmin": null
        },
        "op": "d",
        "ts_ms": 1465581902461
    }
}

payload 部分を確認すると、イベントペイロードの 作成 または 更新 との違いが複数あります。

  • op フィールド値は d、この行が削除されたことを表しています。
  • この before フィールドには、データベースのコミットで削除された行の状態が表示されます。この場合も、REPLICA IDENTITY 設定によりプライマリーキー列のみが含まれます。
  • after フィールドは null で、行が存在しなくなったことを表します。
  • source フィールド構造には、、および txId フィールドの変更を除き、前 ts_ms lsn と同じ値の多くが含まれます。
  • は ts_ms、Debezium がこのイベントを処理したタイムスタンプを示しています。

このイベントにより、コンシューマーがこの行の削除を処理するのに使用できるすべての情報が提供されます。

警告

PK なしのテーブルには注意してください。REPLICA IDENTITY DEFAULT を持つテーブルからの削除メッセージには、before （デフォルト ID レベルの唯一のフィールドである PK がない）そのため、空としてスキップされます。PK のないテーブルからのメッセージを処理するには、REPLICA IDENTITY を FULL レベルに設定します。

PostgreSQL コネクターのイベントは、Kafka ログの圧縮 と連携するように設計されています。これにより、すべてのキーの少なくとも最新のメッセージが保持されていれば、古いメッセージを削除することができます。これにより、Kafka はストレージ領域を回収でき、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できます。

行が削除されても、上記の delete イベント値はログの圧縮でも機能します。これは、Kafka が同じキーで以前のメッセージをすべて削除できるためです。しかし、メッセージ値が Kafka null では、同じキーを持つ すべてのメッセージ が削除できる場合にのみ使用されます。これを可能にするために、PostgreSQL コネクターは、常に同じキーではなく null 値を持つ特別な tombstone イベントで delete イベントに従います。

3.2.5. トランザクションメタデータ

Debezium は、トランザクションメタデータの境界を表すイベントを生成し、データメッセージを強化できます。

3.2.5.1. トランザクション境界

Debezium は、すべてのトランザクション BEGIN およびのイベントを生成し ENDます。すべてのイベントにはが含まれます。

  • status - BEGIN または END
  • id : 一意のトランザクション ID の文字列表現
  • event_count （ END イベント用）: トランザクションによってエミュレートされたイベントの合計数
  • data_collections （ END イベント用）: 指定のデータコレクションから発信さ event_count れる変更により発生するイベントの数を提供する data_collection とのペアの配列

メッセージの例を以下に示します。 

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

{
  "status": "END",
  "id": "571",
  "event_count": 2,
  "data_collections": [
    {
      "data_collection": "s1.a",
      "event_count": 1
    },
    {
      "data_collection": "s2.a",
      "event_count": 1
    }
  ]
}

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

3.2.5.2. データイベントの強化

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

  • id : 一意のトランザクション ID の文字列表現
  • total_order : トランザクションによって生成されるすべてのイベント間のイベントの絶対位置
  • data_collection_order : トランザクションによって出力されたすべてのイベント間のイベントのデータ収集位置

メッセージの例を以下に示します。 

{
  "before": null,
  "after": {
    "pk": "2",
    "aa": "1"
  },
  "source": {
...
  },
  "op": "c",
  "ts_ms": "1580390884335",
  "transaction": {
    "id": "571",
    "total_order": "1",
    "data_collection_order": "1"
  }
}
3.2.5.3. データタイプ

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

以下の表は、コネクターが各 PostgreSQL データタイプをイベントのフィールド 内 の リテラルタイプ およびセマンティクスタイプにマッピングする方法について説明しています。

literal タイプは、Kafka Connect のスキーマタイプ（、、、、、、、、、、、、、、、、、、、、INT8、、INT16 INT32 INT64 FLOAT32 FLOAT64 BOOLEAN、STRING BYTES ARRAY MAPおよび）を使用して値が文字的に表される方法を記述 し STRUCTます。

セマンティクスタイプは、Kafka Connect スキーマがフィールドの Kafka Connect スキーマの名前を使用してフィールドの 意味 をキャプチャーする方法について説明しています。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

BOOLEAN

BOOLEAN

該当なし

 

BIT(1)

BOOLEAN

該当なし

 

BIT( > 1), BIT VARYING[(M)]

BYTES

io.debezium.data.Bits

length schema パラメーターには、ビット数を表す整数が含まれます。結果的にはリトルエンディアン形式でビットが byte[] 含まれ、指定されたビット数を含めるようにサイズが指定されます（例： numBytes = n/8 + (n%8== 0 ? 0 : 1) n はビット数）。

SMALLINT, SMALLSERIAL

INT16

該当なし

 

INTEGER, SERIAL

INT32

該当なし

 

BIGINT, BIGSERIAL

INT64

該当なし

 

REAL

FLOAT32

該当なし

 

DOUBLE PRECISION

FLOAT64

該当なし

 

CHAR[(M)]

STRING

該当なし

 

VARCHAR[(M)]

STRING

該当なし

 

CHARACTER[(M)]

STRING

該当なし

 

CHARACTER VARYING[(M)]

STRING

該当なし

 

TIMESTAMPTZ, TIMESTAMP WITH TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

タイムゾーン情報が GMT であるタイムスタンプを表す文字列

TIMETZ, TIME WITH TIME ZONE

STRING

io.debezium.time.ZonedTime

タイムゾーン情報が GMT であるタイムゾーン情報が含まれる文字列表現

INTERVAL [P]

INT64

io.debezium.time.MicroDuration
（デフォルト）

365.25 / 12.0 計算式（月 1 日）を使用した時間間隔のマイクロ秒単位の概算値。

INTERVAL [P]

String

io.debezium.time.Interval
（がに設定 interval.handling.mode されているタイミング string）

パターンに続く間隔の値の文字列表現（ P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S例：）。 P1Y2M3DT4H5M6.78S

BYTEA

BYTES

該当なし

 

JSON, JSONB

STRING

io.debezium.data.Json

JSON ドキュメント、配列、またはスケーラーの文字列表現が含まれます。

XML

STRING

io.debezium.data.Xml

XML ドキュメントの文字列表現を含みます。

UUID

STRING

io.debezium.data.Uuid

PostgreSQL UUID 値の文字列表現が含まれます。

POINT

STRUCT

io.debezium.data.geometry.Point

2 つの FLOAT64 フィールドを持つ構造が含まれています (x,y)。それぞれはジオメトリックポイントの座標を表します。

LTREE

STRING

io.debezium.data.Ltree

PostgreSQL LTREE 値の文字列表現が含まれます。

CITEXT

STRING

該当なし

 

INET

STRING

該当なし

 

INT4RANGE

STRING

該当なし

整数の範囲

INT8RANGE

STRING

該当なし

bigint の範囲

NUMRANGE

STRING

該当なし

数値の範囲

TSRANGE

STRING

該当なし

タイムゾーンなしのタイムスタンプ範囲の文字列表現が含まれます。

TSTZRANGE

STRING

該当なし

（ローカルシステム）タイムゾーンを含むタイムスタンプ範囲の文字列表現が含まれます。

DATERANGE

STRING

該当なし

日付範囲の文字列表現が含まれます。これは常に排他的な上限を持ちます。

ENUM

STRING

io.debezium.data.Enum

PostgreSQL ENUM 値の文字列表現が含まれます。許可される値のセットは、という名前のスキーマパラメーターに保持され allowedます。

その他のデータタイプのマッピングについては、以下のセクションで説明します。

3.2.5.3.1. 一時的な値

PostgreSQL の TIMESTAMPTZ および TIMETZ データタイプ（タイムゾーン情報が含まれる）以外では、他の一時タイプは time.precision.mode 設定プロパティーの値によって異なります。time.precision.mode 設定プロパティーが adaptive （デフォルト）に設定されると、コネクターはコラムのデータタイプ定義に基づいて一時タイプのリテラルタイプおよびセマンティクスタイプを判断し、イベントがデータベースの値を 正確 に表します。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

DATE

INT32

io.debezium.time.Date

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

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

INT32

io.debezium.time.Time

タイムゾーン情報が含まれ、午前 1 時を経過したミリ秒数を表します。

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

INT64

io.debezium.time.MicroTime

タイムゾーン情報が含まれ、午前 1 時以内に経過したマイクロ秒数を表します。

TIMESTAMP(1), TIMESTAMP(2), TIMESTAMP(3)

INT64

io.debezium.time.Timestamp

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

TIMESTAMP(4), TIMESTAMP(5), TIMESTAMP(6), TIMESTAMP

INT64

io.debezium.time.MicroTimestamp

過去のエポックに対するマイクロ秒数を表し、タイムゾーン情報が含まれません。

設定プロパティーがに time.precision.mode 設定されていると adaptive_time_microseconds、コネクターはコラムのデータタイプ定義に基づいてリテラルタイプとセマンティクスタイプを判断します。これにより、イベントがデータベースの値を 正確 に表します。ただし、すべての TIME フィールドがマイクロ秒としてキャプチャーされます。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

DATE

INT32

io.debezium.time.Date

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

TIME([P])

INT64

io.debezium.time.MicroTime

タイムゾーン情報が含まれ、時間値をマイクロ秒単位で表します。PostgreSQL では、精度 0 - 6 の範囲 P で、マイクロ秒の精度を最大で保存できます。

TIMESTAMP(1) , TIMESTAMP(2), TIMESTAMP(3)

INT64

io.debezium.time.Timestamp

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

TIMESTAMP(4) , TIMESTAMP(5), TIMESTAMP(6), TIMESTAMP

INT64

io.debezium.time.MicroTimestamp

過去のエポックに対するマイクロ秒数を表し、タイムゾーン情報が含まれません。

設定プロパティーがに time.precision.mode 設定された場合 connect、コネクターは事前定義された Kafka Connect の論理タイプを使用します。これは、コンシューマーがビルトインの Kafka Connect の論理タイプのみを認識し、可変精度の値を処理することができない場合に便利です。一方、PostgreSQL はマイクロ秒の精度をサポートするため、connect 時間精度モードのコネクターによって生成されたイベント により、データベースの列に 分数次の精度の値が 3 よりも大きいと、精度 が失わ れてしまいます。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

DATE

INT32

org.apache.kafka.connect.data.Date

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

TIME([P])

INT64

org.apache.kafka.connect.data.Time

毎時からのミリ秒数を表し、タイムゾーン情報が含まれません。PostgreSQL では 0 - 6 の範囲で最大マイクロ秒の精度を保存 P できますが、P> 3 ではこのモードの精度が失われます。

TIMESTAMP([P])

INT64

org.apache.kafka.connect.data.Timestamp

エポックからの経過時間（ミリ秒単位）を表し、タイムゾーン情報が含まれません。PostgreSQL では 0 - 6 の範囲で最大マイクロ秒の精度を保存 P できますが、P> 3 ではこのモードの精度が失われます。

3.2.5.3.2. TIMESTAMP 値

TIMESTAMP タイプは、タイムゾーン情報がないタイムスタンプを表します。このような列は、UTC を基にして同等の Kafka Connect 値に変換されます。たとえば、「2018-06-20 15:13:16.945104」の TIMESTAMP 値 time.precision.mode は、「1529507596945104」の値 io.debezium.time.MicroTimestamp で表されます（がに設定されていません connect）。

Kafka Connect および Debezium を実行している JVM のタイムゾーンはこの変換には影響しないことに注意してください。

3.2.5.3.3. 10 進数の値

decimal.handling.mode 設定プロパティーがに設定された場合 precise、コネクターはすべての DECIMAL および NUMERIC 列に事前定義された Kafka Connect の org.apache.kafka.connect.data.Decimal 論理タイプを使用します。これがデフォルトのモードです。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

NUMERIC[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

scaled schema パラメーターには、変更する 10 進数の数字を表す整数が含まれます。

DECIMAL[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

scaled schema パラメーターには、変更する 10 進数の数字を表す整数が含まれます。

このルールには例外があります。NUMERIC または DECIMAL タイプをスケール制約なしで使用すると、データベースから送信される値は値ごとに異なる（バリアント可能な）スケーリングになります。この場合、タイプ io.debezium.data.VariableScaleDecimal が使用され、転送された値の値とスケールの両方が含まれます。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

NUMERIC

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値 scale のスケールと、スケーリングされていない形式で元の値が INT32 含ま BYTES れるタイプ value の 2 つのフィールドが含まれる構造が含まれています。

DECIMAL

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値 scale のスケールと、スケーリングされていない形式で元の値が INT32 含ま BYTES れるタイプ value の 2 つのフィールドが含まれる構造が含まれています。

しかし、設定プロパティーがに decimal.handling.mode 設定された場合 double、コネクターはすべて DECIMAL および NUMERIC 値をすべて Java の二重値として表し、以下のようにエンコードします。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

NUMERIC[(M[,D])]

FLOAT64

  

DECIMAL[(M[,D])]

FLOAT64

  

decimal.handling.mode 設定プロパティーの最後のオプションはです string。この場合、コネクターはすべての DECIMAL および NUMERIC 値をフォーマットされた文字列表現として表現し、以下のようにエンコードします。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

NUMERIC[(M[,D])]

STRING

  

DECIMAL[(M[,D])]

STRING

  

PostgreSQL は、DECIMAL/ の値に格納するための特殊なNUMERIC 値 NaN （数字ではありません）に対応します。このような値のみ string および double モードは、それらを Double.NaN または文字列定数としてエンコードでき NANます。

3.2.5.3.4. HStore の値

hstore.handling.mode 設定プロパティーが json （デフォルト）に設定されると、コネクターはすべてすべての値を文字列指定された JSON HSTORE 値として解釈し、以下のようにエンコードします。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

HSTORE

STRING

io.debezium.data.Json

例： JSON コンバーターを使用した出力表現は、です。 {\"key\" : \"val\"}

hstore.handling.mode 設定プロパティーがに設定された場合 map、コネクターはすべての HSTORE 列に MAP スキーマタイプを使用します。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

HSTORE

MAP

 

例： JSON コンバーターを使用した出力表現は、です。 {"key" : "val"}

3.2.5.4. PostgreSQL ドメインタイプ

PostgreSQL は、他の基礎となるタイプに基づくユーザー定義型の概念もサポートします。そのような列タイプが使用される場合、Debezium は完全なタイプ階層を基にコラムの表示を公開します。

重要

ドメインタイプを使用する列を監視する場合は、特別な考慮を検討する必要があります。

デフォルトのデータベースタイプのいずれかを拡張し、ドメインタイプがカスタムの長さ/スケールを定義するドメインタイプを使用して列を定義する場合、生成されたスキーマはその定義された長さ/スケールを継承します。

カスタムの長さ/スケールを定義する別のドメインタイプを拡張するドメインタイプを使用して列を定義すると、生成されたスキーマは PostgreSQL ドライバーの列メタデータの実装により定義された長さ/スケールを継承し ません。

3.2.5.4.1. ネットワークアドレスの種別

PostgreSQL には、IPv4、IPv6、および MAC アドレスを保存できるデータタイプもあります。これらのタイプは入力エラーの確認や特殊な Operator および関数を提供するため、プレーンテキストの種別ではなくこれらのネットワークアドレスを保存する方が適切です。

PostgreSQL データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

INET

STRING

 

IPv4 ネットワークおよび IPv6 ネットワーク

CIDR

STRING

 

IPv4、IPv6 ホストおよびネットワーク

MACADDR

STRING

 

MAC アドレス

MACADDR8

STRING

 

EUI-64 形式の MAC アドレス

3.2.5.4.2. PostGIS タイプ

PostgreSQL コネクターは、すべての PostGIS データタイプの完全サポートも提供します。http://postgis.net

PostGIS データタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

GEOMETRY
（プレーン）

STRUCT

io.debezium.data.geometry.Geometry

2 つのフィールドを持つ構造が含まれます。

  • srid (INT32) : 構造にどのタイプのジオメトリーオブジェクトが格納されているかを定義するリファレンスシステム識別子
  • wkb (BYTES) : binary-Known-Binary 形式でエンコードされたgemetry オブジェクトのバイナリー表現。形式の詳細は、「 Open Geospatial Consortium Simple Features Access specification 」を参照してください。

GEOGRAPHY
(Spherical)

STRUCT

io.debezium.data.geometry.Geography

2 つのフィールドを持つ構造が含まれます。

  • srid (INT32) : 構造に保管される地理的オブジェクトタイプを定義する「参照システム識別子」
  • wkb (BYTES) : binary-Known-Binary 形式でエンコードされたgemetry オブジェクトのバイナリー表現。形式の詳細は、「 Open Geospatial Consortium Simple Features Access specification 」を参照してください。
3.2.5.4.3. 重要の値

PostgreSQL のページサイズにはハード制限があります。つまり、ca. 8 KB を超える値は TOAST ストレージ を使用して保存する必要があります。TOAST メカニズムを使用して保存されていて変更されていない値は、テーブルのレプリカアイデンティティーの一部でない限り、メッセージには含まれないため、これはデータベースからのレプリケーションメッセージに影響します。Debezium が不足している値をデータベースから直接読み込むことは安全ではありません。これは競合状態が発生する可能性があるためです。そのため、Debezium は以下のルールに従って、これらの値を処理します。

  • TOAST 列の表は、他の列として変更イベント before および after ブロックの一部です REPLICA IDENTITY FULL。
  • テーブル REPLICA IDENTITY DEFAULT: データベースから UPDATE イベントを受信すると、レプリカ ID の一部ではない TOAST 列値はそのイベントの一部ではありません。同様に、イベントを受信すると DELETE、TOAST 列は before ブロックの一部ではありません。この場合、Debezium は列の値を安全に提供できないため、設定オプションで定義されたプレースホルダーの値が返され toasted.value.placeholderます。
重要

Amazon RDS インスタンスには特定の問題があります。wal2json プラグインは一定期間にわたって進化し、帯域外の値を提供するリリースがありました。Amazon では、PostgreSQL バージョンごとに異なるバージョンのプラグインがサポートされます。Amazon の ドキュメント を参照して、バージョンからバージョンマッピングを取得してください。一貫性のある値の処理のために、以下を行うことが推奨されます。

  • PostgreSQL 10+ インスタンスの pgoutput プラグインの使用
  • slot.stream.params 設定オプションを使用して、wal2json プラグインの以前のバージョン include-unchanged-toast=0 に対して設定

3.3. PostgreSQL コネクターのデプロイ

PostgreSQL コネクターのインストールは、JAR のみのダウンロード、Kafka Connect 環境への抽出、および Kafka Connect 環境でプラグインの親ディレクトリーが指定されていることを確認する簡単なプロセスです。

前提条件

手順

  1. Debezium 1.1.3 PostgreSQL コネクター をダウンロードします。
  2. ファイルを Kafka Connect 環境に抽出します。

  3. プラグインの親ディレクトリーを Kafka Connect に追加し plugin.pathます。 

    plugin.path=/kafka/connect
注記

上記の例では、Debezium PostgreSQL コネクターを /kafka/connect/Debezium-connector-postgresql パスに抽出していることを前提としています。

  1. Kafka Connect プロセスを再起動します。これにより、新しい JAR が確実に検出されます。

関連情報

デプロイメントプロセスおよび AMQ Streams でのコネクターのデプロイに関する詳細は、『Debezium インストールガイド』を参照してください。

3.3.1. 設定例

コネクターを使用して特定の PostgreSQL サーバーまたはクラスターの変更イベントを生成するには、以下を実行します。

  1. 論理デコードプラグインのインストール
  2. 論理レプリケーションに対応するように PostgreSQL サーバー を設定します。
  3. PostgreSQL コネクターの設定ファイルを作成します。

コネクターが起動すると、PostgreSQL サーバーのデータベースの一貫したスナップショットを取得し、変更をストリーミングし、挿入、更新、および削除される各行に対してイベントを生成します。スキーマおよびテーブルのサブセットのイベントを生成することもできます。任意で、機密性の高い、大きすぎる、または必要でないコラムを無視し、マスク、または切り捨てられます。

以下は、192.168.99.100 のポート 5432 で PostgreSQL サーバーを監視する PostgreSQL コネクターの設定例です fullfillment。通常、コネクターで使用できる設定プロパティーを使用して、.yaml ファイルに Debezium PostgreSQL コネクターを設定します。 

apiVersion: kafka.strimzi.io/v1beta1
  kind: KafkaConnector
  metadata:
    name: inventory-connector  1
    labels: strimzi.io/cluster: my-connect-cluster
  spec:
    class: io.debezium.connector.postgresql.PostgresConnector
    tasksMax: 1  2
    config:  3
      database.hostname: postgresqldb   4
      database.port: 5432
      database.user: debezium
      database.password: dbz
      database.dbname: postgres
      database.server.name: fullfillment   5
      database.whitelist: public.inventory   6
1
コネクターの名前。
2
1 度に操作する必要があるタスクは 1 つだけです。PostgreSQL コネクターは PostgreSQL サーバーの読み取りを行うため binlog、単一のコネクタータスクを使用すると適切な順序とイベント処理が確保されます。Kafka Connect サービスはコネクターを使用して作業を行う 1 つ以上のタスクを開始し、Kafka Connect サービスのクラスター全体に実行中のタスクを自動的に分散します。いずれかのサービスが停止またはクラッシュすると、そのタスクは実行中のサービスに再分配されます。
3
コネクターの設定。
4
データベースホスト。これは、PostgreSQL サーバー(postgresqldb)を実行しているコンテナーの名前です。
5
一意のサーバー名。サーバー名は、サーバーの PostgreSQL サーバーまたはクラスターの論理識別子です。この名前は、すべての Kafka トピックの接頭辞として使用されます。
6
public.inventory データベースの変更のみが検出されます。

これらの設定で指定できる コネクタープロパティーの完全なリスト を参照してください。

この設定は、POST から稼働中の Kafka Connect サービスに送信できます。これにより、設定を記録し、PostgreSQL データベースに接続し、イベントを Kafka トピックに記録する 1 つのコネクタータスクを開始します。

3.3.2. モニタリング

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

JMX でこれらのメトリクスを公開する方法については、モニタリングドキュメント を参照してください。

3.3.2.1. スナップショットメトリクス

MBean はです debezium.postgres:type=connector-metrics,context=snapshot,server=<database.server.name>。

属性名

型

説明

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

TotalTableCount

int

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

RemainingTableCount

int

スナップショットがコピーしたテーブルの数。

SnapshotRunning

boolean

スナップショットが起動しているかどうか。

SnapshotAborted

boolean

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

SnapshotCompleted

boolean

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

SnapshotDurationInSeconds

long

スナップショットが完了しなかった場合でも、これまでスナップショットが取得した秒数の合計数。

RowsScanned

Map<String, Long>

スナップショットの各テーブルに対してスキャンされる行数が含まれるマップ。テーブルは処理中にマップに徐々に追加されます。テーブルの完了後にスキャンされた 10,000 行をすべて更新します。

3.3.2.2. ストリーミングメトリクス

MBean はです debezium.postgres:type=connector-metrics,context=streaming,server=<database.server.name>。

属性名

型

説明

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

Connected

boolean

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

MilliSecondsBehindSource

long

最後に変更イベントのタイムスタンプとコネクターの処理の間隔（ミリ秒単位）。値には、データベースサーバーとコネクターが実行されているマシンのクロック間の違いが反映されます。

NumberOfCommittedTransactions

long

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

SourceEventPosition

map<string, string>

最後に受信したイベントのコーディネート。

LastTransactionId

string

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

3.3.3. コネクタープロパティー

以下の設定プロパティーは、デフォルト値が利用可能でない限り 必要 になります。

プロパティー

デフォルト

説明

name

 

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

connector.class

 

コネクターの Java クラスの名前。PostgreSQL コネクターに常にの値を使用 io.debezium.connector.postgresql.PostgresConnector してください。

tasks.max

1

このコネクターに作成する必要のあるタスクの最大数。PostgreSQL コネクターは常に単一のタスクを使用するため、この値は使用されないため、デフォルト値は常に受け入れ可能です。

plugin.name

decoderbufs

サーバーに インストールされている Postgres の論理 デコードプラグインの名前。サポートされている値はのみです pgoutput。

処理されたトランザクションが非常に大きい場合、トランザクションのすべての変更を含む JSON バッチイベントは、サイズが 1 GB のハードコーディングされたメモリーバッファーに収まらない可能性があります。このような場合、トランザクションの変更が すべて PostgreSQL から Debezium に別のメッセージとして送信されると、ストリーミングモードと呼ばれるストリーミングモードに切り替えることができます。

slot.name

debezium

プラグインおよびデータベースインスタンスからの変更ストリーミング用に作成された Postgres の論理デコードスロットの名前。値は Postgres レプリケーションスロットの命名ルール に準拠する必要があります。"Each レプリケーションスロットには、小文字、数字、およびアンダースコアを含めることができます。

slot.drop.on.stop

false

コネクターが順次終了する際に論理レプリケーションスロットをドロップするかどうか。テストまたは開発環境 true でのみ、をに設定してください。スロットを削除すると、データベースが WAL セグメントを破棄できるため、再起動後、前の WAL 位置からコネクターを再開できないことがあります。

publication.name

dbz_publication

の使用時にストリーミングの変更用に作成された PostgreSQL 公開の名前 pgoutput。

すべてのテーブル を含めるようにまだない場合、このパブリッシュは起動時に作成されます。その後、Debezium は独自のホワイトリスト/ブラックリストのフィルタリング機能を使用して、変更イベントを設定した場合の特定のテーブルに制限します。このパブリッシュを作成するには、コネクターユーザーにスーパーユーザー権限を持っている必要があるため、通常は前のパブリッシュを作成することが推奨されます。

パブリッシュがすでに存在する場合（すべてのテーブルまたはテーブルのサブセットで設定されている場合）、Debezium は定義したパブリッシュを使用します。

database.hostname

 

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

database.port

5432

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

database.user

 

PostgreSQL データベースサーバーに接続するときに使用する PostgreSQL データベースの名前。

database.password

 

PostgreSQL データベースサーバーに接続するときに使用するパスワード。

database.dbname

 

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

database.server.name

 

監視対象の特定の PostgreSQL データベースサーバーまたはクラスターの namespace を特定して提供する論理名。このコネクターから送信されるすべての Kafka トピック名の接頭辞として使用されるため、論理名は他のすべてのコネクターで一意にする必要があります。英数字とアンダースコアのみを使用してください。

schema.whitelist

 

監視するスキーマ名に一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないスキーマ名は監視から除外されます。デフォルトでは、システム以外のスキーマはすべて監視されます。とは使用されない場合があり schema.blacklistます。

schema.blacklist

 

監視から除外されるスキーマ名に一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないスキーマ名は、システムスキーマを除き監視されます。とは使用されない場合があり schema.whitelistます。

table.whitelist

 

監視するテーブルの完全修飾テーブル識別子と一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないテーブルはすべて監視から除外されます。各識別子は schemaName.tableName の 形式 です。デフォルトでは、コネクターは監視される各スキーマのすべてのシステムテーブルを監視します。とは使用されない場合があり table.blacklistます。

table.blacklist

 

監視から除外されるテーブルの完全修飾テーブル識別子と一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないテーブルはすべて監視されます。各識別子は schemaName.tableName の 形式 です。とは使用されない場合があり table.whitelistます。

column.blacklist

 

変更イベントメッセージ値から除外される必要のある列の完全修飾名に一致する正規表現のオプションのコンマ区切りリスト。カラムの完全修飾名は schemaName.tableName . columnName 形式です。

time.precision.mode

adaptive

時間、日付、およびタイムスタンプは、異なるタイプの精度で表示できます。たとえば、adaptive （デフォルト）は、データベースの列のタイプに基づいてミリ秒、マイクロ秒、ナノ秒のいずれかを使用してデータベース内で時間とタイムスタンプの値を正確に adaptive_time_microseconds キャプチャーします。 日時およびタイムスタンプの値は、データベース列のタイプに基づくミリ秒、マイクロ秒、またはナノ秒（常にマイクロ秒としてキャプチャーされる TIME タイプのフィールドを除く）を使用するか、connect 常に Kafka Connect の組み込み表現を使用した時間およびタイムスタンプの値を表します。これは、データベース列の精度に関係なくミリ秒値を使用します。「 一時値 」を参照してください。

decimal.handling.mode

precise

コネクターが DECIMAL および NUMERIC 列の値を処理する方法を指定します。precise （デフォルト）は、バイナリー形式で変更イベントを表す java.math.BigDecimal 値を使用して正確に double 表すか、または double 値を使用して表します。これにより精度が失われますが、使用が非常に容易になります。string オプションはフォーマットされた文字列としてエンコードされますが、実際のタイプのセマンティック情報は失われます。「10 進数の値」を参照してください。

hstore.handling.mode

map

コネクターが hstore 列の値を処理する方法を指定します json string。map （デフォルト）はを使用して json 表す MAPか、などのフォーマットされた文字列として値をjson エンコードします {"key" : "val"}。「HStore の値」を参照してください。

interval.handling.mode

numeric

コネクターが interval 列の値を処理する方法を指定します。numeric （デフォルト）はマイクロ秒数を使用する間隔を string 表します。たとえば、文字列パターン表現（ P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S例：）を使用して正確に表します P1Y2M3DT4H5M6.78S。「データタイプ」を参照してください。

database.sslmode

disable

PostgreSQL サーバーへの暗号化された接続を使用するかどうか。オプションは、暗号化されていない接続を使用する disable （デフォルト）です。安全（暗号化）接続を 使用 し、確立できない場合は失敗します。ただし require、設定した認証局(CA)証明書に対してサーバー TLS 証明書を検証することもできます。 または、有効な一致する CA 証明書が見つからない場合に失敗します。verify-full と同様に、サーバー証明書 verify-ca が接続を試行するホストと一致することを確認してください。詳細は PostgreSQL のドキュメント を参照してください。

database.sslcert

 

クライアントの SSL 証明書が含まれるファイルへのパス。詳細は PostgreSQL のドキュメント を参照してください。

database.sslkey

 

クライアントの SSL 秘密鍵が含まれるファイルへのパス。詳細は PostgreSQL のドキュメント を参照してください。

database.sslpassword

 

で指定されたファイルからクライアントの秘密鍵にアクセスするためのパスワード database.sslkey。詳細は PostgreSQL のドキュメント を参照してください。

database.sslrootcert

 

サーバーが検証されるルート証明書が含まれるファイルへのパス。詳細は PostgreSQL のドキュメント を参照してください。

database.tcpKeepAlive

 

TCP keep-alive プローブを有効にして、データベース接続がまだ有効であることを確認します（デフォルトでは有効化）。詳細は PostgreSQL のドキュメント を参照してください。

tombstones.on.delete

true

削除イベントの後に tombstone イベントを生成するかどうかを制御します。
削除操作 true が削除イベントと後続の tombstone イベントによって表される場合。削除イベント false のみを送信する場合。
tombstone イベント（デフォルトの動作）を生成すると、Kafka はソースレコードが削除されると、指定のキーに関連するすべてのイベントを完全に削除できます。

column.truncate.to.length.chars

該当なし

フィールドの値が指定された文字数よりも長い場合に、変更イベントメッセージの値で切り捨てられる必要のある文字ベースの列の完全修飾名に一致する正規表現のオプションのコンマ区切りリスト。異なる長さを持つ複数のプロパティーを 1 つの設定で使用できますが、それぞれの長さは正の整数である必要があります。カラムの完全修飾名は schemaName.tableName . columnName 形式です。

column.mask.with.length.chars

該当なし

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

column.propagate.source.type

該当なし

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

datatype.propagate.source.type

該当なし

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

message.key.columns

空の文字列

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

以下の 高度な 設定プロパティーには、ほとんどの場合で動作するため、コネクターの設定で指定する必要はほとんどありません。

プロパティー

デフォルト

説明

snapshot.mode

initial

コネクターの起動時にスナップショットを実行する基準を指定します。デフォルトは 初期 で、ターゲットサーバー名にオフセットが記録されていない場合に限り、コネクターがスナップショットを実行できることを指定します。always オプションは、起動時に毎回コネクターがスナップショットを実行するように指定します。never オプションは、接続がスナップショットを使用せず、最初に論理サーバー名で起動すると、コネクターが最後に残された場所（最後の LSN 位置）から読み取られるか、論理レプリケーションスロットのビューから開始するように指定します。initial_only オプションは、後続の変更を処理せずに、コネクターが最初のスナップショットのみを取得してから停止するよう指定します。エクスポート したオプションは、データベーススナップショットがレプリケーションスロットの作成時にその時点に基づいており、ロックなしの方法でスナップショットを実行するのに非常に適しています。

snapshot.lock.timeout.ms

10000

スナップショット実行時にテーブルロックの取得を待つ最大時間（ミリ秒単位）を指定する正の整数値。この時間帯にテーブルロックを取得できないと、スナップショットは失敗します。スナップショットの表示

snapshot.select.statement.overrides

 

スナップショットに含まれるテーブルからの行を制御します。
このプロパティーには、完全修飾テーブルのコンマ区切りリスト( DB_NAME.TABLE_NAME) が含まれます。個々のテーブルの select ステートメントは、追加の設定プロパティーで指定され、各テーブルの 1 つずつ、ID によって識別されます snapshot.select.statement.overrides.[DB_NAME].[TABLE_NAME]。これらのプロパティーの値は、スナップショット中に特定のテーブルからデータを取得する際に使用する SELECT ステートメントになります。大規模な追加のみのテーブルのユースケースとして、以前のスナップショットが中断された場合に、スナップショットを開始（再開）する特定のポイントを設定することが挙げられます。
注記： この設定は、スナップショットにのみ影響します。論理デコーダーによって生成されたイベントは影響を受けません。

event.processing​.failure.handling.mode

fail

イベントの処理中にコネクターが例外に応答する方法を指定します fail （問題のあるイベントのオフセットを示唆）、コネクターが停止します
warn。は、問題のあるイベントが省略され、問題のあるイベントのオフセットがログに記録される原因と
skip なります。は、問題のあるイベントをスキップします。

max.queue.size

20240

ストリーミングレプリケーションを介して受信される変更イベントが Kafka に書き込まれる前に配置されるブロックキューの最大サイズを指定する正の整数値。このキューは、たとえば Kafka への書き込みが遅い場合や Kafka が利用できない場合などに抑制を提供できます。

max.batch.size

10240

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

poll.interval.ms

1000

新しい変更イベントが表示されるまでコネクターが待機する時間（ミリ秒単位）を指定する正の整数値。デフォルトは 1000 ミリ秒または 1 秒です。

include.unknown.datatypes

false

Debezium がデータタイプが不明なフィールドを満たしている場合、デフォルトではフィールドは変更イベントから省略され、警告がログに記録されます。フィールドを組み込んで、不透明なバイナリー表現のクライアントにダウンストリームを送信して、クライアントがそれをデコードする方が望ましい場合もあります。不明なデータ false をフィルターし、それらをバイナリー形式で維持 true するには、に設定します。

注記

クライアントは後方互換性の問題をリスクとします。データベース固有のバイナリー表示の変更だけでなく、データタイプが Debezium によってサポートされる場合は、論理タイプでダウンストリームが送信され、コンシューマーによる調整が必要になります。通常、サポートがサポートされていないデータタイプが発生した場合は、機能要求を報告してサポートを追加してください。

database.initial.statements

 

データベースへの JDBC 接続（トランザクションログ読み取り接続ではなく）が確立されたときに実行する SQL ステートメントのセミコロン区切りリスト。セミコロン(';')を区切り文字として使用し、セミコロンを文字として使用する場合は 2 倍のセミコロン(';')を使用します。

注記

コネクターはそれぞれの判断で JDBC 接続を確立する可能性があるため、これは通常セッションパラメーターの設定のみに使用し、DML ステートメントの実行には使用しないでください。

heartbeat.interval.ms

0

ハートビートメッセージを送信する頻度を制御します。
このプロパティーには、コネクターがハートビートトピックにメッセージを送信する頻度を定義する間隔（ミリ秒単位）が含まれます。これは、コネクターがデータベースから変更イベントを受信しているかどうかを監視するために使用できます。また、キャッシュされていないテーブルのレコードのみが長くなる場合には、ハートビートメッセージも利用する必要があります。このような状況では、コネクターは引き続きデータベースからログを読み取るが、Kafka に変更メッセージを出力せず、オフセットの更新が Kafka にコミットされないことを意味します。これにより、WAL ファイルが必要なよりも長い時間保持されます（コネクターはすでに処理済みですが、最新の取得した LSN をデータベースにフラッシュする可能性があるため）、コネクターの再起動後により多くの変更イベントを再送信する可能性があります。ハートビートメッセージを送信しないよう 0 に、このパラメーターをに設定します。
デフォルトでは無効です。

heartbeat.topics.prefix

__debezium-heartbeat

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

heartbeat.action.query

 

指定されている場合、このクエリーはソースデータベースに対してハートビートごとに実行されます。

これは、「 WAL Disk Space Consumption 」で説明されている状況に対処するために使用できます。この場合、トラフィックの多いデータベースで低トラフィックのデータベースから変更をキャプチャーし、Debezium が WAL レコードを処理しなくなり、データベースで WAL ポジションを取得できなくなります。

一部のハートビートテーブルにレコードを挿入すると（上述の手順で作成されている必要がある）、コネクターは低トラフィックのデータベースから変更を受信し、その LSN を認識して、データベースホストのバインドされていない WAL 増加を防ぎます。

例: INSERT INTO test_heartbeat_table (text) VALUES ('test_heartbeat')

schema.refresh.mode

columns_diff

テーブルのインメモリースキーマの更新をトリガーする条件を指定します。

columns_diff （デフォルト）は最も安全なモードで、インメモリースキーマは常にデータベーステーブルのスキーマと同期し続けます。

columns_diff_exclude_unchanged_toast TOASTable データの変更が不適切に行われない限り、受信メッセージから派生するスキーマと不一致がある場合は、コネクターにインメモリースキーマキャッシュを更新するよう指示します。

この設定は、このような更新の一部はほとんどない TOASTed データを持つテーブルが頻繁に更新される場合に、コネクターのパフォーマンスを大幅に向上します。ただし、TOASTable の列がテーブルからドロップされると、インメモリースキーマが古い状態になる可能性があります。

snapshot.delay.ms

 

起動後のスナップショットの取得前にコネクターが待機する間隔（ミリ秒単位）
。クラスターで複数のコネクターを起動する際にスナップショットの中断を回避するために使用できます。コネクターのリバランスが発生する可能性があります。

snapshot.fetch.size

10240

スナップショットの作成中に、各テーブルから 1 回読み込むべき行の最大数を指定します。コネクターはこのサイズの複数のバッチでテーブルコンテンツを読み取ります。デフォルトは 10240 です。

slot.stream.params

 

設定した論理デコードプラグインに渡されるパラメーターのオプションの一覧です。例: add-tables=public.table,public.table2;include-lsn=true

sanitize.field.names

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

フィールド名が Avro 命名要件に準拠するようにサニタイズされるかどうか。詳細は、「 Avro の命名 」を参照してください。

slot.max.retries

6

試行に失敗するときにレプリケーションスロットへの接続を再試行する回数。

slot.retry.delay.ms

10000（10 秒）

コネクターがレプリケーションスロットへの接続に失敗したときに再試行の間隔を待つミリ秒数。

toasted.value.placeholder

__debezium_unavailable_value

Debezium が提供する定数を指定し、元の値がデータベースから提供されない値であることを示します。hex: 接頭辞で始まる場合、残りの文字列は 16 進法でエンコードされた octets に再送されることが想定されます。詳細は、「 未通知の値 」を参照してください。

provide.transaction.metadata

false

true Debezium に設定すると、トランザクション境界でイベントが生成され、トランザクションメタデータでデータイベントが強化されます。

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

コネクターは、Kafka プロデューサーおよびコンシューマーの作成時に使用される パススルー 設定プロパティーもサポートします。

Kafka プロデューサーおよびコンシューマーのすべての設定プロパティーについては、Kafka のドキュメント を参照してください。PostgreSQL コネクターは 新しいコンシューマー を使用します。

3.4. PostgreSQL 典型的な問題

Debezium は、複数のアップストリームデータベースの変更をすべてキャプチャーし、イベントの失敗や損失は発生しない分散システムです。当然ながら、システムが規則的な動作や管理を慎重に行なっ ている場合、Debezium はすべての変更イベントの配信を一度 提供します。ただし、障害が発生すると、システムはイベントを失いませんが、障害からの復旧中は変更イベントを繰り返す可能性があります。そのため、Kafka などのこのような異常な状況 では、少なくとも 1 回 変更イベントが配信されます。

本セクションの残りの部分では、Debezium が様々な障害や問題を処理する方法について説明します。

3.4.1. 設定および起動エラー

コネクターは起動時に失敗し、ログにエラー/例外を報告し、コネクターの設定が無効であるときに実行を停止し、コネクターが指定の接続パラメーターを使用して PostgreSQL に正常に接続できない場合、または PostgreSQL が事前記録された位置（LSN 値を介して）から再開する場合や、PostgreSQL にその履歴が利用できない場合に、実行を停止します。

このような場合、エラーには問題の詳細が記載され、推奨される回避策が考えられます。設定が修正され、PostgreSQL の問題が対処されると、コネクターを再起動することができます。

3.4.2. PostgreSQL Becomes Unavailable

コネクターが稼働したら、接続した PostgreSQL サーバーが何らかの理由で利用できなくなると、コネクターはエラーを出して失敗し、コネクターは停止します。サーバーが利用可能になるとコネクターを再起動するだけです。

PostgreSQL コネクターは、最後に処理されたオフセット（PostgreSQL log sequence number 値の形式で）外部に保存します。コネクターが再起動し、サーバーインスタンスに接続すると、その特定のオフセットからストリーミングを継続するようサーバーへ要求されます。Debezium レプリケーションスロットが非アクティブのままである限り、このオフセットは常に利用可能のままになります。プライマリーでレプリケーションスロットを削除しないでください。削除しないと、データが失われます。スロットが削除された場合の障害ケースについては、次の項を参照してください。

3.4.3. Cluster Failures

PostgreSQL では 12、レプリカスロットは プライマリーサーバーでのみ許可され ます。つまり、PostgreSQL コネクターはデータベースクラスターのアクティブなプライマリーのみを参照できます。また、レプリケーションスロット自体もレプリカに伝播されません。プライマリーノードがダウンした場合、新しいプライマリーをプロモート（ 論理デコードプラグインがインストールされ ている）とレプリケーションスロットが作成されると、コネクターを再起動して新しいサーバーを参照できます。

フェイルオーバーは重要な注意事項がいくつかあります。また、データを損失していないレプリケーションスロットがあることを確認できるまで、Debezium を一時停止する必要があります。フェイルオーバーの後、フェイルオーバーの管理がない限り、アプリケーションが 新しい プライマリーへの書き込みを許可する前に Debezium レプリケーションスロットを再作成するプロセスが含まれない限り、変更イベントが失われます。また、フェイルオーバーの状況において、Debezium が 以前のプライマリーが失敗する前 にスロットのすべての変更を読み取ることができることを検証する必要がある場合もあります。

失われた変更を回復および検証する信頼できる方法の 1 つとして、障害が発生したプライマリーのバックアップを、障害の発生した直前のポイントに復元することです。これにより、レプリケーションスロットを、消費されていない変更の有無を検査できます。いずれの場合も、書き込みを許可する前に、新しいプライマリーでレプリケーションスロットを再作成する必要があります。

3.4.4. Kafka Connect Process の正常な停止

Kafka Connect を分散モードで実行しており、Kafka Connect プロセスが正常に停止した場合、そのプロセスのコネクタータスクをグループ内の別の Kafka Connect プロセスに移行し、新しいコネクタータスクは以前のタスクが除外された場所をそのまま取得します。コネクタータスクが正常に停止され、新しいプロセスで再起動される間、処理には短い遅延が生じます。

3.4.5. Kafka Connect プロセスクラッシュ

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

注記

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

Debezium には、各変更イベントの発生元に関するソース固有の情報も含まれています。これには、PostgreSQL サーバーの時間、サーバートランザクションの ID、トランザクションの変更先のログの位置が含まれます。コンシューマーは、この情報（特に LSN 位置）を追跡し、特定のイベントをすでに確認しているかどうかを確認できます。

3.4.6. Kafka Becomes Unavailable

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

3.4.7. コネクターが期間停止する

コネクターが正常に停止されると、データベースは引き続き使用され、新しい変更は PostgreSQL WAL に記録されます。コネクターを再起動すると、最後に停止した場所の変更のストリーミングを再開し、コネクターが停止した際に加えられたすべての変更についての変更イベントを記録します。

Kafka クラスターが適切に設定されていると、大きなスループットを処理できます。Kafka Connect は Kafka のベストプラクティスで記述され、十分なリソースが非常に多くのデータベース変更イベントを処理できます。そのため、しばらくコネクターが再起動されると、Kafka の機能とパフォーマンスと PostgreSQL のデータに加えられた変更のボリュームにどの程度迅速に適用されるかに関連します。

第4章 MongoDB の Debezium Connector

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

4.1. 概要

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

MongoDB レプリカセットは、すべて同じデータのコピーを持つサーバーセット から構成され、レプリケーションにより、クライアントがレプリカセットのプライマリードキュメントに対して加えたすべての変更が、別のレプリカセットのサーバー（セカンダリー）に 正しく 適用されるようにし ます。MongoDB レプリケーションは、プライマリーレコードを oplog （ または操作ログ）に記録することで機能します。次に、各秒はプライマリーの oplog を読み取り、すべての操作を独自のドキュメントに読み込みます。レプリカセットに新しいサーバーを追加すると、そのサーバーは最初にプライマリー上のすべてのデータベースおよびコレクションの スナップショット を実行して、プライマリーの oplog を読み取り、スナップショットの作成以降に追加された可能性のあるすべての変更を適用します。この新しいサーバーは、プライマリーの oplog の末尾に追い付くとセカンダリー（クエリーを処理する）になります。

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

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

MongoDB コネクターは、レプリカセットのメンバーシップやリーダーの変更、シャードの追加または削除、および通信の失敗を引き起こす可能性のあるネットワークの問題に非常に耐性があります。コネクターは常にレプリカセットのプライマリーノードを使用して変更をストリーミングします。そのため、レプリカセットの選択が行われ、異なるノードがプライマリー状態になると、コネクターは即座にストリーミングを停止し、新しいプライマリーノードに接続し、新しいプライマリーノードを使用して変更をストリーミングを開始します。同様に、コネクターがレプリカセットのプライマリーとの通信に問題がある場合には、再接続を試みます（ネットワークまたはレプリカセットをオーバーコミットしないようにするために使用されるため）、最後に停止した場所から変更のストリーミングを継続します。これにより、コネクターはレプリカセットメンバーシップの変更に動的に調整し、通信の失敗を自動的に処理できます。

関連情報

4.2. MongoDB の設定

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

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

4.3. サポートされている MongoDB トポロジー

MongoDB コネクターは、さまざまな MongoDB トポロジーと使用できます。

4.3.1. MongoDB レプリカセット

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

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

注記

MongoDB がプロキシー（OS X や Windows の Docker など）での前にある場合、クライアントがレプリカセットに接続してメンバーを検出すると、MongoDB クライアントはプロキシーを有効なメンバーとして除外し、プロキシーを通過せずに直接メンバーへの接続を試みます。

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

4.3.2. MongoDB シャードクラスター

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

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

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

4.3.3. MongoDB スタンドアロンサーバー

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

注記

4.4. MongoDB コネクターの仕組み

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

注記

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

4.4.1. 論理コネクター名

コネクター設定プロパティーは、MongoDB レプリカセットまたはシャードクラスターの 論理名 として mongodb.name 機能します。コネクターは論理名を複数の方法で使用します。すべてのトピック名の接頭辞として、および各レプリカセットの oplog 位置の記録時には一意の識別子として使用されます。

各 MongoDB コネクターには、ソース MongoDB システムを説明する一意の論理名を指定する必要があります。論理名はアルファベット文字またはアンダースコアで始まり、英数字またはアンダースコア（小文字）の残りの文字で始まります。

4.4.2. スナップショットの実行

タスクがレプリカセットを使用して開始すると、コネクターの論理名とレプリカセット名を使用して、コネクターが変更の読み取りを以前に停止した位置を示す オフセット を見つけます。オフセットが見つかり、これが oplog に存在する場合は、そのタスクは、記録されたオフセットの位置からすぐに ストリーミングの変更 を続行します。

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

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

注記

コネクターがレプリカセットのスナップショットを実行している間は、タスクの再割り当ておよび再設定が行われないようにします。コネクターは、スナップショットの進捗と共にログメッセージを実行します。各コネクターの Kafka Connect の別個のクラスターをほぼ制御するには、コネクターごとに実行します。

4.4.3. ストリーミングの変更

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

コネクターが正常に停止されると、処理された最後のオフセットが記録され、再起動すると、コネクターはそのまま停止した場所をそのまま保持します。ただし、コネクターのタスクが突然終了した場合、タスクは最後にオフセットを記録した後に、最後のオフセットが記録される前に処理および生成されたイベントが発生した可能性があります。再起動すると、コネクターは最後に 記録 されたオフセットから開始し、クラッシュの直前に生成された同じイベントが生成される可能性があります。

注記

すべてが正常に動作している場合、Kafka コンシューマーは実際にすべてのメッセージ が 1 度だけ 表示されます。ただし、Kafka に誤りが発生すると、最低でも 1 度 だけすべてのメッセージがコンシューマーに表示されることを保証できます。そのため、コンシューマーはメッセージを複数回認識していることを予想する必要があります。

上記のように、コネクタータスクは常にレプリカセットのプライマリーノードを使用して oplog から変更をストリーミングし、コネクターが可能な限り最新の操作を認識するようにし、代わりに 2 つのデータが使用される場合よりも低いレイテンシーで変更をキャプチャーできます。レプリカセットが新しいプライマリーを選択すると、コネクターはストリーミングの変更を停止し、新しいプライマリーに接続し、新しいプライマリーノードからの変更のストリーミングを開始します。同様に、コネクターがレプリカセットのメンバーと通信する際に問題が発生した場合に、指数関数的バックオフを使用してレプリカセットに過重なバックオフを行わないようにし、接続すると、最後に完了した場所から変更がストリーミングを継続します。これにより、コネクターはレプリカセットメンバーシップの変更に動的に調整し、通信の失敗を自動的に処理できます。

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

4.4.4. トピック名

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

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

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

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

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

4.4.5. パーティション

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

Kafka は、1 つのトピックパーティションに書き込まれたイベントにのみ順序の合計を維持します。キーによるイベントのパーティション設定により、同じキーを持つすべてのイベントは常に同じパーティションに送信されます。これにより、特定のドキュメントのすべてのイベントが常に正しく順序付けられます。

4.4.6. イベント

MongoDB コネクターによって生成されたすべてのデータ変更イベントには、キーと値があります。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリーム について設計されており、これらのイベントの構造は構造内で変更されたり、コネクターが変更したりした場合に、これらのイベントの構造が変わる可能性があります。これはコンシューマーによる対応が困難になる可能性があるため、Kafka Connect による各イベントの自己完結が非常に容易になります。各メッセージキーと値には、スキーマ と ペイロード の 2 つの部分があります。スキーマはペイロードの構造を記述し、ペイロードには実際のデータが含まれます。

4.4.6.1. Change イベントのキー

指定のコレクションでは、変更イベントのキーに単一の id フィールドが含まれます。この値は、MongoDB 拡張 JSON シリアル化から派生する文字列として表されるドキュメントの識別子です。論理名を持つコネクター（例： ドキュメント fulfillmentを含む inventory データベースを含むレプリカセット）について customers 考えてみましょう。 

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

customers コレクションのすべての変更イベントには、JSON で使用する同じキー構造が含まれています。 

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

キーの schema 一部には、ペイロード部分に含まれる Kafka Connect スキーマが含まれます。この場合、payload 値はオプションではなく、という名前のスキーマによって定義される構造で fulfillment.inventory.customers.Key、id type という名前の必須フィールドが 1 つあることを意味し stringます。キーの payload フィールドの値を確認すると、値が整数を含む文字列である 1 つの id フィールドを持つ構造であることがわかります（JSON のオブジェクトはオブジェクト内） 1004。

この例では整数識別子を持つドキュメントを使用していましたが、有効な MongoDB ドキュメント識別子（ドキュメントを含む）は機能します。ペイロードの id フィールドの値は、元のドキュメントの _id フィールドの MongoDB 拡張 JSON シリアル化（厳密モード）を表す文字列になります。以下のサンプルで、異なるタイプの _id フィールドがイベントキーのペイロードとしてエンコードされる方法を示しています。

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

整数

1234

{ "id" : "1234" }

float

12.34

{ "id" : "12.34" }

文字列

"1234"

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

ドキュメント

{ "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\"}" }

バイナリー

BinData("a2Fma2E=",0)

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

4.4.6.2. イベントの値の変更

変更イベントメッセージの値は、より複雑です。キーメッセージと同様に、schema セクションと payload セクションがあります。MongoDB コネクターによって生成されたすべての変更イベント値の payload セクションには、以下のフィールドが含まれる 構造 があります。

  • op は、操作のタイプを記述する文字列の値が含まれる必須フィールドです。MongoDB コネクターの値は c create（または insert）、u 更新、d 削除、および r 読み取り（スナップショットの場合）になります。
  • after はオプションのフィールドで、イベント発生 後 にドキュメントの状態が含まれる場合。MongoDB の oplog エントリーには、イベント 作成 のドキュメントの完全な状態のみが含まれるため、これらは after フィールドが含まれるイベントのみになります。
  • source は、イベントのソースメタデータを記述する構造が含まれる必須フィールドです。これには、MongoDB のバージョン、論理名、レプリカセットの名前、コレクションの namespace、MongoDB タイムスタンプ（およびタイムスタンプ内のイベントの ordinal）が含まれます。 MongoDB 操作の識別子（例： oplog イベントの h フィールド）、およびイベントがスナップショット中に生じた場合は初期同期フラグ。
  • ts_ms は任意で、コネクターがイベントを処理した JVM のシステムクロックを使用して（Kafka Connect タスクを実行している JVM でシステムクロックを使用）。

当然ながら、イベントメッセージ値の スキーマ 部分には、この構造と内部のネストされたフィールドを記述するスキーマが含まれます。

customers コレクションの 作成や読み取り のイベント値の例を見てみましょう。 

{
    "schema": {
      "type": "struct",
      "fields": [
        {
          "type": "string",
          "optional": true,
          "name": "io.debezium.data.Json",
          "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",
          "field": "source"
        },
        {
          "type": "string",
          "optional": true,
          "field": "op"
        },
        {
          "type": "int64",
          "optional": true,
          "field": "ts_ms"
        }
      ],
      "optional": false,
      "name": "dbserver1.inventory.customers.Envelope"
      },
    "payload": {
      "after": "{\"_id\" : {\"$numberLong\" : \"1004\"},\"first_name\" : \"Anne\",\"last_name\" : \"Kretchmar\",\"email\" : \"annek@noanswer.org\"}",
      "patch": null,
      "source": {
        "version": "1.1.2.Final",
        "connector": "mongodb",
        "name": "fulfillment",
        "ts_ms": 1558965508000,
        "snapshot": true,
        "db": "inventory",
        "rs": "rs0",
        "collection": "customers",
        "ord": 31,
        "h": 1546547425148721999
      },
      "op": "r",
      "ts_ms": 1558965515240
    }
  }

このイベントの 値 の schema 一部を確認すると、そのコレクションに 固有 のスキーマと source 構造のスキーマ（MongoDB コネクターに固有で、すべてのイベントで再利用）がわかります。また、after 値は常に文字列で、規則によりドキュメントの JSON 表現が含まれていることに注意してください。

このイベントの 値 の payload 一部を確認する op=r と、イベント内の情報が表示されます。つまり、ドキュメントがスナップショットの一部として読み取られたこと snapshot=true、after フィールドの値にドキュメントの JSON 文字列表現が含まれることが記述されています。

注記

これは、イベントの JSON 表現が記述する行よりもはるかに大きいことが分かります。JSON 表現にはメッセージの スキーマ と ペイロード の部分を含める必要があるため、これは true です。

このコレクションの 更新 変更イベントの値には実際には同じ スキーマ があり、ペイロードは同じですが、異なる値を保持します。具体的には、更新イベントには after 値がなく、代わりにべき等更新操作の patch JSON 表現や、更新の選択基準を含む filter 文字列が含まれます。filter 文字列にはシャードコレクションの複数のシャードキーフィールドを含めることができます。以下に例を示します。 

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

これを insert イベントの値と比較すると、payload セクションにいくつかの違いが表示されます。

  • op フィールドの値は u、更新によりこのドキュメントが変更されていることを示すようになりました。
  • patch フィールドが表示され、ドキュメントへの実際の MongoDB idempotent 変更の文字列が JSON 表現されます。この例では、first_name フィールドを新しい値に設定します。
  • filter フィールドが表示され、更新に使用される MongoDB 選択基準の文字列が JSON 表現されます。
  • after フィールドが表示されなくなる
  • source フィールド構造には以前のフィールドと同じフィールドがありますが、イベントが oplog の別の位置にあるため、値は異なります。
  • は ts_ms、Debezium がこのイベントを処理したタイムスタンプを示しています。
警告

patch フィールドの内容は MongoDB 自体によって提供され、その正確な形式は特定のデータベースバージョンによって異なります。したがって、MongoDB インスタンスを新規バージョンにアップグレードする際には、フォーマットに変更を加える可能性があります。

本ドキュメントのすべての例は MongoDB 3.4 から取得され、別のものを使用する場合は異なる場合があります。

注記

MongoDB の oplog でイベントを更新するには、変更 後のドキュメントのステータスの 前 または後 にはないため、コネクターがこの情報を提供する方法はありません。ただし、イベントの 作成 または 読み取り に は start 状態が含まれるため、各ドキュメントの最新状態を維持し、各イベントをその状態に適用することで、ストリームのダウンストリームコンシューマーは状態を完全に調整できます。Debezium コネクターはこのような状態を維持できないため、これは実行できません。

これまでは、イベントの 作成/読み取り および 更新 の例を確認することができます。以下の例は、同じコレクションの delete イベントの値を示しています。このコレクションの delete イベントの値は全く同じ スキーマ を持ち、ペイロードは同じですが、異なる値を保持します。特に、削除イベントには after 値も値もありません patch。 

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

これを他のイベントの値と比較すると、payload セクションにいくつかの違いがあります。

  • op フィールド値は d、このドキュメントが削除されたことを表しています。
  • patch フィールドは表示されません。
  • after フィールドは表示されません。
  • filter フィールドが表示され、削除に使用される MongoDB 選択基準の文字列が JSON 表現されます。
  • source フィールド構造には以前のフィールドと同じフィールドがありますが、イベントが oplog の別の位置にあるため、値は異なります。
  • は ts_ms、Debezium がこのイベントを処理したタイムスタンプを示しています。

MongoDB コネクターは、他の種類のイベントを提供します。各 削除 イベントの後に、削除 イベントと同じキーを持つ tombstone イベントが続きますが、null 値が設定されます。これにより、Kafka には ログ圧縮 メカニズムを実行し、そのキーで すべて のメッセージを削除するのに必要な情報が提供されます。

注記

すべての MongoDB コネクターイベントは、Kafka ログの圧縮 と連携するように設計されています。これにより、すべてのキーの少なくとも最新のメッセージが保持されていれば、古いメッセージを削除できるようになります。これは、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できる Kafka でストレージ領域を回収する方法です。

一意に識別されたドキュメントの MongoDB コネクターイベントはすべて全く同じキーを持ち、最新のイベントのみが保持される Kafka にシグナルします。tombstone イベントは、同じ鍵を持つ すべて のメッセージが削除可能であることを Kafka に通知します。

4.4.7. トランザクションメタデータ

Debezium は、tranaction メタデータ境界を表すイベントを生成し、データメッセージを強化できます。

4.4.7.1. トランザクション境界

Debezium は、すべてのトランザクション BEGIN およびのイベントを生成し ENDます。すべてのイベントにはが含まれます。

  • status - BEGIN または END
  • id : 一意のトランザクション ID の文字列表現
  • event_count （ END イベント用）: トランザクションによってエミュレートされたイベントの合計数
  • data_collections （ END イベント用）: 指定のデータコレクションから発信さ event_count れる変更により発生するイベントの数を提供する data_collection とのペアの配列

メッセージの例を以下に示します。 

{
  "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": "rs0.testDB.tablea",
      "event_count": 1
    },
    {
      "data_collection": "rs0.testDB.tableb",
      "event_count": 1
    }
  ]
}

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

4.4.7.2. データイベントの強化

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

  • id : 一意のトランザクション 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"
  }
}

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

MongoDB コネクターのインストールは、JAR のみのダウンロード、Kafka Connect 環境への抽出、およびプラグインの親ディレクトリーを Kafka Connect 環境に指定する必要がある単純なプロセスです。

前提条件

手順

  1. Debezium MongoDB コネクター をダウンロードします。
  2. ファイルを Kafka Connect 環境に抽出します。

  3. プラグインの親ディレクトリーを Kafka Connect に追加し plugin.pathます。 

    plugin.path=/kafka/connect
注記

上記の例では、Debezium MongoDB コネクターを /kafka/connect/Debezium-connector-mongodb パスに抽出していることを前提としています。

  1. Kafka Connect プロセスを再起動します。これにより、新しい JAR が確実に検出されます。

関連情報

デプロイメントプロセスおよび AMQ Streams でのコネクターのデプロイに関する詳細は、『Debezium インストールガイド』を参照してください。

4.5.1. 設定例

コネクターを使用して特定の MongoDB レプリカセットまたはシャードクラスターの変更イベントを生成するには、JSON に設定ファイルを作成します。コネクターが起動すると、MongoDB レプリカセットでコレクションのスナップショットを実行し、レプリカセットの oplog の読み取り、挿入、更新、および削除されるすべての行についてのイベントの生成を開始します。任意で、不要なコレクションを除外します。

192.168.99.100 のポート 27017 rs0 で MongoDB レプリカセットを監視する MongoDB コネクターの設定例を以下に示します fullfillment。通常、コネクターで使用できる設定プロパティーを使用して、.yaml ファイルで Debezium MongoDB コネクターを設定します。 

apiVersion: kafka.strimzi.io/v1beta1
  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.whitelist: inventory[.]* 5
1
Kafka Connect サービスに登録した場合のコネクターの名前。
2
MongoDB コネクタークラスの名前。
3
MongoDB レプリカセットに接続するために使用するホストアドレス。
4
生成されたイベントの namespace を構成する MongoDB レプリカセットの 論理名。これは、コネクターが書き込む Kafka トピックの名前、Kafka Connect スキーマ名、および Avro Connector が使用されたときに対応する Avro スキーマの namespace で使用されます。
5
監視するすべてのコレクションの名前空間（例： <dbName>.<collectionName>）に一致する正規表現の一覧。これはオプションです。

これらの設定で指定できる コネクタープロパティーの完全なリスト を参照してください。

この設定は、POST を介して実行中の Kafka Connect サービスに送信できます。これにより、設定を記録し、MongoDB レプリカセットまたはシャードクラスターに接続される 1 つのコネクタータスクを開始し、各レプリカセットのタスクを割り当てます。必要な場合はスナップショットを実行し、イベントを Kafka トピックに読み取り、イベントを Kafka トピックに読み取ります。

4.5.2. モニタリング

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

JMX でこれらのメトリクスを公開する方法については、モニタリングドキュメント を参照してください。

4.5.2.1. スナップショットメトリクス

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

属性名

型

説明

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるコレクションのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

TotalTableCount

int

スナップショットに含まれるコレクションの合計数。

RemainingTableCount

int

スナップショットがコピーしたコレクションの数。

SnapshotRunning

boolean

スナップショットが起動しているかどうか。

SnapshotAborted

boolean

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

SnapshotCompleted

boolean

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

SnapshotDurationInSeconds

long

スナップショットが完了しなかった場合でも、これまでスナップショットが取得した秒数の合計数。

RowsScanned

Map<String, Long>

スナップショットの各コレクションにエクスポートされるドキュメントの数が含まれるマップ。コレクションは処理中にマップに徐々に追加されます。コレクションの完了後にスキャンされたドキュメントをすべて更新し、更新します。

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

属性型説明

NumberOfDisconnects

long

データベースの接続解除数。

4.5.2.2. ストリーミングメトリクス

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

属性名

型

説明

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるコレクションのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

Connected

boolean

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

MilliSecondsBehindSource

long

最後に変更イベントのタイムスタンプとコネクターの処理の間隔（ミリ秒単位）。値には、データベースサーバーとコネクターが実行されているマシンのクロック間の違いが反映されます。

NumberOfCommittedTransactions

long

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

SourceEventPosition

map<string, string>

最後に受信したイベントのコーディネート。

LastTransactionId

string

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

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

属性型説明

NumberOfDisconnects

long

データベースの接続解除数。

NumberOfPrimaryElections

long

プライマリーノードのエミュレーション数。

4.5.3. コネクタープロパティー

以下の設定プロパティーは、デフォルト値が利用可能でない限り 必要 になります。

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

name

 

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

connector.class

 

コネクターの Java クラスの名前。MongoDB コネクターに常にの値を使用 io.debezium.connector.mongodb.MongoDbConnector してください。

mongodb.hosts

 

レプリカセットの MongoDB サーバーのホスト名とポートのペアのコンマ区切りリスト（「host」または「host:port」の形式）。この一覧には、ホスト名とポートのペアを 1 つ含めることができます。がに設定 mongodb.members.auto.discover されている場合には false、ホストとポートのペアの前にレプリカセット名（例：、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

この設定を有効にすると、接続フェーズで厳密なホスト名の確認を無効にするかどうかを制御します。接続 true によって中間者攻撃が阻止されない場合。

database.whitelist

空の文字列

監視するデータベース名に一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないデータベース名は、監視から除外されます。デフォルトでは、すべてのデータベースが監視されます。とは使用されない場合があり database.blacklistます。

database.blacklist

空の文字列

監視から除外されるデータベース名に一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないデータベース名が監視されます。とは使用されない場合があり database.whitelistます。

collection.whitelist

空の文字列

監視する MongoDB コレクションの完全修飾ネームスペースに一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないコレクションはモニタリングから除外されます。各識別子は databaseName. collectionName の形式です。デフォルトでは、コネクターはおよびデータベースのもの以外のすべてのコレクションを監視 local し admin ます。とは使用されない場合があり collection.blacklistます。

collection.blacklist

空の文字列

監視から除外される MongoDB コレクションの完全修飾ネームスペースに一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないコレクションはすべて監視されます。各識別子は databaseName. collectionName の形式です。とは使用されない場合があり collection.whitelistます。

snapshot.mode

initial

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

field.blacklist

空の文字列

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

field.renames

空の文字列

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

tasks.max

1

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

initial.sync.max.threads

1

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

tombstones.on.delete

true

削除イベントの後に tombstone イベントを生成するかどうかを制御します。
削除操作 true が削除イベントと後続の tombstone イベントによって表される場合。削除イベント false のみを送信する場合。
tombstone イベント（デフォルトの動作）を生成すると、Kafka はソースレコードが削除されると、指定のキーに関連するすべてのイベントを完全に削除できます。

snapshot.delay.ms

 

起動後のスナップショットの取得前にコネクターが待機する間隔（ミリ秒単位）
。クラスターで複数のコネクターを起動する際にスナップショットの中断を回避するために使用できます。コネクターのリバランスが発生する可能性があります。

snapshot.fetch.size

0

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

以下の 高度な 設定プロパティーには、ほとんどの場合で動作するため、コネクターの設定で指定する必要はほとんどありません。

プロパティー

デフォルト

説明

max.queue.size

8192

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

max.batch.size

2048

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

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、失敗するまでに 20 分以上の試行が connect.backoff.max.delay.ms 発生します。

mongodb.members.auto.discover

true

'mongodb.hosts' のアドレスがクラスターまたはレプリカセットのすべてのメンバーを検出するのに使用するシード(true)か、内のアドレスをそのまま（）として使用するかどうかを指定 mongodb.hosts するブール値false。MongoDB が プロキシーによって の前に付けられる場合を除き、デフォルトは true およびです。

heartbeat.interval.ms

0

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

ハートビートメッセージを送信しないよう 0 に、このパラメーターをに設定します。
デフォルトでは無効です。

heartbeat.topics.prefix

__debezium-heartbeat

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

sanitize.field.names

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

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

skipped.operations

 

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

provide.transaction.metadata

false

true Debezium に設定すると、トランザクション境界でイベントが生成され、トランザクションメタデータでデータイベントが強化されます。

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

4.6. MongoDB コネクターに関する典型的な問題

Debezium は、複数のアップストリームデータベースの変更をすべてキャプチャーし、イベントの失敗や損失は発生しない分散システムです。当然ながら、システムが規則的な動作や管理を慎重に行なっ ている場合、Debezium はすべての変更イベントの配信を一度 提供します。ただし、障害が発生すると、システムはイベントを失いませんが、障害からの復旧中は変更イベントを繰り返す可能性があります。そのため、このような異常な状況で（Kafka のような）Debezium は、最低でも 1 回 変更イベントを配信します。

本セクションの残りの部分では、Debezium が様々な障害や問題を処理する方法について説明します。

4.6.1. 設定および起動エラー

コネクターは、起動時に失敗し、ログにエラー/例外を報告し、コネクターの設定が無効な場合に実行を停止します。または、コネクターが指定の接続パラメーターを使用して MongoDB への接続を繰り返し失敗すると、コネクターは MongoDB への接続を繰り返し失敗します。再接続は指数関数的バックオフを使用して行われ、試行回数は設定可能です。

このような場合、エラーには問題の詳細が記載され、推奨される回避策が考えられます。設定が修正され、MongoDB の問題が対処されると、コネクターを再起動することができます。

4.6.2. 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

4.6.3. Kafka Connect プロセスが正常に停止する

Kafka Connect を分散モードで実行しており、Kafka Connect プロセスが正常に停止した場合、そのプロセスのコネクタータスクをグループ内の別の Kafka Connect プロセスに移行し、新しいコネクタータスクは以前のタスクが除外された場所をそのまま取得します。コネクタータスクが正常に停止され、新しいプロセスで再起動される間、処理に短い遅延が生じます。

グループにプロセスが含まれ、そのプロセスが正常に停止されると、Kafka Connect はコネクターを停止し、各レプリカセットの最後のオフセットを記録します。再起動すると、レプリカセットタスクは停止した正確な場所を続行します。

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

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

注記

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

Debezium には、MongoDB イベントの一意のトランザクション ID(h)およびタイムスタンプ（sec および ord）を含む各変更イベントの発信元固有の情報も含まれます。コンシューマーは、これらの他の値を追跡し、特定のイベントをすでに確認しているかどうかを確認できます。

4.6.5. Kafka が利用できなくなる

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

4.6.6. コネクターが一定期間停止している。

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

Kafka クラスターが適切に設定されていると、大きなスループットが可能になります。Kafka Connect は Kafka のベストプラクティスで記述され、十分なリソースが非常に多くのデータベース変更イベントを処理できます。そのため、しばらくコネクターが再起動されると、Kafka の機能およびパフォーマンスと MongoDB のデータに加えられた変更のボリュームにどの程度迅速に適用されるかは大きく変わります。

注記

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

4.6.7. MongoDB による書き込みの損失

MongoDB は、特定の失敗状況でコミットを失う可能性があります。たとえば、プライマリーが変更を適用し、oplog でこれを記録する場合、予期せずクラッシュする前にセカンダリーノードはプライマリーの oplog からそれらの変更を読み取る可能性がありませんでした。このようなセカンダリーの 1 つがプライマリーとして選択される場合、その oplog は、古いプライマリーが記録された最後の変更がなく、それらの変更がありません。

プライマリーの oplog に記録された MongoDB の変更が失われる場合、MongoDB コネクターはこれらの損失した変更をキャプチャーしたり、キャプチャーしない可能性があります。現時点では、MongoDB がこの副次的影響を防ぐことはできません。

第5章 SQL Server の Debezium コネクター

Debezium の SQL Server Connector は、SQL Server データベースのスキーマの行レベルの変更を監視および記録できます。

SQL Server データベース/クラスターに初めて接続すると、すべてのスキーマの一貫したスナップショットを読み取ります。スナップショットが完了すると、コネクターは SQL Server にコミットされた変更を継続的にストリーミングし、対応する挿入、更新、および削除イベントを生成します。各テーブルのイベントはすべて個別の Kafka トピックに記録され、アプリケーションやサービスによって簡単に消費されます。

5.1. 概要

コネクターの機能は、SQL Server Standard(SQL Server 2016 SP1)または Enterprise 版から提供される 変更データキャプチャー 機能をベースとしています。このメカニズムを使用して、SQL Server キャプチャープロセスにより、ユーザーが関心のあるデータベースおよびテーブルをすべて監視し、その変更はストアドプロシージャーファサードを持つ特別に作成されたフレーム テーブル に保管されます。

コネクターがキャプチャー する必要のあるテーブルについて は、データベース Operator が有効 にする必要があります。コネクターは次に、すべての行レベルの挿入、更新、および削除操作の 変更イベント を作成します。その際、コネクターは 、 個別の Kafka トピックで各テーブルのすべての変更イベントを記録します。クライアントアプリケーションは、以下に関心のあるデータベーステーブルに対応する Kafka トピックを読み取り、これらのトピックで表示されるすべての行レベルのイベントに対応します。

データベース Operator は通常、データベース のアン/テーブルの中間期間中に有効になります。つまり、コネクターにはデータベースに加えられたすべての変更の完全な履歴がないことを意味します。そのため、SQL Server コネクターが最初に特定の SQL Server データベースに接続するとき、各データベーススキーマの 一貫したスナップショット を実行することで開始します。コネクターがスナップショットを完了した後も、スナップショットの作成先の正確な時点から変更のストリーミングが継続されます。これにより、全データの一貫したビューから始め、スナップショットの発生中に加えられた変更をすべて失われることなく、読み取りを継続します。

コネクターは失敗を許容します。コネクターは変更を読み取り、イベントを生成する際に、各イベントに関連するデータベースログ（LSN / ログシーケンス番号） の 位置を記録します。コネクターが何らかの理由で停止する場合（通信の失敗、ネットワークの問題、クラッシュなど）、再起動すると単に、最後に停止した テーブル を読み取り続けるだけです。これには、スナップショットが含まれます。再起動すると、コネクターが停止した際にスナップショットが完了しなかった場合（再起動時にスナップショットが開始します）。

5.2. SQL Server の設定

SQL Server コネクターを使用して SQL Server にコミットされた変更を監視する前に、まず監視されたデータベース で レスポンスを有効にします。database は master データベース用に有効 に できないことに注意してください。 

-- ====
-- Enable Database for CDC template
-- ====
USE MyDB
GO
EXEC sys.sp_cdc_enable_db
GO

次に、監視 する 予定の各テーブルについて  を有効にします。 

-- ====
-- Enable a Table Specifying Filegroup Option Template
-- ====
USE MyDB
GO

EXEC sys.sp_cdc_enable_table
@source_schema = N'dbo',
@source_name   = N'MyTable',
@role_name     = N'MyRole',
@filegroup_name = N'MyDB_CT',
@supports_net_changes = 0
GO

ユーザーがこれらのテーブルにアクセスできることを 確認 します。 

-- ====
-- Verify the user of the connector have access, this query should not have empty result
-- ====

EXEC sys.sp_cdc_help_change_data_capture
GO

結果が空である場合は、キャプチャーインスタンスとをキャプチャーテーブルの両方にアクセスする権限があることを確認し て ください。

5.2.1. Azure 上の SQL Server

SQL Server プラグインは、Azure 上の SQL Server でテストされていません。管理対象環境でデータベースと共にプラグインを試すための、ユーザーからのフィードバックをお寄せください。

5.3. SQL Server コネクターの仕組み

5.3.1. スナップショット

SQL Server は、データベース変更の完全な履歴を保存するものではありません。そのため、Debezium が現在のデータベースコンテンツのベースラインを確立し、それを Kafka にストリームする必要があります。これは、スナップショットと呼ばれるプロセスで実行されます。

デフォルトでは（スナップショットモードの 初期）コネクターは、最初の起動時にデータベースの初期 一貫したスナップショット を実行します（これは、コネクターのフィルター設定に従ってキャプチャーされるテーブル内の構造およびデータを意味します）。

各スナップショットは、以下の手順で構成されます。

  1. キャプチャーされるテーブルの特定
  2. 各監視されるテーブルのロックを取得して、あらゆるテーブルに対して構成の変更が発生しないようにします。ロックのレベルは、snapshot.isolation.mode 設定オプションにより決定されます。
  3. サーバーのトランザクションログの最大 LSN（LSN シーケンス番号）の位置を確認します。
  4. 関連するすべてのテーブルの構造を取得します。
  5. 必要に応じて、手順 2 で取得したロックを解放します。つまり、ロックは通常短期間のみ保持されます。
  6. ステップ 3 で読み取られた LSN 位置で有効であるすべてのデータベーステーブルおよびスキーマをスキャンし、各行の READ イベントを生成し、そのイベントを適切なテーブル固有の Kafka トピックに書き込みます。
  7. コネクターオフセットでスナップショットが正常に完了したことを記録します。

5.3.2. 変更データテーブルの読み取り

最初の起動時に、コネクターはキャプチャーされたテーブルの構造の完全にスナップショットを取り、この情報を内部データベース履歴トピックに保持します。次に、コネクターは各ソーステーブルの変更テーブルを特定し、メインのループを実行します。

  1. 各変更テーブルで、最後に保存された最大 LSN と現在の最大 LSN の間に作成されたすべての変更を読み取ります。
  2. コミット LSN に従って、読み取り変更を段階的に順序付けし、LSN を変更します。これにより、データベースに加えられた順序で変更が Debezium によって再生されます。
  3. コミットをパスし、LSN を Kafka Connect にオフセットとして変更します。
  4. 最大 LSN を保存して、ループを繰り返します。

再起動後、コネクターは、前のステップでオフのままにしたオフセット（コミットおよび LSN）から再開します。

コネクターは、ホワイトリストに登録されたソーステーブルで有効であるか、無効であるかを検出して、その動作を調整することができます。

5.3.3. Topic 名

SQL Server コネクターは、すべての挿入、更新、および削除のイベントを 1 つの Kafka トピックに書き込みます。Kafka トピックの名前は常に serverName. schemaName.tableName の形式を取ります。 serverName は database.server.name 設定プロパティーで指定されたコネクターの論理名、schemaName は 操作が発生したスキーマの名前、tableName は操作が発生したデータベーステーブルの名前になります。

たとえば、SQL Server のインストールと、orders スキーマの 4 つのテーブルが含まれる inventory データベースのインストールについて考え products products_on_hand customersてみましょう dbo。このデータベースに論理サーバー名が指定された場合 fulfillment、コネクターは以下の 4 つの Kafka トピックでイベントを生成します。

  • fulfillment.dbo.products
  • fulfillment.dbo.products_on_hand
  • fulfillment.dbo.customers
  • fulfillment.dbo.orders

5.3.4. イベント

SQL Server コネクターによって生成されたすべてのデータ変更イベントにはキーと値がありますが、キーと値の構造は、変更イベントの発生元となるテーブルによって異なります（ Topic name を参照）。

警告

SQL Server コネクターは、すべての Kafka Connect スキーマ名が 有効な Avro スキーマ名 であることを確認します。つまり、論理サーバー名は、ラテン文字またはアンダースコア（例： [a-z,A-Z,_]）で開始し、論理サーバー名の残りの文字と、スキーマおよびテーブル名の残りの文字は、ラテン文字、数字、またはアンダースコア([a-z,A-Z,0-9,\_])で始まる必要があります。そうでない場合には、無効な文字はすべて自動的にアンダースコアに置き換えられます。

これにより、論理サーバー名、スキーマ名、およびテーブル名に他の文字が含まれる場合に予期しない競合が発生し、テーブルのフルネーム間の文字のみが無効となり、アンダースコアに置き換えられます。

Debezium および Kafka Connect は、イベントメッセージの継続的なストリームについて設計されており、これらのイベント の構造は徐々に変わる可能性があります。これはコンシューマーによる対応が困難になる可能性があるため、Kafka Connect による各イベントの自己完結が容易になります。各メッセージキーと値には、スキーマ と ペイロード の 2 つの部分があります。スキーマはペイロードの構造を記述し、ペイロードには実際のデータが含まれます。

5.3.4.1. イベントキーの変更

特定のテーブルでは、変更イベントのキーには、イベントの作成時にテーブルのプライマリーキー（または一意の鍵制約）にある各列のフィールドが含まれる構造があります。

inventory データベースのスキーマで定義されている customers テーブルについて考えてみましょう dbo。 

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
);

database.server.name 設定プロパティーに値がある場合 server1、この定義がある間に customers テーブルのすべての変更イベントは、JSON で使用する同じキー構造に対応します。 

{
    "schema": {
        "type": "struct",
        "fields": [
            {
                "type": "int32",
                "optional": false,
                "field": "id"
            }
        ],
        "optional": false,
        "name": "server1.dbo.customers.Key"
    },
    "payload": {
        "id": 1004
    }
}

キーの schema 部分には、キー部分に含まれるものを記述する Kafka Connect スキーマが含まれます。この場合、payload 値はオプションではなく、という名前のスキーマによって定義される構造で server1.dbo.customers.Key、id type という名前の必須フィールドが 1 つあることを意味し int32ます。キーのフィールドの値を確認すると、値が 1 つの payload フィールド（JSON のオブジェクトにある）の構造で id あることがわかり 1004ます。

そのため、このキーは、プライマリーキーコラムにの id 値がである dbo.customers テーブル（コネクターから出力 server1）の行の説明として解釈でき 1004ます。

5.3.4.2. イベント値の変更

メッセージキーと同様に、変更イベントメッセージの値には schema セクションおよび payload セクションがあります。SQL Server コネクターによって生成されるすべての変更イベント値の payload セクションには、以下のフィールドが含まれる 構造 があります。

  • op は、操作のタイプを記述する文字列の値が含まれる必須フィールドです。SQL Server コネクターの値は c create（または insert）、u 更新、d 削除、および r 読み取り（スナップショットの場合）になります。
  • before はオプションのフィールドで、イベント発生 前 の行の状態がある場合はその行の状態になります。この構造は、server1 コネクターが dbo.customers テーブルのすべての行に使用する server1.dbo.customers.Value Kafka Connect スキーマによって記述されます。
  • after はオプションのフィールドで、イベント発生 後 の行の状態が含まれる場合です。構造は、で使用される同じ server1.dbo.customers.Value Kafka Connect スキーマによって記述され beforeます。

  • source イベントのソースメタデータを記述する構造が含まれる必須フィールドです。この場合、SQL Server のフィールドには Debezium バージョン、コネクター名、イベントが進行中のスナップショットの一部であるかどうか、またはコミット LSN、変更が発生した時点の LSN、データベース、スキーマ、および変更の時点を表すタイムスタンプが含まれます。

    また、ストリーミング時に event_serial_no はフィールドが表示されます。これは、同じコミットがあり、LSN を変更するイベント間を区別するために使用されます。値が異なる場合は、ほとんどの場合 2 つの状況があり 1ます。

    • 更新イベントにはの値がに設定されます。これは 2、更新によって SQL Server の Change テーブルに 2 つのイベントが生成されるためです（ソースドキュメント）。最初の値には古い値が含まれ、2 つ目には新しい値が含まれます。したがって、1 つ目はドロップされ、Debezium 変更イベントを作成するために 2 つ目の値とともに使用されます。
    • プライマリーキーが更新されると、SQL Server は 2 つのレコードを発行して、古いプライマリーキーの値のレコードを delete 削除 insert し、新しいプライマリーキーでレコードを作成します。どちらの操作も同じコミットを共有し、LSN を変更します。また、イベント番号は 1 およびです 2。
  • ts_ms は任意で、コネクターがイベントを処理した JVM のシステムクロックを使用して（Kafka Connect タスクを実行している JVM でシステムクロックを使用）。

当然ながら、イベントメッセージ値の スキーマ 部分には、この構造と内部のネストされたフィールドを記述するスキーマが含まれます。

5.3.4.2.1. イベントの作成

イベントの 作成 値を以下の 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.dbo.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.dbo.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"
          },
          {
            "type": "int64",
            "optional": true,
            "field": "event_serial_no"
          }
        ],
        "optional": false,
        "name": "io.debezium.connector.sqlserver.Source",
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "server1.dbo.customers.Envelope"
  },
  "payload": {
    "before": null,
    "after": {
      "id": 1005,
      "first_name": "john",
      "last_name": "doe",
      "email": "john.doe@example.org"
    },
    "source": {
      "version": "1.1.2.Final",
      "connector": "sqlserver",
      "name": "server1",
      "ts_ms": 1559729468470,
      "snapshot": false,
      "db": "testDB",
      "schema": "dbo",
      "table": "customers",
      "change_lsn": "00000027:00000758:0003",
      "commit_lsn": "00000027:00000758:0005",
      "event_serial_no": "1"
    },
    "op": "c",
    "ts_ms": 1559729471739
  }
}

このイベントの 値 の schema 一部を確認すると、source 構造のスキーマ（SQL Server コネクターに固有で 、 すべてのイベントで再利用される）のスキーマ、before および after フィールドのテーブル固有のスキーマが表示されます。

注記

before および after フィールドのスキーマ名は logicalName. schemaName . tableName.Value の形式であるため、他のすべてのテーブルの他のすべてのスキーマから完全に独立した名前になります。つまり、Avro Converter を使用すると、各 論理ソース の 各テーブル の Avro スキーマは、独自の進化と履歴になります。

このイベントの 値 の payload 一部を確認すると、イベントの情報が表示されます。つまり、行が作成されたこと（つまり op=c）、および after フィールドの値に、新しい挿入された行の、、、id first_name last_nameおよび email 列の値が含まれていることが示されています。

注記

これは、イベントの JSON 表現が記述する行よりもはるかに大きいことが分かります。JSON 表現にはメッセージの スキーマ と ペイロード の部分を含める必要があるため、これは true です。を使用すると、Kafka トピックに書き込まれた実際のメッセージのサイズを大幅に縮小することもできます。

5.3.4.2.2. イベントの更新

このテーブルの 更新 変更イベントの値は実際には同じ スキーマ を持ち、ペイロードは同じですが、異なる値を保持します。以下に例を示します。 

{
  "schema": { ... },
  "payload": {
    "before": {
      "id": 1005,
      "first_name": "john",
      "last_name": "doe",
      "email": "john.doe@example.org"
    },
    "after": {
      "id": 1005,
      "first_name": "john",
      "last_name": "doe",
      "email": "noreply@example.org"
    },
    "source": {
      "version": "1.1.2.Final",
      "connector": "sqlserver",
      "name": "server1",
      "ts_ms": 1559729995937,
      "snapshot": false,
      "db": "testDB",
      "schema": "dbo",
      "table": "customers",
      "change_lsn": "00000027:00000ac0:0002",
      "commit_lsn": "00000027:00000ac0:0007",
      "event_serial_no": "2"
    },
    "op": "u",
    "ts_ms": 1559729998706
  }
}

これを insert イベントの値と比較すると、payload セクションにいくつかの違いが表示されます。

  • op フィールド値は u、更新によりこの行が変更されたことを示すようになりました。
  • この before フィールドには、データベースのコミットの前に値が含まれる行の状態が含まれるようになりました。
  • この after フィールドには更新された行の状態が使用されるようになりました。ここで、email 値は現在の状態であることを確認でき noreply@example.orgます。
  • source フィールド構造には以前のフィールドと同じフィールドがありますが、イベントがトランザクションログ内の別の位置にあるため、値は異なります。
  • この event_serial_no フィールドにはの値があり 2ます。これは、背後にある 2 つのイベントで構成され、2 つ目のイベントのみを公開している更新イベントによって生じます。詳しくは、ソースのドキュメント を確認し、フィールドを参照してください $operation。
  • は ts_ms、Debezium がこのイベントを処理したタイムスタンプを示しています。

本 payload セクションのみで確認できる点がいくつかあります。コミットにより before、と after 構造を比較して、この行で実際に何が変更されているかを判断できます。source 構造は、この変更の SQL Server の記録に関する情報を提供します（トレース可能性の向上）。より重要なことは、このイベントを他のトピックの他のイベントと比較し、このイベントが他のイベントとして発生したかどうか、または他のイベントの一部として確認することができます。

注記

行のプライマリー/一意キーの列が更新されると、行のキーの値が変更され、Debezium は 3 つ のイベント（ DELETE イベントおよび行の古いキーを持つコンブロック イベント） を出力し、行の新しいキーを含む INSERT イベントが出力されます。

5.3.4.2.3. イベントの削除

これまでは、イベントの 作成 および 更新 の例を確認することができます。以下の例は、同じテーブルの 削除 イベントの値を示しています。繰り返しになると、値の schema 一部は create および update イベントと全く同じになります。 

{
  "schema": { ... },
  },
  "payload": {
    "before": {
      "id": 1005,
      "first_name": "john",
      "last_name": "doe",
      "email": "noreply@example.org"
    },
    "after": null,
    "source": {
      "version": "1.1.2.Final",
      "connector": "sqlserver",
      "name": "server1",
      "ts_ms": 1559730445243,
      "snapshot": false,
      "db": "testDB",
      "schema": "dbo",
      "table": "customers",
      "change_lsn": "00000027:00000db0:0005",
      "commit_lsn": "00000027:00000db0:0007",
      "event_serial_no": "1"
    },
    "op": "d",
    "ts_ms": 1559730450205
  }
}

payload 部分を確認すると、イベントペイロードの 作成 または 更新 との違いが複数あります。

  • op フィールド値は d、この行が削除されたことを表しています。
  • この before フィールドには、データベースのコミットで削除された行の状態が表示されます。
  • after フィールドは null で、行が存在しなくなったことを表します。
  • source フィールド構造には、、および change_lsn フィールドの変更を除き、前 ts_ms commit_lsn と同じ値の多くが含まれます。
  • は ts_ms、Debezium がこのイベントを処理したタイムスタンプを示しています。

このイベントにより、コンシューマーがこの行の削除を処理するのに使用できるすべての情報が提供されます。

SQL Server コネクターのイベントは、Kafka ログの圧縮 と連携するように設計されています。これにより、すべてのキーの少なくとも最新のメッセージが保持されていれば、古いメッセージを削除することができます。これにより、Kafka はストレージ領域を回収でき、トピックに完全なデータセットが含まれ、キーベースの状態のリロードに使用できます。

行が削除されても、上記の delete イベント値はログの圧縮でも機能します。これは、Kafka が同じキーで以前のメッセージをすべて削除できるためです。しかし、メッセージ値が Kafka null では、同じキーを持つ すべてのメッセージ が削除できる場合にのみ使用されます。これを可能にするため、SQL Server コネクターは、常に同じキーではなく null 値を持つ特別な tombstone イベントで delete イベントに従います。

5.3.5. トランザクションメタデータ

Debezium は、tranaction メタデータ境界を表すイベントを生成し、データメッセージを強化できます。

5.3.5.1. トランザクション境界

Debezium は、すべてのトランザクション BEGIN およびのイベントを生成し ENDます。すべてのイベントにはが含まれます。

  • status - BEGIN または END
  • id : 一意のトランザクション ID の文字列表現
  • event_count （ END イベント用）: トランザクションによってエミュレートされたイベントの合計数
  • data_collections （ END イベント用）: 指定のデータコレクションから発信さ event_count れる変更により発生するイベントの数を提供する data_collection とのペアの配列

メッセージの例を以下に示します。 

{
  "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ます。

5.3.5.2. データイベントの強化

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

  • id : 一意のトランザクション 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"
  }
}

5.3.6. データベーススキーマの進化

Debezium は、時間の経過とともにスキーマの変更をキャプチャーできます。方法は SQL Server に実装されるため、スキーマの更新時にコネクターがデータ変更イベントを生成し続けるには、データベースオペレーターと共同作業を行う必要があります。

Debezium は、前に説明したように、SQL Server の変更データキャプチャー機能を使用します。そのため、SQL Server はソーステーブルで実行されるすべての変更が含まれるキャプチャーテーブルを作成します。ただし、キャプチャーテーブルは静的であるため、ソーステーブル構造が変更される際に更新する必要があります。この更新はコネクター自体によって行われませんが、昇格された権限を持つオペレーターによって実行する必要があります。

通常、スキーマ変更を実行する方法は 2 つあります。

  • コールド - これは Debezium が停止したときに実行されます。
  • hot: Debezium が実行中に実行されます。

いずれのアプローチも、短所と短所があります。

警告

いずれの場合も、同じソーステーブルで新しいスキーマの更新を行う前に、この手順を完全に実行することが重要です。したがって、手順が 1 度だけ行われるように、単一のバッチですべての DDL を実行することが推奨されます。

注記

ソーステーブルに有効なスキーマ変更がすべてサポートされる訳ではありません。このような例外の 1 つが列の名前を変更したり、タイプを変更したりすると、SQL Server では操作を実行できません。

注記

SQL Server の─メカニズム自体では必須ではありませんが、コラムをからまたはその NOT NULL 逆に変更する場合は、新しいキャプチャーインスタンスを作成 NULL する必要があります。これは、SQL Server コネクターがその変更された情報を取得できるようにするために必要です。それ以外の場合は、発生する変更イベントには、対応するフィールドの optional 値（true または false）が元の値と一致するように設定されます。

5.3.6.1. コールドスキーマの更新

これは最も安全な手順ですが、高可用性の要件のあるアプリケーションでは実現できない可能性があります。Operator は以下の一連の手順に従う必要があります。

  1. データベースレコードを生成するアプリケーションの一時停止
  2. Debezium がストリームされていないすべての変更をストリーミングするのを待ちます。
  3. コネクターを停止します。
  4. ソーステーブルスキーマにすべての変更を適用する
  5. sys.sp_cdc_enable_table 手順でパラメーター固有の値を使用して、更新ソーステーブルの新しいキャプチャーテーブルを作成します。 @capture_instance
  6. アプリケーションの再開
  7. コネクターを開始します。
  8. Debezium が新しいキャプチャーテーブルからストリーミングを開始すると、パラメーターを古いキャプチャーインスタンス名に @capture_instance 設定し、sys.sp_cdc_disable_table ストアドプロシージャーを使用して古い古いものを削除できます。
5.3.6.2. ホットスキーマの更新

ホットスキーマの更新では、アプリケーションとデータ処理のダウンタイムは必要ありません。手順自体も、コールドスキーマ更新の場合よりもはるかに簡単です。

  1. ソーステーブルスキーマにすべての変更を適用する
  2. sys.sp_cdc_enable_table 手順でパラメーター固有の値を使用して、更新ソーステーブルの新しいキャプチャーテーブルを作成します。 @capture_instance
  3. Debezium が新しいキャプチャーテーブルからストリーミングを開始すると、パラメーターを古いキャプチャーインスタンス名に @capture_instance 設定し、sys.sp_cdc_disable_table ストアドプロシージャーを使用して古い古いものを削除できます。

ホットスキーマの更新には、欠点が 1 つあります。データベーススキーマの更新と新しいキャプチャーインスタンスの作成期間はあります。この期間中に到達するすべての変更は、古い構造を持つ古いインスタンスによってキャプチャーされます。たとえば、新たに追加されたコラムに、この時間中に生成された変更イベントがまだその新しい列のフィールドが含まれていないことを意味します。このような移行期間をアプリケーションが許容しない場合は、コールドスキーマの更新に従うことが推奨されます。

5.3.6.3. 例

この例では、コラム phone_number が customers テーブルに追加されます。 

# Start the database shell
docker-compose -f docker-compose-sqlserver.yaml exec sqlserver bash -c '/opt/mssql-tools/bin/sqlcmd -U sa -P $SA_PASSWORD -d testDB'
-- Modify the source table schema
ALTER TABLE customers ADD phone_number VARCHAR(32);

-- Create the new capture instance
EXEC sys.sp_cdc_enable_table @source_schema = 'dbo', @source_name = 'customers', @role_name = NULL, @supports_net_changes = 0, @capture_instance = 'dbo_customers_v2';
GO

-- Insert new data
INSERT INTO customers(first_name,last_name,email,phone_number) VALUES ('John','Doe','john.doe@example.com', '+1-555-123456');
GO

Kafka Connect ログには、以下のようなメッセージが含まれます。 

connect_1    | 2019-01-17 10:11:14,924 INFO   ||  Multiple capture instances present for the same table: Capture instance "dbo_customers" [sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_CT, startLsn=00000024:00000d98:0036, changeTableObjectId=1525580473, stopLsn=00000025:00000ef8:0048] and Capture instance "dbo_customers_v2" [sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL]   [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource]
connect_1    | 2019-01-17 10:11:14,924 INFO   ||  Schema will be changed for ChangeTable [captureInstance=dbo_customers_v2, sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL]   [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource]
...
connect_1    | 2019-01-17 10:11:33,719 INFO   ||  Migrating schema to ChangeTable [captureInstance=dbo_customers_v2, sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL]   [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource]

メッセージのスキーマおよび Kafka トピックに書き込まれたメッセージの値に新しいフィールドがあります。 

...
     {
        "type": "string",
        "optional": true,
        "field": "phone_number"
     }
...
    "after": {
      "id": 1005,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "+1-555-123456"
    },
-- Drop the old capture instance
EXEC sys.sp_cdc_disable_table @source_schema = 'dbo', @source_name = 'dbo_customers', @capture_instance = 'dbo_customers';
GO

5.3.7. データタイプ

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

以下の表は、コネクターが各 SQL Server データタイプをイベントのフィールド 内 の リテラルタイプ およびセマンティクスタイプにマッピングする方法について説明しています。literal タイプは、Kafka Connect のスキーマタイプ（、、、、、、、、、、、、、、、、、、、、INT8、、INT16 INT32 INT64 FLOAT32 FLOAT64 BOOLEAN、STRING BYTES ARRAY MAPおよび）を使用して値が文字的に表される方法を記述 し STRUCTます。セマンティクスタイプは、Kafka Connect スキーマがフィールドの Kafka Connect スキーマの名前を使用してフィールドの 意味 をキャプチャーする方法について説明しています。

SQL Server のデータタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

BIT

BOOLEAN

該当なし

 

TINYINT

INT16

該当なし

 

SMALLINT

INT16

該当なし

 

INT

INT32

該当なし

 

BIGINT

INT64

該当なし

 

REAL

FLOAT32

該当なし

 

FLOAT[(N)]

FLOAT64

該当なし

 

CHAR[(N)]

STRING

該当なし

 

VARCHAR[(N)]

STRING

該当なし

 

TEXT

STRING

該当なし

 

NCHAR[(N)]

STRING

該当なし

 

NVARCHAR[(N)]

STRING

該当なし

 

NTEXT

STRING

該当なし

 

XML

STRING

io.debezium.data.Xml

XML ドキュメントの文字列表現を含みます。

DATETIMEOFFSET[(P)]

STRING

io.debezium.time.ZonedTimestamp

タイムゾーン情報が GMT であるタイムスタンプを表す文字列

その他のデータタイプのマッピングについては、以下のセクションで説明します。

カラムのデフォルト値は、対応するフィールドの Kafka Connect スキーマに伝播されます。変更メッセージには、（明示的な列の値が指定されていない）フィールドのデフォルト値が含まれるため、スキーマからデフォルト値を取得する必要はほとんどありません。

5.3.7.1. 一時的な値

タイムゾーン情報が含まれる SQL Server の DATETIMEOFFSET データタイプ以外の一時的なタイプは、time.precision.mode 設定プロパティーの値によって異なります。time.precision.mode 設定プロパティーが adaptive （デフォルト）に設定されると、コネクターはコラムのデータタイプ定義に基づいて一時タイプのリテラルタイプおよびセマンティクスタイプを判断し、イベントがデータベースの値を 正確 に表します。

SQL Server のデータタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

DATE

INT32

io.debezium.time.Date

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

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

INT32

io.debezium.time.Time

タイムゾーン情報が含まれ、午前 1 時を経過したミリ秒数を表します。

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

INT64

io.debezium.time.MicroTime

タイムゾーン情報が含まれ、午前 1 時以内に経過したマイクロ秒数を表します。

TIME(7)

INT64

io.debezium.time.NanoTime

タイムゾーン情報が含まれ、ナノ秒数（ナノ秒）を示します。

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、コネクターは事前定義された Kafka Connect の論理タイプを使用します。これは、コンシューマーがビルトインの Kafka Connect の論理タイプのみを認識し、可変精度の値を処理することができない場合に便利です。一方、SQL Server は 10 分のマイクロ秒の精度に対応しているため、connect time Precision モードのコネクターによって生成されたイベントにより、データベース列に分 数 秒の精度が 3 よりも大きいと、精度 が失わ れます。

SQL Server のデータタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

DATE

INT32

org.apache.kafka.connect.data.Date

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

TIME([P])

INT64

org.apache.kafka.connect.data.Time

毎時からのミリ秒数を表し、タイムゾーン情報が含まれません。SQL Server では、0 - 7 の範囲で最大 10 分のマイクロ秒の精度を保存 P できますが、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

エポックからの経過時間（ミリ秒単位）を表し、タイムゾーン情報が含まれません。SQL Server では、0 - 7 の範囲で最大 10 分のマイクロ秒の精度を保存 P できますが、P> 3 ではこのモードの精度が失われてしまいます。

5.3.7.1.1. タイムスタンプの値

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

Kafka Connect および Debezium を実行している JVM のタイムゾーンはこの変換には影響しないことに注意してください。

5.3.7.2. 10 進数の値

SQL Server のデータタイプ

リテラルタイプ（スキーマタイプ）

セマンティクスタイプ（スキーマ名）

備考

NUMERIC[(P[,S])]

BYTES

org.apache.kafka.connect.data.Decimal

scale schema パラメーターには、変更する 10 進数の数字を表す整数が含まれます。connect.decimal.precision schema パラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

DECIMAL[(P[,S])]

BYTES

org.apache.kafka.connect.data.Decimal

scale schema パラメーターには、変更する 10 進数の数字を表す整数が含まれます。connect.decimal.precision schema パラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

SMALLMONEY

BYTES

org.apache.kafka.connect.data.Decimal

scale schema パラメーターには、変更する 10 進数の数字を表す整数が含まれます。connect.decimal.precision schema パラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

MONEY

BYTES

org.apache.kafka.connect.data.Decimal

scale schema パラメーターには、変更する 10 進数の数字を表す整数が含まれます。connect.decimal.precision schema パラメーターには、指定の 10 進数値の精度を表す整数が含まれます。

5.4. SQL Server コネクターのデプロイ

SQL Server コネクターのインストールは、JAR のみのダウンロード、Kafka Connect 環境に抽出し、プラグインの親ディレクトリーを Kafka Connect 環境で指定する必要がある単純なプロセスです。

前提条件

手順

  1. Debezium SQL Server コネクター をダウンロードします。
  2. ファイルを Kafka Connect 環境に抽出します。

  3. プラグインの親ディレクトリーを Kafka Connect に追加し plugin.pathます。 

    plugin.path=/kafka/connect
注記

上記の例では、Debezium SQL Server コネクターを /kafka/connect/debezium-connector-sqlserver パスに抽出していることを前提としています。

  1. Kafka Connect プロセスを再起動します。これにより、新しい JAR が確実に検出されます。

関連情報

デプロイメントプロセスおよび AMQ Streams でのコネクターのデプロイに関する詳細は、『Debezium インストールガイド』を参照してください。

5.4.1. 設定例

コネクターを使用して特定の SQL Server データベースまたはクラスターの変更イベントを生成するには、以下を実行します。

  1. SQL Server で必要に応じ て、データベースで Events イベントを公開します。
  2. SQL Server コネクターの設定ファイルを作成します。

コネクターが起動すると、SQL Server データベースのスキーマの一貫したスナップショットを取得し、変更をストリーミングし、挿入、更新、および削除されるすべての行に対してイベントを生成します。スキーマおよびテーブルのサブセットのイベントを生成することもできます。任意で、機密性の高い、大きすぎる、または必要でないコラムを無視し、マスク、または切り捨てられます。

以下は、192.168.99.100 のポート 1433 で SQL Server サーバーを監視するコネクターインスタンスの設定例です fullfillment。通常、コネクターで使用できる設定プロパティーを使用して、.yaml ファイルで Debezium SQL Server コネクターを設定します。 

apiVersion: kafka.strimzi.io/v1beta1
  kind: KafkaConnector
  metadata:
    name: inventory-connector  1
    labels: strimzi.io/cluster: my-connect-cluster
  spec:
    class: io.debezium.connector.sqlserver.SqlServerConnector 2
    config:
      database.hostname: 192.168.99.100  3
      database.port: 1433 4
      database.user: debezium  5
      database.password: dbz  6
      database.dbname: testDB  7
      database.server.name: fullfullment 8
      database.whitelist: dbo.customers   9
      database.history.kafka.bootstrap.servers: my-cluster-kafka-bootstrap:9092  10
      database.history.kafka.topic: dbhistory.fullfillment  11
1
Kafka Connect サービスに登録した場合のコネクターの名前。
2
この SQL Server コネクタークラスの名前。
3
SQL Server インスタンスのアドレス。
4
SQL Server インスタンスのポート番号。
5
SQL Server ユーザーの名前
6
SQL Server ユーザーのパスワード
7
変更を取得するデータベースの名前。
8
ネームスペースを形成する SQL Server インスタンス/クラスターの論理名。Avro Connector が使用されたときに、コネクターが書き込む Kafka トピックの名前、Kafka Connect スキーマ名、および対応する Avro スキーマの namespace で使用されます。
9
Debezium の変更がキャプチャーされるすべてのテーブルの一覧。
10
このコネクターが DDL ステートメントの書き込みおよび復元に使用する Kafka ブローカーのリスト。
11
コネクターが DDL ステートメントを作成し、リカバリーするデータベース履歴トピックの名前。このトピックは内部での使用のみを目的としており、コンシューマーが使用しないでください。

これらの設定で指定できる コネクタープロパティーの完全なリスト を参照してください。

この設定は、POST から稼働中の Kafka Connect サービスに送信できます。これにより、設定を記録し、SQL Server データベースに接続する 1 つのコネクタータスクを開始し、トランザクションログを読み取り、イベントを Kafka トピックに記録します。

5.4.2. モニタリング

Debezium SQL Server コネクターには、Zookeeper、Kafka、および Kafka Connect がある JMX メトリクスの組み込みサポートに加えて、3 つのメトリクスタイプがあります。

JMX でこれらのメトリクスを公開する方法については、モニタリングドキュメント を参照してください。

5.4.2.1. スナップショットメトリクス

MBean はです debezium.sql_server:type=connector-metrics,context=snapshot,server=<database.server.name>。

属性名

型

説明

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

TotalTableCount

int

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

RemainingTableCount

int

スナップショットがコピーしたテーブルの数。

SnapshotRunning

boolean

スナップショットが起動しているかどうか。

SnapshotAborted

boolean

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

SnapshotCompleted

boolean

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

SnapshotDurationInSeconds

long

スナップショットが完了しなかった場合でも、これまでスナップショットが取得した秒数の合計数。

RowsScanned

Map<String, Long>

スナップショットの各テーブルに対してスキャンされる行数が含まれるマップ。テーブルは処理中にマップに徐々に追加されます。テーブルの完了後にスキャンされた 10,000 行をすべて更新します。

5.4.2.2. ストリーミングメトリクス

MBean はです debezium.sql_server:type=connector-metrics,context=streaming,server=<database.server.name>。

属性名

型

説明

LastEvent

string

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

MilliSecondsSinceLastEvent

long

コネクターが最新のイベントを読み取り、処理したからの経過時間（ミリ秒単位）。

TotalNumberOfEventsSeen

long

最後に起動またはリセット以降にこのコネクターが認識したイベントの合計数。

NumberOfEventsFiltered

long

コネクターに設定されたホワイトリストまたはブラックリストのフィルタリングルールでフィルターされたイベントの数。

MonitoredTables

string[]

コネクターによって監視されるテーブルのリスト。

QueueTotalCapcity

int

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

QueueRemainingCapcity

int

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

Connected

boolean

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

MilliSecondsBehindSource

long

最後に変更イベントのタイムスタンプとコネクターの処理の間隔（ミリ秒単位）。値には、データベースサーバーとコネクターが実行されているマシンのクロック間の違いが反映されます。

NumberOfCommittedTransactions

long

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

SourceEventPosition

map<string, string>

最後に受信したイベントのコーディネート。

LastTransactionId

string

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

5.4.2.3. スキーマ履歴のメトリクス

MBean はです debezium.sql_server:type=connector-metrics,context=schema-history,server=<database.server.name>。

属性名

型

説明

Status

string

STOPPED RECOVERING （ストレージからの履歴をリカバリー）のいずれか。データベース履歴の状態を RUNNING 記述します。

RecoveryStartTime

long

リカバリーの開始時の時間（Eepoch 秒）。

ChangesRecovered

long

リカバリーフェーズで読み込まれた変更の数。

ChangesApplied

long

リカバリー中およびランタイム時のスキーマ変更の合計数。

MilliSecondsSinceLastRecoveredChange

long

最後の変更後に経過したミリ秒数。最後の変更が履歴ストアから復元されました。

MilliSecondsSinceLastAppliedChange

long

最後の変更が適用されてから経過したミリ秒数。

LastRecoveredChange

string

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

LastAppliedChange

string

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

5.4.3. コネクタープロパティー

以下の設定プロパティーは、デフォルト値が利用可能でない限り 必要 になります。

プロパティー

デフォルト

説明

name

 

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

connector.class

 

コネクターの Java クラスの名前。SQL Server コネクターに常に io.debezium.connector.sqlserver.SqlServerConnector の値を使用してください。

tasks.max

1

このコネクターに作成する必要のあるタスクの最大数。SQL Server コネクターは常に単一のタスクを使用するため、この値は使用されないため、デフォルト値は常に受け入れ可能です。

database.hostname

 

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

database.port

1433

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

database.user

 

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

database.password

 

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

database.dbname

 

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

database.server.name

 

監視する特定の SQL Server データベースサーバーの名前空間を特定して提供する論理名。このコネクターから成るすべての Kafka トピック名の接頭辞として使用されるため、論理名は他のすべてのコネクター全体で一意にする必要があります。英数字とアンダースコアのみを使用してください。

database.history.kafka.topic

 

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

database.history​.kafka.bootstrap.servers

 

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

table.whitelist

 

監視するテーブルの完全修飾テーブル識別子と一致する正規表現のオプションのコンマ区切りリスト。ホワイトリストに含まれていないテーブルはすべて監視から除外されます。各識別子は schemaName.tableName の 形式 です。デフォルトでは、コネクターは監視される各スキーマのすべてのシステムテーブルを監視します。とは使用されない場合があり table.blacklistます。

table.blacklist

 

監視から除外されるテーブルの完全修飾テーブル識別子と一致する正規表現のオプションのコンマ区切りリスト。ブラックリストに含まれていないテーブルはすべて監視されます。各識別子は schemaName.tableName の 形式 です。とは使用されない場合があり table.whitelistます。

column.blacklist

空の文字列

変更イベントメッセージ値から除外される必要のある列の完全修飾名に一致する正規表現のオプションのコンマ区切りリスト。カラムの完全修飾名は schemaName.tableName . columnName 形式です。プライマリーキーの列は、値からブラックリストに指定した場合でも、イベントのキーに常に含まれます。

time.precision.mode

adaptive

時間、日付、およびタイムスタンプは、異なるタイプの精度で表すことができます。たとえば、adaptive （デフォルト）は、データベース列のタイプに応じてミリ秒、マイクロ秒、またはナノ秒のいずれかの精度を使用して、データベース内で時間とタイムスタンプの値を正確にキャプチャーします。または、Kafka Connect の組み込み表現を時間、日付、およびタイムスタンプの値に connect 常に表します。「 一時値 」を参照してください。

tombstones.on.delete

true

削除イベントの後に tombstone イベントを生成するかどうかを制御します。
削除操作 true が削除イベントと後続の tombstone イベントによって表される場合。削除イベント false のみを送信する場合。
tombstone イベント（デフォルトの動作）を生成すると、Kafka はソースレコードが削除されると、指定のキーに関連するすべてのイベントを完全に削除できます。

column.truncate.to.length.chars

該当なし

フィールドの値が指定された文字数よりも長い場合に、変更イベントメッセージの値で切り捨てられる必要のある文字ベースの列の完全修飾名に一致する正規表現のオプションのコンマ区切りリスト。異なる長さを持つ複数のプロパティーを 1 つの設定で使用できますが、それぞれの長さは正の整数である必要があります。カラムの完全修飾名は schemaName.tableName . columnName 形式です。

column.mask.with.length.chars

該当なし

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

column.propagate.source.type

該当なし

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

datatype.propagate.source.type

該当なし

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

message.key.columns

空の文字列

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

以下の 高度な 設定プロパティーには、ほとんどの場合で動作するため、コネクターの設定で指定する必要はほとんどありません。

プロパティー

デフォルト

説明

snapshot.mode

initial

構造の最初のスナップショットと、任意でキャプチャーされたテーブルのデータを取得するためのモード。スナップショットが完了すると、コネクターはデータベースの変更ログから変更イベントを引き続き読み取ります。

サポートされる値は：
initial: で、キャプチャーされたテーブルの構造およびデータのスナップショットを作成します。トピックに、キャプチャーされたテーブルからのデータの完全な表現を組み込む必要がある場合に便利です。キャプチャーされたテーブルのスナップショットのみを作成し
schema_onlyます。今後の変更のみがトピックに伝播される必要がある場合に役に立ちます。

snapshot.isolation.mode

repeatable_read

使用するトランザクション分離レベルと、監視対象のテーブルをコネクターがロックする時間を制御するモード。、read_uncommitted、、read_committed repeatable_read snapshotおよびの 5 つの値があります（ exclusive 実際には、exclusive モードは反復可能な読み取り分離レベルを使用しますが、読み取りにはすべてのテーブルに対して排他的ロックが行われます）。

これは、read_committed read_uncommitted モードにより snapshot、初期スナップショット時に他のトランザクションがテーブル行の更新を妨げることはありませんが、exclusive およびの作業は行われませ repeatable_read ん。

もう 1 つの側面として、データの一貫性があります。初期スナップショット exclusive snapshot およびストリーミングログがリニア履歴を構成するのは、およびモードのみになります。repeatable_read および read_committed モードの場合は、たとえば、追加されたレコードが、初期スナップショットでは、1 回、ストリーミングフェーズでは 2 回、という可能性があります。それにもかかわらず、整合性レベルはデータのミラーリングに対して行う必要があります。データの一貫性保証は read_uncommitted ありません（一部のデータは損失または破損する可能性があります）。

event.processing​.failure.handling.mode

fail

イベントの処理中にコネクターが例外に応答する方法を指定します fail （問題のあるイベントのオフセットを示唆）、コネクターが停止します
warn。は、問題のあるイベントが省略され、問題のあるイベントのオフセットがログに記録される原因と
skip なります。は、問題のあるイベントをスキップします。

poll.interval.ms

1000

新しい変更イベントが表示されるまでコネクターが待機する時間（ミリ秒単位）を指定する正の整数値。デフォルトは 1000 ミリ秒または 1 秒です。

max.queue.size

8192

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

max.batch.size

2048

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

heartbeat.interval.ms

0

ハートビートメッセージを送信する頻度を制御します。
このプロパティーには、コネクターがハートビートトピックにメッセージを送信する頻度を定義する間隔（ミリ秒単位）が含まれます。これは、コネクターがデータベースから変更イベントを受信しているかどうかを監視するために使用できます。また、キャッシュされていないテーブルのレコードのみが長くなる場合には、ハートビートメッセージも利用する必要があります。このような状況では、コネクターは引き続きデータベースからログを読み取るが、Kafka に変更メッセージを出力せず、オフセットの更新が Kafka にコミットされないことを意味します。これにより、コネクターの再起動後にイベントが再送信されることがあります。ハートビートメッセージを送信しないよう 0 に、このパラメーターをに設定します。
デフォルトでは無効です。

heartbeat.topics.prefix

__debezium-heartbeat

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

snapshot.delay.ms

 

起動後のスナップショットの取得前にコネクターが待機する間隔（ミリ秒単位）
。クラスターで複数のコネクターを起動する際にスナップショットの中断を回避するために使用できます。コネクターのリバランスが発生する可能性があります。

snapshot.fetch.size

2000

スナップショットの作成中に、各テーブルから 1 回読み込むべき行の最大数を指定します。コネクターはこのサイズの複数のバッチでテーブルコンテンツを読み取ります。デフォルトは 2000 です。

snapshot.lock.timeout.ms

10000

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

snapshot.select.statement.overrides

 

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

sanitize.field.names

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

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

database.server.timezone

 

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

これは、サーバーから取得したトランザクションタイムスタンプ(ts_ms)のタイムゾーンを定義するために使用されます（実際にはゾーンされていません）。デフォルト値は unset です。SQL Server 2014 以前のバージョンで実行され、データベースサーバーに異なるタイムゾーンと Debezium コネクターを実行する JVM を使用する場合のみ指定する必要があります。
設定を解除すると、デフォルトの動作では、Debezium コネクターを実行する仮想マシンのタイムゾーンが使用されます。この場合、SQL Server 2014 以前で実行し、サーバーとコネクターで異なるタイムゾーンを使用する場合は、ts_ms の値が正しくない可能性があります。
使用できる値は、「Z」、「UTC」、オフセット値（+02:00、CET のような短縮ゾーン ID、"Europe/Paris" など）などです。

provide.transaction.metadata

false

true Debezium に設定すると、トランザクション境界でイベントが生成され、トランザクションメタデータでデータイベントが強化されます。

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

コネクターは、Kafka プロデューサーおよびコンシューマーの作成時に使用される パススルー 設定プロパティーもサポートします。具体的には、データベース履歴に書き込む Kafka プロデューサーの作成時に、接頭辞で始まるコネクター設定プロパティーがすべて database.history.producer. 使用され、コネクターの起動時にデータベース履歴を読み取る Kafka コンシューマーの作成時に、接頭辞で始まるすべてのコネクター設定が database.history.consumer. 使用されます（接頭辞なし）。

たとえば、以下のコネクター設定プロパティーを使用して Kafka ブローカーへの接続をセキュア化 できます。

Kafka プロデューサーおよびコンシューマーの パススルー に加え、で始まるプロパティー（ database.例：） database.applicationName=debezium は JDBC URL に渡されます。 

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

Kafka プロデューサーおよびコンシューマーのすべての設定プロパティーについては、Kafka のドキュメント を参照してください。（SQL Server コネクターは 新しいコンシューマー を使用します。）

第6章 Debezium の監視

Zookeeper および Kafka が提供する JMX メトリクスを使用して、Debezium を監視できます。これらのメトリクスを使用するには、Zookeeper、Kafka、および Kafka Connect のサービスの開始時にこれらのメトリクスを有効にする必要があります。JMX を有効にするには、正しい環境変数を設定する必要があります。

注記

同じマシンで複数のサービスを実行している場合は、サービスごとに個別の JMX ポートを使用するようにしてください。

6.1. RHEL での Debezium の監視

6.1.1. ZooKeeper JMX 環境変数

ZooKeeper には JMX のサポートが組み込まれています。ローカルインストールを使用して Zookeeper を実行すると、zkServer.sh スクリプトは以下の環境変数を認識します。

JMXPORT
JMX を有効にし、JMX に使用するポート番号を指定します。この値は、JVM パラメーターを指定するために使用され -Dcom.sun.management.jmxremote.port=$JMXPORTます。
JMXAUTH
接続時に JMX クライアントがパスワード認証を使用する必要があるかどうか。true またはである必要があり falseます。デフォルトは false です。この値は、JVM パラメーターを指定するために使用され -Dcom.sun.management.jmxremote.authenticate=$JMXAUTHます。
JMXSSL
JMX クライアントが SSL/TLS を使用して接続するかどうか。true またはである必要があり falseます。デフォルトは false です。この値は、JVM パラメーターを指定するために使用され -Dcom.sun.management.jmxremote.ssl=$JMXSSLます。
JMXLOG4J
Log4J JMX MBean を無効にするかどうか。true （デフォルト）またはのどちらかでなければなりません false。デフォルトは true です。この値は、JVM パラメーターを指定するために使用され -Dzookeeper.jmx.log4j.disable=$JMXLOG4Jます。

6.1.2. Kafka JMX 環境変数

ローカルインストールを使用して Kafka を実行する場合、kafka-server-start.sh スクリプトは以下の環境変数を認識します。

JMX_PORT
JMX を有効にし、JMX に使用するポート番号を指定します。この値は、JVM パラメーターを指定するために使用され -Dcom.sun.management.jmxremote.port=$JMX_PORTます。
KAFKA_JMX_OPTS

起動時に JVM に直接渡される JMX オプション。デフォルトのオプションは以下のとおりです。

  • -Dcom.sun.management.jmxremote
  • -Dcom.sun.management.jmxremote.authenticate=false
  • -Dcom.sun.management.jmxremote.ssl=false

6.1.3. Kafka Connect JMX 環境変数

ローカルインストールを使用して Kafka を実行する場合、connect-distributed.sh スクリプトは以下の環境変数を認識します。

JMX_PORT
JMX を有効にし、JMX に使用するポート番号を指定します。この値は、JVM パラメーターを指定するために使用され -Dcom.sun.management.jmxremote.port=$JMX_PORTます。
KAFKA_JMX_OPTS

起動時に JVM に直接渡される JMX オプション。デフォルトのオプションは以下のとおりです。

  • -Dcom.sun.management.jmxremote
  • -Dcom.sun.management.jmxremote.authenticate=false
  • -Dcom.sun.management.jmxremote.ssl=false

6.2. OpenShift での Debezium のモニタリング

OpenShift で Debezium を使用している場合、で JMX ポートを開いて JMX メトリクスを取得でき 9999ます。詳細は、「 JMX オプション 」を参照してください。

さらに、Prometheus および Grafana を使用して JMX メトリクスを監視することもできます。詳細は、「 メトリクスの導入 」を参照してください。

第7章 Debezium ロギング

Debezium には幅広いログがコネクターに組み込まれており、ロギング設定を変更して、ログに表示されるログステートメントとそれらのログの送信先を制御することができます。Debezium（Kafka、Kafka Connect、および Zookeeper）は Java に Log4j ロギングフレームワークを使用します。

デフォルトでは、コネクターは起動時にかなりの便利な情報を生成しますが、コネクターがソースデータベースで維持される際に、非常に多くのログを生成します。コネクターが正常に動作している場合には、多くの場合で十分ですが、コネクターが予期せず動作している場合は不十分になる可能性があります。このような場合、ロギングレベルを変更して、コネクターが実行している内容と、それが行われていない動作を記述するより詳細なログメッセージを生成することができます。

7.1. ロギングの概念

ロギングを設定する前に、Log4J ロガー、ログレベル、およびアペンダーを理解している必要 が あります。

loggers

アプリケーションによって生成される各ログメッセージは特定の ロガー （例： io.debezium.connector.mysql）に送信されます。ロガーは階層に分けられます。たとえば、io.debezium.connector.mysql ロガーはロガーの子で、io.debezium.connector io.debezium ロガーの子です。階層の上部で、ルートロガー は下のすべてのロガーに対するデフォルトのロガー設定を定義します。

ログレベル

アプリケーションによって生成されたすべてのログメッセージには、特定の ログレベル もあります。

  1. ERROR : エラー、例外、およびその他の重要な問題
  2. WARN - 潜在的な 問題と問題
  3. INFO : ステータスおよび一般アクティビティー（通常は低ボリューム）
  4. DEBUG : 予期しない動作の診断に役立つより詳細なアクティビティー
  5. TRACE : 詳細で詳細なアクティビティー（通常は非常に高ボリューム）
アペンダー

アペンダー は基本的にログメッセージが書き込まれる宛先です。各アペンダーはログメッセージの形式を制御し、ログメッセージの表示内容をさらに制御できます。

ロギングを設定するには、各ロガーの希望レベルと、それらのログメッセージが書き込まれるアペンダーを指定します。ロガーは階層であるため、その下のすべてのロガーに対してルートロガーの設定がデフォルトとして機能します。ただし、子（または子）ロガーは上書きできます。

7.2. デフォルトのロギング設定について

Kafka Connect プロセスで Debezium コネクターを実行している場合、Kafka Connect は Kafka インストールで Log4j 設定ファイル（例： /opt/kafka/config/connect-log4j.properties）を使用します。デフォルトでは、このファイルには以下の設定が含まれます。

connect-log4j.properties

log4j.rootLogger=INFO, stdout  1

log4j.appender.stdout=org.apache.log4j.ConsoleAppender  2
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout  3
log4j.appender.stdout.layout.ConversionPattern=[%d] %p %m (%c)%n  4
...

1
デフォルトのロガー設定を定義するルートロガー。デフォルトでは、ロガーには INFO、WARN、および ERROR メッセージが含まれます。これらのログメッセージは stdout アペンダーに書き込まれます。
2
stdout アペンダーは、ファイルではなく、コンソールにログメッセージを書き込みます。
3
stdout アペンダーは、ログメッセージのフォーマットにパターン一致アルゴリズムを使用します。
4
stdout アペンダーのパターン（詳細は Log4j ドキュメント を参照してください）

他のロガーを設定しない限り、Debezium によって使用されるすべてのロガーは rootLogger 設定を継承します。

7.3. ロギングの設定

デフォルトでは、Debezium コネクターはすべての INFO、WARN、および ERROR メッセージをコンソールに書き込みます。ただし、この設定は以下の方法で変更することができます。

注記

本セクションでは、Log4j で Debezium ロギングを設定するのに使用できるいくつかの方法のみを説明します。Log4j の使用に関する詳細は、チュートリアルを検索してアペンダーを使用して特定の宛先にログメッセージを送信します。

7.3.1. ログレベルの変更

デフォルトの Debezium ロギングレベルは、コネクターの正常性を示すのに十分な情報を提供します。ただし、コネクターが正常でない場合は、ロギングレベルを変更して問題のトラブルシューティングを行うことができます。

通常、Debezium コネクターはログメッセージを生成する Java クラスの完全修飾名に一致する名前を持つログメッセージをロガーに送信します。Debezium は、パッケージを使用して同様の関数または関連関数でコードを整理します。つまり、特定のクラスまたは特定のパッケージ下にあるすべてのクラスに対してログメッセージをすべて制御できます。

手順

  1. log4j.properties ファイルを開きます。

  2. コネクターのロガーを設定します。

    この例では、MySQL コネクターとコネクターによって使用されるデータベース履歴実装のロガーを設定し、ログ DEBUG レベルのメッセージを設定します。

    log4j.properties

    ...
log4j.logger.io.debezium.connector.mysql=DEBUG, stdout  1
log4j.logger.io.debezium.relational.history=DEBUG, stdout  2

log4j.additivity.io.debezium.connector.mysql=false  3
log4j.additivity.io.debezium.relational.history=false  4
...

    1
    、DEBUG、、INFO WARNおよび ERROR メッセージを stdout アペンダー io.debezium.connector.mysql に送信するようにという名前のロガーを設定します。
    2
    、DEBUG、、INFO WARNおよび ERROR メッセージを stdout アペンダー io.debezium.relational.history に送信するようにという名前のロガーを設定します。
    3 4
    追加をオフにします。これは 、 ログメッセージが親ロガーの追加者に送信されないことを意味します（これにより、複数のアペンダーを使用する際に重複ログメッセージが表示されるのを防ぐことができます）。

  3. 必要に応じて、コネクター内のクラスの特定のサブセットのロギングレベルを変更します。

    コネクター全体のロギングレベルを増やすと、ログの詳細レベルが高まるため、何が発生しているかを理解することが困難になる可能性があります。このような場合、トラブルシューティングを行う問題に関連するクラスのサブセットのロギングレベルを変更できます。

    1. コネクターのロギングレベルをまたはのいずれ DEBUG かに設定し TRACEます。

    2. コネクターのログメッセージを確認します。

      トラブルシューティングを行う問題に関連するログメッセージを見つけます。各ログメッセージの最後には、メッセージを生成した Java クラスの名前が表示されます。

    3. コネクターのログレベルをに設定し INFOます。

    4. 特定した各 Java クラスのロガーを設定します。

      たとえば、binlog の処理時に MySQL コネクターが一部のイベントをスキップする理由が不明なシナリオについて考えてみましょう。コネクター全体でオン DEBUG または TRACE ロギングを行うのではなく、コネクターのロギングレベルを維持 INFO し、binlog を読み取るクラス TRACE のみを設定 DEBUG または設定できます。

      log4j.properties

      ...
log4j.logger.io.debezium.connector.mysql=INFO, stdout
log4j.logger.io.debezium.connector.mysql.BinlogReader=DEBUG, stdout
log4j.logger.io.debezium.relational.history=INFO, stdout

log4j.additivity.io.debezium.connector.mysql=false
log4j.additivity.io.debezium.relational.history=false
log4j.additivity.io.debezium.connector.mysql.BinlogReader=false
...

7.3.2. マップされた診断コンテキストの追加

ほとんどの Debezium コネクター（および Kafka Connect ワーカー）は複数のスレッドを使用して異なるアクティビティーを実行します。これにより、ログファイルを表示し、特定の論理アクティビティーのログメッセージのみを見つけることが困難になる可能性があります。ログメッセージの検索を容易にするため、Debezium は各スレッドの追加情報を提供する マッピングされた診断コンテキスト (MDC)を複数提供します。

Debezium は、以下の MDC プロパティーを提供します。

dbz.connectorType
コネクタータイプの短いエイリアス。たとえば、、MySql Mongo Postgres、などがあります。同じ タイプ のコネクターに関連付けられたすべてのスレッドは同じ値を使用するため、これを使用して特定のタイプのコネクターによって生成されたすべてのログメッセージを見つけることができます。
dbz.connectorName
コネクターの設定に定義されたコネクターまたはデータベースサーバーの名前。たとえば products、serverA、などです。特定の コネクターインスタンスに関連付けられたすべてのスレッドは同じ値を使用する ため、特定のコネクターインスタンスによって生成されたすべてのログメッセージを確認できます。
dbz.connectorContext
コネクターのタスク内で実行される個別のスレッドとして実行されるアクティビティーの省略名。たとえば、、main binlog snapshot、などがあります。コネクターがテーブルやコレクションなど、特定のリソースにスレッドを割り当てると、代わりにそのリソースの名前を使用できます。コネクターに関連付けられた各スレッドは個別の値を使用するため、この特定のアクティビティーに関連するログメッセージをすべて見つけることができます。

コネクターの MDC を有効にするには、log4j.properties ファイルにアペンダーを設定します。

手順

  1. log4j.properties ファイルを開きます。

  2. サポートされる Debezium MDC プロパティーのいずれかを使用するようにアペンダーを設定します。

    以下の例では、以下の MDC プロパティーを使用するよう stdout アペンダーが設定されています。

    log4j.properties

    ...
log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %-5p  %X{dbz.connectorType}|%X{dbz.connectorName}|%X{dbz.connectorContext}  %m   [%c]%n
...

    これにより、以下のようなログメッセージが生成されます。 

    ...
2017-02-07 20:49:37,692 INFO   MySQL|dbserver1|snapshot  Starting snapshot for jdbc:mysql://mysql:3306/?useInformationSchema=true&nullCatalogMeansCurrent=false&useSSL=false&useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=convertToNull with user 'debezium'   [io.debezium.connector.mysql.SnapshotReader]
2017-02-07 20:49:37,696 INFO   MySQL|dbserver1|snapshot  Snapshot is using user 'debezium' with these MySQL grants:   [io.debezium.connector.mysql.SnapshotReader]
2017-02-07 20:49:37,697 INFO   MySQL|dbserver1|snapshot  	GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'debezium'@'%'   [io.debezium.connector.mysql.SnapshotReader]
...

    ログの各行には、コネクタータイプ（例： MySQL）、コネクターの名前（例： dbserver1）、およびスレッドのアクティビティー（例： snapshot）が含まれます。

7.4. OpenShift での Debezium ロギング

OpenShift で Debezium を使用している場合、Kafka Connect ロガーを使用して Debezium ロガーおよびロギングレベルを設定できます。詳細は、「 Kafka Connect ロガー 」を参照してください。

第8章 アプリケーションの Debezium コネクターの設定

デフォルトの Debezium コネクター動作がアプリケーションに適したではない場合、以下の Debezium 機能を使用して必要な動作を設定できます。

  • ByLogicalTableRouter SMT は、データ変更イベントレコードを指定したトピックに再度ルーティングします。
  • ExtractNewRecordState SMT は、一部の Kafka コンシューマーで必要とされる可能性のある単純な形式で、データ変更イベントレコードの複雑な構造をフラット化します。
  • PostgreSQL、MongoDB、または SQL Server コネクターの Avro シリアライズ を設定すると、イベントレコードコンシューマーの変更がレコードスキーマに対応できるようになります。
  • CloudEventsConverter では、Debezium コネクターは CloudEvents 仕様に準拠する変更イベントレコードを出力できます。

8.1. 指定したトピックへのルーティング変更イベントレコード

データ変更イベントが含まれる各 Kafka レコードには、デフォルトの宛先トピックがあります。必要な場合は、レコードが Kafka Connect コンバーターに到達する前に指定したトピックにレコードを再ルート指定できます。そのため、Debezium は SMT(Single ByLogicalTableRouter Message transformation)を提供します。Debezium コネクターの Kafka Connect 設定でこの変換を設定します。設定オプションを使用すると、以下を指定できます。

  • 再ルートを作成するレコードを識別する式
  • 宛先トピックに解決する式
  • 宛先トピックに再ルーティングされるレコード間の一意の鍵を確保する方法

変換設定が必要な動作を提供するのはユーザー次第です。Debezium は、変換の設定から生じる動作を検証しません。

ByLogicalTableRouter 変換は Kafka Connect SMT です。

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

8.1.1. 指定したトピックへのルーティングレコードのユースケース

デフォルトの動作では、Debezium コネクターは、名前がデータベースの名前から形成されているトピックと、変更が行われたテーブルの名前が Debezium コネクターによって各変更イベントレコードを送信することです。つまり、トピックは 1 つの物理テーブルのレコードを受け取ります。トピックで複数の物理テーブルのレコードを受信する場合、Debezium コネクターがそのトピックにレコードを再ルーティングするように設定する必要があります。

論理テーブル

論理表は、複数の物理テーブルのルーティングレコードの一般的なユースケースです。論理表には、スキーマがすべて同じスキーマを持つ複数の物理テーブルがあります。たとえば、シャード化されたテーブルには同じスキーマがあります。論理テーブルは、db_shard1.my_table およびという 2 つ以上のシャードテーブルで構成される場合があります db_shard2.my_table。テーブルはシャードごとに異なり、物理的には異なりますが、それらが論理テーブルを形成します。シャードのテーブルのテーブルの変更イベントレコードを同じトピックに再ルーティングできます。

パーティション化された PostgreSQL テーブル

Debezium PostgreSQL コネクターがパーティション設定されたテーブルの変更を取得する場合、イベントレコードの変更が各パーティションに対して異なるトピックにルーティングされることがデフォルトの動作になります。すべてのパーティションから 1 つのトピックにレコードを出力するには、ByLogicalTableRouter SMT を設定します。パーティションテーブルの各キーは一意であることが保証されるので、SMT がキーを固有のキー key.enforce.uniqueness=false を確保するようにキーフィールドを追加しないようにを設定します。キーフィールドを追加するのはデフォルトの動作です。

8.1.2. 複数テーブルのルーティングレコードの例

複数の物理テーブルのイベントレコードを同じトピックにルーティングするには、Debezium コネクターの Kafka Connect 設定で ByLogicalTableRouter 変換を設定します。ByLogicalTableRouter SMT の設定では、以下を判断する正規表現を指定する必要があります。

  • レコードをルーティングするテーブル。これらのテーブルはすべて同じスキーマを持つ必要があります。
  • 宛先トピック名。

たとえば、.properties ファイルの設定は以下のようになります。 

transforms=Reroute
transforms.Reroute.type=io.debezium.transforms.ByLogicalTableRouter
transforms.Reroute.topic.regex=(.*)customers_shard(.*)
transforms.Reroute.topic.replacement=$1customers_all_shards
topic.regex

変換が各変更イベントレコードに適用され、特定のトピックにルーティングするかどうかを判断する正規表現を指定します。

この例では、正規表現は名前に customers_shard 文字列が含まれるテーブルへの変更の記録 (.)customers_shard(.) と一致します。これにより、以下の名前を持つテーブルのレコードを再ルート化します。

myserver.mydb.customers_shard1
myserver.mydb.customers_shard2
myserver.mydb.customers_shard3

topic.replacement
宛先トピック名を表す正規表現を指定します。変換は、各一致するレコードをこの式で識別したトピックにルーティングします。この例では、上記の 3 つのシャードテーブルのレコードは myserver.mydb.customers_all_shards トピックにルーティングされます。

8.1.3. 同じトピックにルーティングされるレコード全体で一意の鍵を確保

Debezium Change イベントキーは、テーブルのプライマリーキーを構成するテーブル列を使用します。複数の物理テーブルのレコードを 1 つのトピックにルーティングするには、イベントキーはそれらのすべてのテーブル全体で一意である必要があります。ただし、各物理テーブルには、そのテーブル内でのみ一意のプライマリーキーを設定できます。たとえば、テーブルの行には、myserver.mydb.customers_shard1 テーブルの行と同じキーの値がある場合があり myserver.mydb.customers_shard2 ます。

変更イベントレコードが同じトピックにあるテーブル全体で各イベントキーが一意になるように、ByLogicalTableRouter 変換によってフィールドが変更されイベントキーに挿入されます。デフォルトでは、挿入されたフィールドの名前はです __dbz__physicalTableIdentifier。挿入されたフィールドの値は、デフォルトの宛先トピック名です。

必要に応じて、別のフィールドをキーに挿入するように ByLogicalTableRouter 変換を設定できます。これを実行するには、key.field.name オプションを指定し、既存のプライマリーキーフィールド名と競合しないフィールド名に設定します。以下に例を示します。 

transforms=Reroute
transforms.Reroute.type=io.debezium.transforms.ByLogicalTableRouter
transforms.Reroute.topic.regex=(.*)customers_shard(.*)
transforms.Reroute.topic.replacement=$1customers_all_shards
transforms.Reroute.key.field.name=shard_id

この例では、shard_id フィールドをルーティングされたレコードのキー構造に追加します。

キーの新しいフィールドの値を調整するには、以下のいずれかのオプションを設定します。

key.field.regex
変換がデフォルトの宛先トピック名に適用され、1 つ以上の文字グループをキャプチャーする正規表現を指定します。
key.field.replacement
取得したグループの観点から、挿入されたキーフィールドの値を決定する正規表現を指定します。

以下に例を示します。 

transforms.Reroute.key.field.regex=(.*)customers_shard(.*)
transforms.Reroute.key.field.replacement=$2

この設定では、宛先のデフォルトのトピック名が以下のようになります。

myserver.mydb.customers_shard1
myserver.mydb.customers_shard2
myserver.mydb.customers_shard3

変換では、2 番目のキャプチャーグループ（シャード番号）の値をキーの新しいフィールドの値として使用します。この例では、挿入された key フィールドの値は、1、2、またはです 3。

テーブルにグローバルに一意の鍵が含まれ、キー構造を変更する必要がない場合は、key.enforce.uniqueness プロパティーをに設定し falseます。 

...
transforms.Reroute.key.enforce.uniqueness=false
...

8.1.4. ByLogicalTableRouter 変換を設定するオプション

プロパティー

デフォルト

説明

topic.regex

 

変換が各変更イベントレコードに適用され、特定のトピックにルーティングするかどうかを判断する正規表現を指定します。

topic.replacement

 

宛先トピック名を表す正規表現を指定します。変換は、各一致するレコードをこの式で識別したトピックにルーティングします。この式は、に指定する正規表現によってキャプチャーされるグループを参照でき topic.regexます。グループを参照するには、、$1 $2、などを指定します。

key.enforce.uniqueness

true

レコードの変更イベントキーにフィールドを追加するかどうかを示します。キーフィールドを追加すると、変更イベントレコードが同じトピックになるテーブル全体で各イベントキーが一意になります。これは、同じキーを持つものの、異なるソーステーブルから生成されたレコードの変更イベントの競合を防ぐのに役立ちます。

変換でキーフィールドを追加したくない false かどうかを指定します。たとえば、パーティション化された PostgreSQL テーブルから 1 つのトピックにルーティングレコードがある場合には、パーティションが設定された PostgreSQL テーブルで一意の鍵 key.enforce.uniqueness=false が保証されているように設定できます。

key.field.name

__dbz__physicalTableIdentifier

変更イベントキーに追加するフィールドの名前。このフィールドの値は、元のテーブル名を識別します。SMT でこのフィールドを追加するには、がデフォルトであるで trueある key.enforce.uniqueness 必要があります。

key.field.regex

 

変換がデフォルトの宛先トピック名に適用され、1 つ以上の文字グループをキャプチャーする正規表現を指定します。SMT がこの式を適用するには、がデフォルトであるで trueある key.enforce.uniqueness 必要があります。

key.field.replacement

 

に指定された式がキャプチャーしたグループの形式で、挿入されたキーフィールドの値を決定する正規表現を指定し key.field.regexます。SMT がこの式を適用するには、がデフォルトであるで trueある key.enforce.uniqueness 必要があります。

8.2. Debezium 変更イベントからのソースレコード after 状態の抽出

Debezium データ変更イベントには、多くの情報を提供する複雑な構造があります。Debezium 変更イベントを実行する Kafka レコードには、このすべての情報が含まれます。ただし、Kafka エコシステムの一部は、フィールド名と値のフラット構造を提供する Kafka レコードを想定する可能性があります。このようなレコードを提供するために、Debezium は ExtractNewRecordState 単一のメッセージ変換(SMT)を提供します。Debezium 変更イベントが含まれる Kafka レコードよりも単純なフォーマットを持つ Kafka レコードが必要な場合に、この変換を設定します。

ExtractNewRecordState 変換は Kafka Connect SMT です。

この変換は SQL データベースコネクターのみで利用できます。

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

8.2.1. Debezium 変更イベント構造の説明

Debezium は、複雑な構造を持つデータ変更イベントを生成します。各イベントは、以下の 3 つの部分で構成されます。

  • メタデータ。これには以下が含まれますが、これに限定されません。

    • 変更後の操作
    • 変更が行われたデータベース名やテーブル名などのソース情報
    • 変更が行われた時点のタイムスタンプ
    • オプションのトランザクション情報
  • 変更前の行データ
  • 変更後の行データ

たとえば、UPDATE 変更イベントの構造は以下のようになります。 

{
	"op": "u",
	"source": {
		...
	},
	"ts_ms" : "...",
	"before" : {
		"field1" : "oldvalue1",
		"field2" : "oldvalue2"
	},
	"after" : {
		"field1" : "newvalue1",
		"field2" : "newvalue2"
	}
}

この複雑な形式は、システムで発生する変更に関する最も重要な情報を提供します。ただし、Kafka エコシステムに他のコネクターまたはその他の部分では、以下のような単純な形式でデータが想定されます。 

{
	"field1" : "newvalue1",
	"field2" : "newvalue2"
}

コンシューマーに必要な Kafka レコード形式を提供するには、ExtractNewRecordState SMT を設定します。

8.2.2. Debezium ExtractNewRecordState 変換の動作

ExtractNewRecordState SMT は、Kafka レコードの Debezium 変更イベントから after フィールドを抽出します。SMT は元の変更イベントをその after フィールドのみに置き換え、単純な Kafka レコードを作成します。

Debezium コネクターまたは Debezium コネクターによって出力されるメッセージを消費するシンクコネクターの ExtractNewRecordState SMT を設定できます。シンクコネクターの設定 ExtractNewRecordState の利点は、Apache Kafka に保存されているレコードに Debezium 変更イベント全体が含まれることです。SMT をソースまたはシンクコネクターに適用する決定は、特定のユースケースによって異なります。

以下のいずれかを行うように変換を設定できます。

  • 変更イベントから単純な Kafka レコードにメタデータを追加します。デフォルトの動作では、SMT はメタデータを追加しません。
  • ストリームの DELETE オペレーションの変更イベントが含まれる Kafka レコードを保持します。デフォルトの動作では、SMT が DELETE 操作変更の Kafka レコードをドロップします。これは、ほとんどのコンシューマーがイベントに対応できないためです。

データベース DELETE 操作により、Debezium は以下の 2 つの Kafka レコードを生成します。

  • before 行データや他 "op": "d", のフィールドを含むレコード。
  • 削除された行と同じキーと、の値と同じ tombstone レコード null。このレコードは Apache Kafka のマーカーです。これは、ログの圧縮 により、このキーを持つすべてのレコードを削除できることを示しています。

before 行データが含まれるレコードを削除する代わりに、ExtractNewRecordData SMT を設定して以下のいずれかを行うように設定できます。

  • レコードをストリームに保持し、"value": "null" フィールドのみが含まれるように編集します。
  • レコードをストリームに保持し、"__deleted": "true" エントリーを追加したフィールドで、value フィールドに追加されたキーと値のペアが含まれる before フィールドが含まれるように編集します。

同様に、tombstone レコードを削除する代わりに、ExtractNewRecordData SMT を設定して、そのストリームに tombstone レコードを保持するように設定できます。

8.2.3. ExtractNewRecordState 変換の設定

ExtractNewRecordState SMT 設定の詳細をコネクターの設定に追加して、Kafka Connect ソースまたはシンクコネクターで Debezium SMT を設定します。デフォルトの動作を取得するには、.properties ファイルで以下のように設定します。 

transforms=unwrap,...
transforms.unwrap.type=io.debezium.transforms.ExtractNewRecordState

Kafka Connect コネクター設定では、Kafka Connect で SMT を適用 transforms= する順序で複数のコンマ区切りの SMT エイリアスを設定できます。

以下の .properties 例では、複数の ExtractNewRecordState オプションを設定します。 

transforms=unwrap,...
transforms.unwrap.type=io.debezium.transforms.ExtractNewRecordState
transforms.unwrap.drop.tombstones=false
transforms.unwrap.delete.handling.mode=rewrite
transforms.unwrap.add.fields=table,lsn
drop.tombstones=false
イベントストリームの DELETE オペレーションの tombstone レコードを保持します。
delete.handling.mode=rewrite

DELETE 操作では、変更イベントの value フィールドをフラット化して Kafka レコードを編集します。value フィールドには、フィールドにあるキーと値のペアを直接含め before ます。SMT を追加し __deleted、に設定します。以下 trueに例を示します。 

"value": {
  "pk": 2,
  "cola": null,
  "__deleted": "true"
}
add.fields=table,lsn
table および lsn フィールドの change イベントメタデータを単純化された Kafka レコードに追加します。

8.2.4. Kafka レコードへのメタデータの追加例

ExtractNewRecordState SMT は、単純化された Kafka レコードに元の変更イベントメタデータを追加できます。たとえば、単純化されたレコードのヘッダーまたは値に、以下のいずれかを含める必要がある場合があります。

  • 変更後の操作のタイプ
  • 変更されたデータベースまたはテーブルの名前
  • Postgres LSN フィールドなどのコネクター固有のフィールド

簡素化された Kafka レコードのヘッダーにメタデータを追加するには、add.header オプションを指定します。簡素化された Kafka レコードの値にメタデータを追加するには、add.fields オプションを指定します。これらのオプションごとに、変更イベントフィールド名のコンマ区切りリストを指定します。空白は指定しないでください。フィールド名が重複している場合は、これらのフィールドのいずれかのメタデータを追加するには、構造とフィールドを指定します。以下に例を示します。 

transforms=unwrap,...
transforms.unwrap.type=io.debezium.transforms.ExtractNewRecordState
transforms.unwrap.add.fields=op,table,lsn,source.ts_ms
transforms.unwrap.add.headers=db
transforms.unwrap.delete.handling.mode=rewrite

この設定では、単純な Kafka レコードに以下のようなものが含まれます。 

{
 ...
	"__op" : "c",
	"__table": "MY_TABLE",
	"__lsn": "123456789",
	"__source_ts_ms" : "123456789",
 ...
}

また、簡素化された Kafka レコードには __db ヘッダーがあります。

簡素化された Kafka レコードでは、SMT はメタデータフィールド名に二重アンダースコアを付けます。構造を指定する場合、SMT は構造名とフィールド名との間にアンダースコアも挿入します。

DELETE 操作用の単純な Kafka レコードにメタデータを追加するには、を設定する必要もあり delete.handling.mode=rewriteます。

8.2.5. ExtractNewRecordState 変換を設定するオプション

以下の表は、ExtractNewRecordState SMT に指定できるオプションを示しています。

プロパティー

デフォルト

説明

drop.tombstones

true

Debezium は、DELETE 操作ごとに tombstone レコードを生成します。デフォルトの動作では ExtractNewRecordState、ストリームから tombstone レコードが削除されます。ストリームの tombstone レコードを維持するには、を指定し drop.tombstones=falseます。

delete.handling.mode

drop

Debezium は、DELETE 操作ごとに変更イベントレコードを生成します。デフォルトの動作では ExtractNewRecordState、これらのレコードをストリームから削除します。ストリームの DELETE オペレーションの Kafka レコードを保持するには、を none または delete.handling.mode に設定し rewriteます。

ストリームの変更イベントレコード none を保持するためにを指定します。レコードにはのみが含まれ "value": "null"ます。

ストリーム内の変更イベントレコード rewrite を維持し、レコードを編集して、value フィールドにあるキー/値のペアを含む before フィールドがあり、にもを追加 __deleted: true し valueます。これは、レコードが削除されたことを示す別の方法です。

指定時に rewrite、削除したレコードを追跡する必要がある DELETE 操作の更新済みレコードだけが存在する可能性があります。Debezium コネクターが作成する tombstone レコードをドロップするデフォルトの動作を受け入れることを検討できます。

route.by.field

 

レコードをルーティングするトピックを確認するには、行データを使用してレコードを after フィールド属性に設定します。SMT は、名前が指定された after field 属性の値と一致するトピックにレコードをルーティングします。DELETE オペレーションでは、このオプションを before フィールド属性に設定します。

たとえば、route.by.field=destination ルートの設定では、値がであるトピックに記録され after.destinationます。デフォルトの動作では、Debezium コネクターは、名前がデータベースの名前から形成されているトピックと、変更が行われたテーブルの名前が Debezium コネクターによって各変更イベントレコードを送信することです。

シンクコネクターで ExtractNewRecordState SMT を設定する場合は、宛先トピック名が単純の変更イベントレコードで更新されるデータベーステーブルの名前を指示する場合に、このオプションを設定すると役に立つ場合があります。トピック名がユースケースに適切でない場合は、イベントを再ルーティング route.by.field するように設定できます。

add.fields

 

このオプションをコンマ区切りの一覧に設定します。空白のないメタデータフィールドは単純な Kafka レコードの値に追加するメタデータフィールドです。フィールド名が重複している場合は、これらのフィールドのいずれかのメタデータを追加するには、構造とフィールドを指定します（例：） source.ts_ms。

SMT が単純化されたレコードの値にメタデータフィールドを追加すると、各メタデータフィールド名の前に二重アンダースコアが付けられます。構造仕様では、SMT は、構造名とフィールド名との間にアンダースコアも挿入します。

変更イベントレコードにないフィールドを指定すると、SMT はレコードの値にフィールドを追加します。

add.headers

 

単純化された Kafka レコードのヘッダーに追加するメタデータフィールドのカンマ区切りリストに、このオプションを設定します。フィールド名が重複している場合は、これらのフィールドのいずれかのメタデータを追加するには、構造とフィールドを指定します（例：） source.ts_ms。

SMT が単純化されたレコードのヘッダーにメタデータフィールドを追加すると、各メタデータフィールド名の前に二重アンダースコアが付けられます。構造仕様では、SMT は、構造名とフィールド名との間にアンダースコアも挿入します。

変更イベントレコードにないフィールドを指定すると、SMT はフィールドをヘッダーに追加しません。

8.3. Avro シリアル化

重要

Avro を使用したレコードキーおよび値のシリアライズ機能はテクノロジープレビュー機能です。テクノロジープレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat はテクノロジープレビュー機能を実稼働環境に実装することは推奨しません。テクノロジープレビューの機能は、最新の技術をいち早く提供して、開発段階で機能のテストやフィードバックの収集を可能にするために提供されます。サポート範囲の詳細は、「テクノロジプレビュー機能のサポート範囲」を参照してください。

Debezium コネクターは Kafka Connect フレームワークで機能し、変更イベントレコードを生成してデータベースの各行レベルの変更をキャプチャーします。変更イベントレコードごとに、Debezium コネクターは以下を行います。

  1. 設定した変換を適用します。
  2. 設定された Kafka Connect コンバーターを使用して、レコードキーおよび値をバイナリー形式でシリアライズします。
  3. 正しい Kafka トピックにレコードを書き込みます。

各 Debezium コネクターインスタンスにコンバーターを指定できます。Kafka Connect では、レコードキーと値を JSON ドキュメントにシリアライズする JSON コンバーターが提供されます。デフォルトの動作では、JSON コンバーターにレコードのメッセージスキーマが含まれ、各レコードが非常に詳細になります。『 Getting Started with Debezium』には、ペイロードとスキーマの両方が含まれる場合にレコードが表示されます。JSON でレコードをシリアライズする必要がある場合、以下のコネクター設定プロパティーをに設定することを検討してください false。

  • key.converter.schemas.enable
  • value.converter.schemas.enable

これらのプロパティーを設定して、各レコードから詳細なスキーマ情報を false 除外します。

Apache Avro を使用すると、レコードキーと値をシリアライズできます。Avro バイナリー形式は、コンパクトで効率的です。Avro スキーマにより、各レコードに正しい構造があることを確認することができます。Avro のスキーマ進化メカニズムにより、スキーマを進化できます。これは、変更したデータベーステーブル構造に一致するように各レコードのスキーマを動的に生成する Debezium コネクターに不可欠です。時間の経過とともに、同じ Kafka トピックに書き込まれたイベントレコードを変更する場合は、同じスキーマのバージョンが異なる可能性があります。Avro のシリアライズにより、イベントレコードコンシューマーの変更がレコードスキーマに適応することが容易になります。

Apache Avro のシリアライズを使用するには、Avro メッセージスキーマとそのバージョンを管理するスキーマレジストリーをデプロイする必要があります。このレジストリーの設定に関する詳細は、Red Hat Integration - Service Registry のドキュメントを参照してください。

8.3.1. Red Hat Integration - Service Registry について

Red Hat Integration: Service Registry は、Avro と連携するコンポーネントを複数提供します。

  • Debezium コネクター設定で指定できる Avro コンバーター。このコンバーターは、Kafka Connect スキーマを Avro スキーマにマッピングします。次にコンバーターは Avro スキーマを使用してレコードキーと値を Avro のコンパクトなバイナリー形式にシリアライズします。

  • 以下を追跡する API およびスキーマレジストリー

    • Kafka トピックで使用される Avro スキーマ
    • Avro コンバーターが生成された Avro スキーマを送信する場所

    Avro スキーマはこのレジストリーに保存されているため、各レコードには小さな スキーマ ID のみが含まれている必要があります。これにより、各レコードはさらに小さくなります。Kafka のような I/O バインドされたシステムでは、プロデューサーとコンシューマーの合計スループットがより高くなります。

  • Kafka プロデューサーおよびコンシューマーの Avro Serdes （ セシリアライザーおよびデシリアライザー）。変更イベントレコードを使用するために作成する Kafka コンシューマーアプリケーションは、Avro Serdes を使用して変更イベントレコードをデシリアライズできます。

Debezium で Service Registry を使用するには、Service Registry コンバーターとその依存関係を、Debezium コネクターの実行に使用する Kafka Connect コンテナーイメージに追加します。

注記

Service Registry プロジェクトは JSON コンバーターも提供します。このコンバーターは、あまり詳細なメッセージと人間が判読できる JSON の利点を組み合わせることができます。メッセージにはスキーマ情報自体は含まれませんが、スキーマ ID のみが含まれます。

8.3.2. デプロイメントの概要

Avro のシリアライズを使用する Debezium コネクターをデプロイする場合、主に以下の 3 つのタスクがあります。

  1. 「 Getting Started with Service Registry」の手順に従い、Red Hat Integration: Service Registry インスタンス をデプロイします。
  2. Debezium Service Registry Kafka Connect zip ファイルをダウンロードし、Debezium コネクターのディレクトリーに展開して、Avro コンバーターをインストールします。

  3. 以下のように設定プロパティーを設定して、Avro のシリアライズを使用するように Debezium コネクターインスタンスを設定します。 

    key.converter=io.apicurio.registry.utils.converter.AvroConverter
key.converter.apicurio.registry.url=http://apicurio:8080/api
key.converter.apicurio.registry.global-id=io.apicurio.registry.utils.serde.strategy.AutoRegisterIdStrategy
value.converter=io.apicurio.registry.utils.converter.AvroConverter
value.converter.apicurio.registry.url=http://apicurio:8080/api
value.converter.apicurio.registry.global-id=io.apicurio.registry.utils.serde.strategy.AutoRegisterIdStrategy

内部からは、Kafka Connect は常に JSON キー/値コンバーターを使用して設定およびオフセットを保存するために使用されます。

8.3.3. Debezium コンテナーの使用

お使いの環境では、提供される Debezium コンテナーを使用して、Avro serializaion を使用する Debezium コネクターをデプロイすることができます。ここの手順に従ってこれを行います。この手順では、Debezium のカスタム Kafka Connect コンテナーイメージをビルドし、Debezium コネクターが Avro コンバーターを使用するように設定します。

前提条件

  • OpenShift クラスターへのクラスター管理者アクセスがある。
  • Avro のシリアライズでデプロイする Debezium コネクタープラグインをダウンロードしている。

手順

  1. Service Registry のインスタンスをデプロイします。以下の手順は、『Getting Started with Service Registry』の「 Installing Service Registry from the OpenShift OperatorHub 」を参照してください。

    • AMQ Streams のインストール
    • AMQ Streams ストレージの設定
    • Service Registry のインストール

  2. Debezium コネクターアーカイブを展開し、コネクタープラグインのディレクトリー構造を作成します。各 Debezium コネクターのアーカイブをダウンロードして抽出した場合、構造は以下のようになります。 

    tree ./my-plugins/
./my-plugins/
├── debezium-connector-mongodb
|   ├── ...
├── debezium-connector-mysql
│   ├── ...
├── debezium-connector-postgres
│   ├── ...
└── debezium-connector-sqlserver
    ├── ...

  3. Avro コンバーターを、Avro のシリアライズを使用するように設定する Debezium コネクターが含まれるディレクトリーに追加します。

    1. Red Hat Integration のダウンロードサイト に移動し、Service Registry Kafka Connect zip ファイルをダウンロードします。
    2. アーカイブを希望の Debezium コネクターディレクトリーに展開します。

    Avro のシリアライズを使用するように複数のタイプの Debezium コネクターを設定するには、関連するコネクタータイプのディレクトリーでアーカイブを展開します。これによりファイルが複製されますが、競合する依存関係の可能性がなくなります。

  4. Avro コンバーターを使用するように設定された Debezium コネクターを実行するためにカスタムイメージを作成し、パブリッシュします。

    1. をベースイメージ registry.redhat.io/amq7/amq-streams-kafka-25:1.5.0 として使用 Dockerfile して、新規のを作成します。以下の例では、my-plugins をプラグインディレクトリーの名前に置き換えます。 

      FROM registry.redhat.io/amq7/amq-streams-kafka-25:1.5.0
USER root:root
COPY ./my-plugins/ /opt/kafka/plugins/
USER 1001

      Kafka Connect がコネクターの実行を開始する前に、Kafka Connect は /opt/kafka/plugins ディレクトリーにあるサードパーティープラグインをロードします。

    2. Docker コンテナーイメージをビルドします。たとえば、で作成した docker ファイルをとして保存した場合 debezium-container-with-avro、以下のコマンドを実行します。

      docker build -t debezium-container-with-avro:latest

    3. カスタムイメージをコンテナーレジストリーにプッシュします。以下に例を示します。

      docker push debezium-container-with-avro:latest

    4. 新しいコンテナーイメージを示します。次のいずれかを行います。

      • KafkaConnect カスタムリソースの KafkaConnect.spec.image プロパティーを編集します。設定された場合、このプロパティーによって Cluster Operator の STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 変数がオーバーライドされます。以下に例を示します。 

        apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaConnect
metadata:
  name: my-connect-cluster
spec:
  #...
  image: debezium-container-with-avro
      • install/cluster-operator/050-Deployment-strimzi-cluster-operator.yaml ファイルで、STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE 変数を編集して新しいコンテナーイメージを参照し、Cluster Operator を再インストールします。このファイルを編集する場合は、これを OpenShift クラスターに適用する必要があります。

  5. Avro コンバーターを使用するように設定された各 Debezium コネクターをデプロイします。Debezium コネクターごとに以下を行います。

    1. Debezium コネクターインスタンスを作成します。以下の inventory-connector.yaml ファイル例では、Avro コンバーターを使用するように設定された MySQL コネクターインスタンスを定義する KafkaConnector カスタムリソースを作成します。 

      apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaConnector
metadata:
  name: inventory-connector
  labels:
    strimzi.io/cluster: my-connect-cluster
spec:
  class: io.debezium.connector.mysql.MySqlConnector
  tasksMax: 1
  config:
    database.hostname: mysql
    database.port: 3306
    database.user: debezium
    database.password: dbz
    database.server.id: 184054
    database.server.name: dbserver1
    database.whitelist: inventory
    database.history.kafka.bootstrap.servers: my-cluster-kafka-bootstrap:9092
    database.history.kafka.topic: schema-changes.inventory
    key.converter: io.apicurio.registry.utils.converter.AvroConverter
    key.converter.apicurio.registry.url: http://apicurio:8080/api
    key.converter.apicurio.registry.global-id: io.apicurio.registry.utils.serde.strategy.AutoRegisterIdStrategy
    value.converter: io.apicurio.registry.utils.converter.AvroConverter
    value.converter.apicurio.registry.url: http://apicurio:8080/api
    value.converter.apicurio.registry.global-id: io.apicurio.registry.utils.serde.strategy.AutoRegisterIdStrategy

    2. コネクターインスタンスを適用します。例を以下に示します。

      oc apply -f inventory-connector.yaml

      このレジスターは inventory データベースに対して実行 inventory-connector されるようにします。

  6. コネクターが作成され、指定されたデータベースの変更を追跡していることを確認します。たとえば、を inventory-connector 起動した場合のように Kafka Connect ログ出力を監視して、コネクターインスタンスを確認できます。

    1. Kafka Connect ログ出力を表示します。 

      oc logs $(oc get pods -o name -l strimzi.io/name=my-connect-cluster-connect)

    2. ログ出力を確認し、初期スナップショットが実行されていることを確認します。以下の行のように表示されるはずです。 

      ...
2020-02-21 17:57:30,801 INFO Starting snapshot for jdbc:mysql://mysql:3306/?useInformationSchema=true&nullCatalogMeansCurrent=false&useSSL=false&useUnicode=true&characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=CONVERT_TO_NULL&connectTimeout=30000 with user 'debezium' with locking mode 'minimal' (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
2020-02-21 17:57:30,805 INFO Snapshot is using user 'debezium' with these MySQL grants: (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
...

      スナップショットには、複数のステップが必要です。 

      ...
2020-02-21 17:57:30,822 INFO Step 0: disabling autocommit, enabling repeatable read transactions, and setting lock wait timeout to 10 (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
2020-02-21 17:57:30,836 INFO Step 1: flush and obtain global read lock to prevent writes to database (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
2020-02-21 17:57:30,839 INFO Step 2: start transaction with consistent snapshot (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
2020-02-21 17:57:30,840 INFO Step 3: read binlog position of MySQL master (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
2020-02-21 17:57:30,843 INFO 	 using binlog 'mysql-bin.000003' at position '154' and gtid '' (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
...
2020-02-21 17:57:34,423 INFO Step 9: committing transaction (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
2020-02-21 17:57:34,424 INFO Completed snapshot in 00:00:03.632 (io.debezium.connector.mysql.SnapshotReader) [debezium-mysqlconnector-dbserver1-snapshot]
...

      スナップショットが完了すると、Debezium は変更イベントに関する inventory データベースの変更などの変更の追跡 binlog を開始します。 

      ...
2020-02-21 17:57:35,584 INFO Transitioning from the snapshot reader to the binlog reader (io.debezium.connector.mysql.ChainedReader) [task-thread-inventory-connector-0]
2020-02-21 17:57:35,613 INFO Creating thread debezium-mysqlconnector-dbserver1-binlog-client (io.debezium.util.Threads) [task-thread-inventory-connector-0]
2020-02-21 17:57:35,630 INFO Creating thread debezium-mysqlconnector-dbserver1-binlog-client (io.debezium.util.Threads) [blc-mysql:3306]
Feb 21, 2020 5:57:35 PM com.github.shyiko.mysql.binlog.BinaryLogClient connect
INFO: Connected to mysql:3306 at mysql-bin.000003/154 (sid:184054, cid:5)
2020-02-21 17:57:35,775 INFO Connected to MySQL binlog at mysql:3306, starting at binlog file 'mysql-bin.000003', pos=154, skipping 0 events plus 0 rows (io.debezium.connector.mysql.BinlogReader) [blc-mysql:3306]
...

8.3.4. naming

Avro の ドキュメント に記載されているように、名前は以下のルールに従う必要があります。

  • で始まるバージョン [A-Za-z_]
  • その後、[A-Za-z0-9_] 文字のみが含まれます。

Debezium は、対応する Avro フィールドのベースとして列名を使用します。この場合、列名が Avro 命名ルールに準拠していない場合に、シリアル化中に問題が発生する可能性があります。各 Debezium コネクターは設定プロパティーを提供し、名前の Avro ルールに準拠しない列がある true 場合はに設定 sanitize.field.names できます。sanitize.field.names をに設定 true すると、スキーマを実際に変更せずに、非整合性フィールドのシリアライズが可能になります。

8.4. CloudEvent のエクスポート

CloudEvents は、イベントデータを一般的な方法で記述するための仕様です。その目的は、サービス、プラットフォーム、およびシステム間で相互運用性を提供することです。Debezium を使用すると、MongoDB、MySQL、PostgreSQL、または SQL Server コネクターを設定し、CloudEvents 仕様に準拠する変更イベントレコードを出力できます。

重要

CloudEvents 形式で変更イベントレコードを出力することはテクノロジープレビュー機能です。テクノロジープレビューの機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat はテクノロジープレビュー機能を実稼働環境に実装することは推奨しません。テクノロジープレビューの機能は、最新の技術をいち早く提供して、開発段階で機能のテストやフィードバックの収集を可能にするために提供されます。サポート範囲の詳細は、「テクノロジプレビュー機能のサポート範囲」を参照してください。

CloudEvents 仕様は以下を定義します。

  • 標準イベント属性のセット
  • カスタム属性を定義するルール
  • イベント形式のシリアライズされた表現（JSON など）へのマッピングルール
  • Apache Kafka、HTTP、AMQP などのトランスポート層のプロトコルバインディング。

Debezium コネクターが CloudEvents 仕様に準拠する変更イベントレコードを出力するように設定するには、Debezium は Kafka Connect メッセージコンバーターで io.debezium.converters.CloudEventsConverterあるを提供します。

現在、構造化マッピングモードのみがサポートされます。CloudEvents の変更イベントフレームは JSON にする必要があります。data 形式は JSON である必要があります。今後の Debezium リリースはバイナリーマッピングモードをサポートする予定です。

8.4.1. イベント形式の例

以下の例は、PostgreSQL コネクターによって出力される CloudEvents 変更イベントレコードを示しています。この例では、PostgreSQL コネクターは、JSON を CloudEvents 形式および形式として使用するように設定されてい data ます。 

{
  "id" : "name:test_server;lsn:29274832;txId:565",   1
  "source" : "/debezium/postgresql/test_server",     2
  "specversion" : "1.0",                             3
  "type" : "io.debezium.postgresql.datachangeevent", 4
  "time" : "2020-01-13T13:55:39.738Z",               5
  "datacontenttype" : "application/json",            6
  "iodebeziumop" : "r",                              7
  "iodebeziumversion" : "1.1.2.Final",        8
  "iodebeziumconnector" : "postgresql",
  "iodebeziumname" : "test_server",
  "iodebeziumtsms" : "1578923739738",
  "iodebeziumsnapshot" : "true",
  "iodebeziumdb" : "postgres",
  "iodebeziumschema" : "s1",
  "iodebeziumtable" : "a",
  "iodebeziumtxId" : "565",
  "iodebeziumlsn" : "29274832",
  "iodebeziumxmin" : null,
  "iodebeziumtxid": "565",                           9
  "iodebeziumtxtotalorder": "1",
  "iodebeziumtxdatacollectionorder": "1",
  "data" : {                                         10
    "before" : null,
    "after" : {
      "pk" : 1,
      "name" : "Bob"
    }
  }
}
1
変更イベントの内容に基づいて変更イベント用にコネクターが生成する一意の ID。
2
イベントのソース。これは、コネクターの設定の database.server.name プロパティーによって指定されるデータベースの論理名です。
3
CloudEvents 仕様のバージョン。
4
変更イベントを生成したコネクタータイプ。このフィールドの形式はです io.debezium.CONNECTOR_TYPE.datachangeevent。の値 CONNECTOR_TYPE は mongodb、、mysql postgresql、またはです sqlserver。
5
ソースデータベースの変更時間。
6
は、JSON である data 属性のコンテンツタイプを記述します。
7
操作識別子。設定可能な値は、r read、c create、u update、または d delete です。
8
Debezium 変更イベントから認識される source 属性はすべて、属性名の iodebezium 接頭辞を使用して CloudEvents 拡張属性にマッピングされます。
9
コネクターで有効にすると、Debezium 変更イベントから認識される各 transaction 属性は、属性名の iodebeziumtx 接頭辞を使用して CloudEvents 拡張属性にマッピングされます。
10
実際のデータ自体は変更されています。操作やコネクターによっては、データに、、before after または patch フィールドが含まれることがあります。

8.4.2. 設定例

Debezium コネクター設定 io.debezium.converters.CloudEventsConverter でを設定します。の設定例を以下に示し CloudEventsConverterます。この例では、がデフォルトで json ある serializer.type ため、の指定を省略することができます。 

...
"value.converter": "io.debezium.converters.CloudEventsConverter",
"value.converter.serializer.type" : "json",
...

CloudEventsConverter Kafka レコード値を変換します。同じコネクター設定で、、、StringConverter LongConverterまたはなど、レコードキーで操作する key.converter かどうかを指定でき JsonConverterます。

8.4.3. 設定プロパティー

Debezium コネクターが CloudEvent コンバーターを使用するように設定する場合は、以下のプロパティーを指定できます。

プロパティー

デフォルト

説明

serializer.type

json

CloudEvents の構造に使用するエンコーディングタイプ json。は唯一サポートされている値です。

data.serializer.type

json

data 属性に使用するエンコーディングタイプ json。は唯一サポートされている値です。

json. ...

該当なし

JSON の使用時に基礎となるコンバーターに渡される設定プロパティー。json. 接頭辞が削除されます。

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.