https://aoe-tk.hatenablog.com/entry/2024/12/19/002946

このエントリは Tsurugi Advent Calendar 2024 の19日目のエントリです。前日は「【劔"Tsurugi" Tips集】distinctの代わりにgroup byの使用を検討する（1.1.0ワークアラウンド）【プログラミングTips】」でした。

データベースを運用、活用する上でデータのダンプ、ロード機能は必須です。運用時のデータバックアップ、リストアもそうですが、データベースに登録しているデータの一部分を抜き出してPandasやExcelなどを使ってデータの分析を行いたいこともあるでしょう。このエントリではTsurugiに用意されているデータのダンプ、ロード機能について紹介します。

Tsurugiが用意しているダンプ・ロード機能

現時点でTsurugiが用意しているデータのダンプ、ロード機能には次のようなものがあります。

Belayer
tgdumpコマンド
Tsubakuroのダンプ、ロードAPI
tgsqlのSQL実行モード
- これは厳密にはダンプ機能ではないのですが、簡易的なダンプ機能として使えるところがあるので紹介します

Belayer

Tsurugiの各種管理機能をWeb APIとして提供する Belayer にはダンプ取得API 及びデータロードAPI が存在します。現時点でTsurugi側として最も推奨するダンプ、ロード手段がこちらになります。

ファイル形式としてはParquetとCSVの2種類があります。Tsurugiが用意しているダンプ、ロード機能のうち、CSVファイルも扱えるのは現時点でこの方法のみです。

これらAPIはTsurugi、Belayerが稼働しているサーバーのローカルディレクトリ (厳密にはBelayerの設定環境変数である $BELAYER_STORAGE_ROOT 下のディレクトリ) を対象にファイルの読み書きを行うことに注意する必要があります。そのため実際に利用するときはファイルアップロードAPI 及びファイルダウンロードAPI と併用することになります。

tgdumpコマンド

Tsurugiにはコマンドラインによるテーブルダンプツール tgdump がインストールされています。

コマンドの名前が示すようにサポートしているのはダンプのみで、データロードには対応していません。ファイルの出力形式はParquetです。また次のような注意点があります。

Tsurugiがインストールされているサーバー上でのみ実行可能
ファイルを出力するディレクトリにはTsurugiの実行ユーザーがアクセス可能であること

Tsubakuroのダンプ、ロードAPI

TsurugiのJava言語向け低レベルAPIである Tsubakuro にはデータのダンプ、ロードを行うためのAPIが用意されています。前述のツールも内部ではこのTsubakuroのAPIを利用して機能を提供しています。

詳しい使い方は昨年のTsurugi Advent Calendar の次のエントリにて解説されています。

zenn.dev

この方法ではParquetに加えてArrow IPC形式のファイルが扱えます。また、テーブル単位ではなく任意のSQLの出力結果をダンプすることができます。

またこの方法でもtgdumpと同様の制約があります (下に再掲) 。ダンプ、ロード処理をTsurugi本体が実行するためです。

Tsurugiがインストールされているサーバー上でのみ実行可能
ファイルを出力するディレクトリにはTsurugiの実行ユーザーがアクセス可能であること

tgsqlのSQL実行モード

Tsurugi SQLコンソールである tgsql には引数にSQL文を渡して即時実行するSQL実行モードがあります。SQL実行モードでSQLの実行を行った場合、SQLの出力結果はJSONとして標準出力に出力されるため、これを利用して簡易ダンプツールとして使うことができます。Pandasなどで読み込んで扱えます。

tgsqlをSQL実行モードで実行するには次のようにオプション引数 --exec をセットし、実行するSQL文を渡します。標準出力をファイルにリダイレクトしておきましょう。

$ tgsql -c ipc:tsurugi --exec "select * from customer" > customer.json

リダイレクト先のファイルには次のようにSQLの実行結果がJSONで出力されています。

$ cat customer.json
// {"columns":[{"name":"c_id","label":"c_id","type":"INT8","dimension":0},{"name":"c_name","label":"c_name","type":"CHARACTER","dimension":0},{"name":"c_age","label":"c_age","type":"INT4","dimension":0}]}
{"c_id":1,"c_name":"Hello","c_age":10}
{"c_id":2,"c_name":"World","c_age":20}

各実行方法のPros & Cons

これまでに挙げた実行方法の長所と短所は次のようになります。

Belayer
- Pros
  - 公式が推奨する方式
  - リモートやTsurugi実行ユーザーとは別のユーザーで利用可能
  - Parquetに加えてCSVが利用可能
- Cons
  - Tsurugiと同じホストにBelayerのインストールが必要であるため、公式提供のDockerイメージから起動した環境では使えない
  - curlコマンド等のWebアプリケーションクライアントを用意する必要がある
tgdumpコマンド
- Pros
  - コマンドラインから手軽に実行可能
- Cons
  - Tsurugiがインストールされているサーバー上でのみ実行可能
  - ファイルを出力するディレクトリにはTsurugiの実行ユーザーがアクセス可能である必要がある
  - ロードはできない
Tsubakuroのダンプ、ロードAPI
- Pros
  - テーブル単位だけでなく任意のSQLの出力結果をダンプすることが可能
  - Parquetに加えてArrow IPC形式のファイルが扱える
- Cons
  - tgdumpと同様、Tsurugiがインストールされているサーバー上でのみ実行可能
  - さらに同様にファイルを出力するディレクトリにはTsurugiの実行ユーザーがアクセス可能である必要がある
tgsqlのSQL実行モード
- Pros
  - JSON形式でダンプができる
  - リモートからも実行可能
- Cons
  - ロードはできない

以上になります。

ですが、他のRDBMSではSQL文によるダンプを行えるものがありますよね。次のエントリではIceaxeを使ってSQL文によるダンプを行う簡易プログラムを書いてみたいと思います。