Embulk Tsurugiへの出力

EmbulkのTsurugi書き込みプラグインのメモ。

概要

RDBのTsurugiへデータを書き込むプラグインを作ってみた。
プラグイン名はembulk-output-tsurugidb。

このプラグインはEmbulk 0.10以降で、Java11以降に対応。（TsurugiのJava通信ライブラリーであるTsubakuroがJava11以降な為）

TsurugiはJDBCを提供していないので、embulk-output-postgresqlを元にしてTsubakuroを使うよう変更した。
基本的な使用方法はembulk-output-postgresqlと同じにしたつもりだが、対応していない機能もある。

このプラグインを使う為には、embulk-output-tsurugidbプラグインをインストールしておく必要がある。

インストール方法

Embulk 0.10以降ではgemを使わないインストール方法になった。以下のようにしてインストールする。
（最新バージョンはMavenセントラルリポジトリーで確認できる）

1. プラグイン本体と依存ライブラリーをMavenローカルリポジトリーにインストールする。

   Embulk 0.10〜0.11.2の場合
   $ export m2_repo=〜
   $ mvn dependency:get -Dartifact=io.github.hishidama.embulk:embulk-output-tsurugidb:1.3.0
   
   Embulk 0.11.3以降の場合 [2023-06-02]
   $ java -jar embulk-0.11.3.jar install io.github.hishidama.embulk:embulk-output-tsurugidb:1.3.0

2. config.ymlのtypeに「tsurugidb」で指定したい場合は、Embulkのプロパティーファイルに設定を追加する。[2024-07-11]
   →プロパティーファイルの記述方法

typeの指定方法

従来通りの方法

outのtypeにtsurugidbを指定する。

config.yml：

〜
out:
  type: tsurugidb
  endpoint: tcp://localhost:12345
〜

この場合は、Embulkのプロパティーファイル（Linuxの場合は$HOME/.embulk/embulk.properties、Windowsの場合は%USERPROFILE%\.embulk\embulk.properties）に設定を追加する必要がある。

embulk.properties：

plugins.output.tsurugidb=maven:io.github.hishidama.embulk:tsurugidb:0.1.7

Embulk 0.11.3以降

outのtypeに「source: maven」を指定する。[2024-07-11]

config.yml：

〜
out:
  type:
    source: maven
    group: io.github.hishidama.embulk
    name: tsurugidb
    version: 0.1.7
  endpoint: tcp://localhost:12345
〜

例

insertする例

SQLのinsert文を使ってテーブルにデータを書き込む例。

config.yml：

in:
  type: file
  path_prefix: 〜/input/intput.csv
  parser:
    type: csv
    columns:
    - {name: foo, type: long}   # int
    - {name: bar, type: long}   # bigint
    - {name: zzz, type: string} # varchar

out:
  type: tsurugidb
  endpoint: tcp://localhost:12345
  table: test

endpointにTsurugiのエンドポイントを指定する。

tableでテーブル名を指定する。
inのcolumnsでは、テーブルのカラム名と同じ名前を指定する。（大文字小文字は区別されない）

ver0.1.0ではmodeは「mode: direct_insert」（対象テーブルに直接書き込む）のみなので、modeは省略可。

putする例

KVSのput命令を使ってテーブルにデータを書き込む例。

Tsurugiの内部ではKVS（Key Value Store）でデータを保持している。
SQLでアクセスするより、KVSとして直接アクセスする方が速いことが期待される。

config.yml：

in:
  type: file
  path_prefix: 〜/input/intput.csv
  parser:
    type: csv
    columns:
    - {name: foo, type: long}   # int
    - {name: bar, type: long}   # bigint
    - {name: zzz, type: string} # varchar

out:
  type: tsurugidb
  endpoint: tcp://localhost:12345
  table: test
  tx_type: OCC
  method: put

methodにputを指定すると、KVSのput命令を使ってデータを書き込む。
ver0.1.0では、KVSは「tx_type: OCC」でしか動作しない。

データ精査

ver0.1.3では、文字列データにヌル文字（文字コード0）が含まれているかどうかをチェックするようになった。[2023-12-10]
デフォルトでは、ヌル文字が含まれていると、該当レコードのinsert/putをスキップする。
validate_nul_charをfalseにすると、ヌル文字精査を行わない。

（何故こういう精査を行うかと言うと、Tsurugi 1.0.0-BETA2では、ヌル文字が含まれる文字列をinsertしようとすると、INVALID_RUNTIME_VALUE_EXCEPTIONが発生する為。
ちなみに、Tsurugi 1.0.0-BETA1では、ヌル文字が含まれる文字列をinsertすると、select時にERR_DATA_CORRUPTIONが発生する）

デバッグログ出力する例

ver0.1.2では、methodがinsert, insert_wait, put, put_waitの場合、SQL実行時にエラーが発生すると該当データをログ出力する。[2023-12-07]
ただしログレベルはDEBUGなので、デフォルトでは出力されない。Embulk実行時にデバッグログ出力を指定する必要がある。

$ java -jar embulk-0.11.1.jar run -l debug config.yml

config.ymlの設定

config.ymlにTsurugi特有のトランザクションオプションやコミットオプションを指定できる。

その他の設定は、embulk-output-jdbcと同様（のはず）。

他に、データの精査有無やエラー発生時の挙動を指定できる。[2023-12-10]

method

config.ymlのmethodで書き込み方法を指定する。

methodの設定値の末尾にwaitが付いているものは、実装方法が単純。（insertやputで都度FutureResponseのawaitメソッドを呼ぶ方式）
実装は単純だったが、実行してみるととても遅かったorz
実用的ではないが、参考までに残してある。

method_option

config.ymlのmethod_optionで、methodのオプションを指定する。

例

out:
  type: tsurugidb
  〜
  method: put
  method_option: put_overwrite

変更履歴

Tsurugi（Tsubakuro）のバージョンアップに伴うものは省略。

• ver0.1.0 [2023-10-08]
  • 初回リリース
• ver0.1.1 [2023-10-09]
  • tx_priority, commit_typeのエラーメッセージ改善
  • method_optionにinsert_if_not_existsを追加
• ver0.1.2 [2023-12-07]
  • Tsubakuro 1.1.0（Tsubugi 1.0.0-BETA2）対応
  • SQL実行時にエラーが発生すると、デバッグレベルでログ出力する
• ver0.1.3 [2023-12-10]
  • char/varcharにヌル文字が入っていたらスキップする
• ver1.0.0 [2024-08-31]
  • session_keep_alive
  • session_shutdown_type・sssion_shutdown_timeout
• ver1.0.1 [2024-10-02]
  • methodにinsert_multi_valuesを追加
• ver1.0.2 [2024-10-02]
  • insert_multi_valuesのPreparedStatementをキャッシュするように修正 、およびSQLのログ出力を抑制