TiCDC Canal-JSON プロトコル

Canal-JSON は、 アリババ運河によって定義されたデータ交換形式のプロトコルです。このドキュメントでは、TiDB 拡張フィールド、Canal-JSON データ形式の定義、公式 Canal との比較など、Canal-JSON データ形式が TiCDC でどのように実装されているかを学ぶことができます。

Canal-JSON を使用する

Message Queue (MQ) をダウンストリーム シンクとして使用する場合、 sink-uriで Canal-JSON を指定できます。 TiCDC は、Event を基本単位として Canal-JSON メッセージをラップして構築し、TiDB データ変更イベントをダウンストリームに送信します。

イベントには 3 つのタイプがあります。

  • DDL イベント: DDL 変更レコードを表します。これは、上流の DDL ステートメントが正常に実行された後に送信されます。 DDL イベントは、インデックスが 0 の MQ パーティションに送信されます。
  • DML イベント: 行データ変更レコードを表します。このタイプのイベントは、行の変更が発生したときに送信されます。これには、変更が発生した後の行に関する情報が含まれます。
  • WATERMARK イベント: 特別な時点を表します。これは、この時点より前に受信したイベントが完了したことを示します。 TiDB 拡張フィールドにのみ適用され、 sink-urienable-tidb-extensiontrueを設定すると有効になります。

以下はCanal-JSONの使用例です。

cdc cli changefeed create --server=http://127.0.0.1:8300 --changefeed-id="kafka-canal-json" --sink-uri="kafka://127.0.0.1:9092/topic-name?kafka-version=2.4.0&protocol=canal-json"

TiDB 拡張フィールド

Canal-JSON プロトコルは、もともと MySQL 用に設計されました。これには、CommitTS トランザクションの TiDB 固有の一意識別子などの重要なフィールドは含まれません。この問題を解決するために、TiCDC は TiDB 拡張フィールドを Canal-JSON プロトコル形式に追加します。 sink-urienable-tidb-extensiontrue (デフォルトではfalse ) を設定すると、TiCDC は Canal-JSON メッセージを生成するときに次のように動作します。

  • TiCDC は、 _tidbという名前のフィールドを含む DML イベント メッセージと DDL イベント メッセージを送信します。
  • TiCDC は WATERMARK イベント メッセージを送信します。

以下は例です。

cdc cli changefeed create --server=http://127.0.0.1:8300 --changefeed-id="kafka-canal-json-enable-tidb-extension" --sink-uri="kafka://127.0.0.1:9092/topic-name?kafka-version=2.4.0&protocol=canal-json&enable-tidb-extension=true"

メッセージフォーマットの定義

このセクションでは、DDL イベント、DML イベント、WATERMARK イベントの形式と、コンシューマー側でデータがどのように解決されるかについて説明します。

DDLイベント

TiCDC は、DDL イベントを次の Canal-JSON 形式にエンコードします。

{ "id": 0, "database": "test", "table": "", "pkNames": null, "isDdl": true, "type": "QUERY", "es": 1639633094670, "ts": 1639633095489, "sql": "drop database if exists test", "sqlType": null, "mysqlType": null, "data": null, "old": null, "_tidb": { // TiDB extension field "commitTs": 163963309467037594 } }

フィールドについては次のように説明します。

分野タイプ説明
ID番号TiCDC のデフォルト値は 0 です。
データベース行が存在するデータベースの名前
テーブル行が配置されているテーブルの名前
PKNames配列主キーを構成するすべての列の名前
はDdlブールメッセージが DDL イベントであるかどうか
タイプCanal-JSON で定義されたイベント タイプ
エス番号メッセージを生成したイベントが発生したときの 13 ビット (ミリ秒) のタイムスタンプ
ts番号TiCDC がメッセージを生成したときの 13 ビット (ミリ秒) のタイムスタンプ
SQLisDdl がtrueの場合、対応する DDL ステートメントを記録します
SQLタイプ物体isDdl がfalseの場合、各列のデータ型がJavaでどのように表現されるかを記録します。
mysqlタイプ物体isDdl がfalseの場合、各列のデータ型が MySQL でどのように表現されるかを記録します。
データ物体isDdl がfalseの場合、各列の名前とそのデータ値を記録します。
古い物体メッセージが更新イベントによって生成された場合のみ、更新前の各列の名前とデータ値が記録されます。
_tidb物体TiDB 拡張フィールド。 enable-tidb-extensiontrueを設定した場合にのみ存在します。値commitTs 、行の変更を引き起こしたトランザクションの TSO です。

DMLイベント

TiCDC は、DML データ変更イベントの行を次のようにエンコードします。

{ "id": 0, "database": "test", "table": "tp_int", "pkNames": [ "id" ], "isDdl": false, "type": "INSERT", "es": 1639633141221, "ts": 1639633142960, "sql": "", "sqlType": { "c_bigint": -5, "c_int": 4, "c_mediumint": 4, "c_smallint": 5, "c_tinyint": -6, "id": 4 }, "mysqlType": { "c_bigint": "bigint", "c_int": "int", "c_mediumint": "mediumint", "c_smallint": "smallint", "c_tinyint": "tinyint", "id": "int" }, "data": [ { "c_bigint": "9223372036854775807", "c_int": "2147483647", "c_mediumint": "8388607", "c_smallint": "32767", "c_tinyint": "127", "id": "2" } ], "old": null, "_tidb": { // TiDB extension field "commitTs": 163963314122145239 } }

ウォーターマークイベント

TiCDC は、 enable-tidb-extensiontrueに設定した場合にのみ WATERMARK イベントを送信します。 typeフィールドの値はTIDB_WATERMARKです。イベントには_tidbフィールドが含まれており、このフィールドにはパラメータwatermarkTsが 1 つだけ含まれています。値watermarkTsは、イベントの送信時に記録される TSO です。

このタイプのイベントを受信すると、 watermarkTs未満のcommitTsを持つすべてのイベントが送信されています。 TiCDC は「At Least Once」セマンティクスを提供するため、データは繰り返し送信される可能性があります。 watermarkTs未満のcommitTsを含む後続のイベントを受信した場合は、このイベントを無視しても問題ありません。

以下は WATERMARK イベントの例です。

{ "id": 0, "database": "", "table": "", "pkNames": null, "isDdl": false, "type": "TIDB_WATERMARK", "es": 1640007049196, "ts": 1640007050284, "sql": "", "sqlType": null, "mysqlType": null, "data": null, "old": null, "_tidb": { // TiDB extension field "watermarkTs": 429918007904436226 } }

消費者側のデータ解決

上の例からわかるように、Canal-JSON には統一されたデータ形式があり、イベント タイプごとにフィールド入力ルールが異なります。統一された方法を使用してこの JSON 形式のデータを解決し、フィールド値を確認してイベント タイプを決定できます。

  • isDdltrueの場合、メッセージには DDL イベントが含まれます。
  • isDdlfalse場合、さらにtypeフィールドを確認する必要があります。 typeTIDB_WATERMARKの場合、それは WATERMARK イベントです。それ以外の場合は、DML イベントです。

フィールドの説明

Canal-JSON 形式では、 mysqlTypeフィールドとsqlTypeフィールドに対応するデータ型が記録されます。

「MySQL タイプ」フィールド

mysqlTypeフィールドには、Canal-JSON 形式で各列に MySQL Type の文字列が記録されます。詳細については、 TiDB データ型を参照してください。

「SQL タイプ」フィールド

sqlTypeフィールドには、Canal-JSON 形式で各列のJava SQL Type が記録されます。これは、JDBC のデータに対応するデータ型です。その値は、MySQL タイプと特定のデータ値によって計算できます。マッピングは次のとおりです。

MySQLのタイプJava SQL タイプ コード
ブール値-6
浮く7
ダブル8
10進数3
シャア1
バーチャー12
バイナリ2004年
ヴァルバイナリ2004年
タイニーテキスト2005年
文章2005年
ミディアムテキスト2005年
長文2005年
小さな塊2004年
ブロブ2004年
ミディアムブロブ2004年
ロングブロブ2004年
日付91
日付時刻93
タイムスタンプ93
時間92
12
列挙型4
セット-7
少し-7
JSON12

整数型

次の表に示すように、 整数型Unsigned制約があるかどうかと、さまざまなJava SQL タイプ コードにそれぞれ対応する値のサイズを考慮する必要があります。

MySQLの型文字列値の範囲Java SQL タイプ コード
タイニーント[-128、127]-6
tinyint 署名なし[0,127]-6
tinyint 署名なし[128、255]5
smallint[-32768、32767]5
smallint 署名なし[0, 32767]5
smallint 署名なし[32768、65535]4
中程度の[-8388608、8388607]4
署名されていない中程度の[0, 8388607]4
署名されていない中程度の[8388608、16777215]4
整数[-2147483648、2147483647]4
int 符号なし[0、2147483647]4
int 符号なし[2147483648、4294967295]-5
ビギント[-9223372036854775808、9223372036854775807]-5
bigint 署名なし[0, 9223372036854775807]-5
bigint 署名なし[9223372036854775808、18446744073709551615]3

次の表は、TiCDC のJava SQL タイプとそのコード間のマッピング関係を示しています。

Java SQL タイプJava SQL タイプ コード
チャー1
10進数3
整数4
スモールント5
本物7
ダブル8
VARCHAR12
日付91
時間92
タイムスタンプ93
BLOB2004年
クロブ2005年
BIGINT-5
タイイント-6
少し-7

Java SQL タイプの詳細については、 Java SQL クラスの型を参照してください。

バイナリ型とブロブ型

TiCDC は、次のように各バイトをその文字表現に変換することにより、 バイナリ型 Canal-JSON 形式でエンコードします。

  • 印刷可能な文字は、ISO/IEC 8859-1 文字エンコーディングを使用して表されます。
  • 印刷不可能な文字と、HTML で特別な意味を持つ特定の文字は、UTF-8 エスケープ シーケンスを使用して表現されます。

次の表に、詳細な表現情報を示します。

文字の種類値の範囲文字表現
制御文字[0、31]UTF-8 エスケープ ( \u0000\u001Fなど)
水平タブ[9]\t
改行[10]\n
キャリッジリターン[13]\r
印刷可能な文字[32、127]リテラル文字 ( Aなど)
アンパサンド[38]\u0026
小なり記号[60]\u0038
大なり記号[62]\u003E
拡張制御文字[128、159]リテラル文字
ISO 8859-1 (ラテン-1)[160、255]リテラル文字

エンコーディングの例

たとえば、 c_varbinaryという名前のVARBINARY列に格納されている次の 16 バイト[5 7 10 15 36 50 43 99 120 60 38 255 254 45 55 70] 、Canal-JSON Updateイベントで次のようにエンコードされます。

{ ... "data": [ { ... "c_varbinary": "\u0005\u0007\n\u000f$2+cx\u003c\u0026ÿþ-7F" } ] ... }

TiCDC Canal-JSON と公式 Canal の比較

TiCDC がUpdateイベントとmysqlTypeフィールドを含む Canal-JSON データ形式を実装する方法は、公式の Canal とは異なります。次の表に主な違いを示します。

アイテムTiCDC Canal-JSON運河
Update種類のイベントデフォルトでは、 oldフィールドにはすべての列データが含まれます。 only_output_updated_columnstrueの場合、 oldフィールドには変更された列データのみが含まれます。oldフィールドには、変更された列データのみが含まれます
mysqlTypeフィールドパラメータ付きの型の場合、型パラメータの情報は含まれません。パラメータ付きの型の場合、型パラメータの完全な情報が含まれます。

Updateタイプのイベント

Update種類のイベントの場合:

  • TiCDC では、 oldフィールドにすべての列データが含まれます
  • 公式 Canal では、 oldフィールドには変更された列データのみが含まれます

次の SQL ステートメントが上流の TiDB で順次実行されると仮定します。

create table tp_int ( id int auto_increment, c_tinyint tinyint null, c_smallint smallint null, c_mediumint mediumint null, c_int int null, c_bigint bigint null, constraint pk primary key (id) ); insert into tp_int(c_tinyint, c_smallint, c_mediumint, c_int, c_bigint) values (127, 32767, 8388607, 2147483647, 9223372036854775807); update tp_int set c_int = 0, c_tinyint = 0 where c_smallint = 32767;

updateステートメントの場合、TiCDC は、以下に示すように、 typeUPDATEとして持つイベント メッセージを出力します。 updateステートメントはc_intc_tinyint列のみを変更します。出力イベント メッセージのoldフィールドには、すべての列データが含まれます。

{ "id": 0, ... "type": "UPDATE", ... "sqlType": { ... }, "mysqlType": { ... }, "data": [ { "c_bigint": "9223372036854775807", "c_int": "0", "c_mediumint": "8388607", "c_smallint": "32767", "c_tinyint": "0", "id": "2" } ], "old": [ // In TiCDC, this field contains all the column data. { "c_bigint": "9223372036854775807", "c_int": "2147483647", // Modified column "c_mediumint": "8388607", "c_smallint": "32767", "c_tinyint": "127", // Modified column "id": "2" } ] }

公式 Canal の場合、以下に示すように、出力イベント メッセージのoldフィールドには、変更された列データのみが含まれます。

{ "id": 0, ... "type": "UPDATE", ... "sqlType": { ... }, "mysqlType": { ... }, "data": [ { "c_bigint": "9223372036854775807", "c_int": "0", "c_mediumint": "8388607", "c_smallint": "32767", "c_tinyint": "0", "id": "2" } ], "old": [ // In Canal, this field contains only the modified column data. { "c_int": "2147483647", // Modified column "c_tinyint": "127", // Modified column } ] }

mysqlTypeフィールド

mysqlTypeフィールドの場合、型にパラメータが含まれる場合、公式の Canal には型パラメータの完全な情報が含まれます。 TiCDC にはそのような情報は含まれていません。

次の例では、テーブル定義 SQL ステートメントに、 decimalcharvarcharenumなどの各列のパラメーターが含まれています。 TiCDC と公式 Canal によって生成された Canal-JSON 形式を比較すると、TiCDC のmysqlTypeフィールドには基本的な MySQL 情報のみが含まれていることがわかります。 type パラメータの完全な情報が必要な場合は、他の方法で実装する必要があります。

次の SQL ステートメントが上流の TiDB で順次実行されると仮定します。

create table t ( id int auto_increment, c_decimal decimal(10, 4) null, c_char char(16) null, c_varchar varchar(16) null, c_binary binary(16) null, c_varbinary varbinary(16) null, c_enum enum('a','b','c') null, c_set set('a','b','c') null, c_bit bit(64) null, constraint pk primary key (id) ); insert into t (c_decimal, c_char, c_varchar, c_binary, c_varbinary, c_enum, c_set, c_bit) values (123.456, "abc", "abc", "abc", "abc", 'a', 'a,b', b'1000001');

TiCDC の出力は次のとおりです。

{ "id": 0, ... "isDdl": false, "sqlType": { ... }, "mysqlType": { "c_binary": "binary", "c_bit": "bit", "c_char": "char", "c_decimal": "decimal", "c_enum": "enum", "c_set": "set", "c_varbinary": "varbinary", "c_varchar": "varchar", "id": "int" }, "data": [ { ... } ], "old": null, }

公式運河の出力は次のとおりです。

{ "id": 0, ... "isDdl": false, "sqlType": { ... }, "mysqlType": { "c_binary": "binary(16)", "c_bit": "bit(64)", "c_char": "char(16)", "c_decimal": "decimal(10, 4)", "c_enum": "enum('a','b','c')", "c_set": "set('a','b','c')", "c_varbinary": "varbinary(16)", "c_varchar": "varchar(16)", "id": "int" }, "data": [ { ... } ], "old": null, }

TiCDC Canal-JSON の変更点

DeleteイベントのOldフィールドの変更

v5.4.0より、 Deleteイベントのうちのoldフィールドが変更されました。

以下はDeleteイベント メッセージです。 v5.4.0 より前では、 oldフィールドには「データ」フィールドと同じ内容が含まれています。 v5.4.0 以降のバージョンでは、 oldフィールドは null に設定されます。 「データ」フィールドを使用して、削除されたデータを取得できます。

{ "id": 0, "database": "test", ... "type": "DELETE", ... "sqlType": { ... }, "mysqlType": { ... }, "data": [ { "c_bigint": "9223372036854775807", "c_int": "0", "c_mediumint": "8388607", "c_smallint": "32767", "c_tinyint": "0", "id": "2" } ], "old": null, // The following is an example before v5.4.0. The `old` field contains the same content as the "data" field. "old": [ { "c_bigint": "9223372036854775807", "c_int": "0", "c_mediumint": "8388607", "c_smallint": "32767", "c_tinyint": "0", "id": "2" } ] }

このページは役に立ちましたか?

Playground
新規
登録なしで TiDB の機能をワンストップでインタラクティブに体験できます。
製品
TiDB Cloud
TiDB
価格
PoC お問い合わせ
エコシステム
TiKV
TiFlash
OSS Insight
© 2024 PingCAP. All Rights Reserved.
Privacy Policy.