docs: spec plan of tgdump with any SQL statements.

project-tsurugi · Dec 26, 2024 · 9a6a219 · 9a6a219
1 parent 3a33b7b
commit 9a6a219
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 20 deletions.
diff --git a/docs/tgdump-design_ja.md b/docs/tgdump-design_ja.md
@@ -34,17 +34,25 @@
 
 ```sh
 tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --connection <endpoint-uri>
+tgdump --sql <query-label>:<query-text> [<query-label>:<query-text> [...]] --to </path/to/destination-dir> --connection <endpoint-uri>
 ```
 
 * mandatory parameters
-  * `<table-name>`
+  * `<table-name>` (`--sql` が指定されていない場合)
     * ダンプ対象のテーブル名 (複数指定可能)
+  * `<query-label>` (`--sql` が指定された場合)
+    * 直後の `<query-text>` を識別するためのクエリラベル
+    * クエリラベルに文字 `:` や空白文字を含めることはできず、1文字以上40文字以内である必要がある
+  * `<query-text>` (`--sql` が指定された場合)
+    * ダンプ処理の内容を表す SQL 文字列
   * `--to`
     * 出力先のディレクトリ
     * 出力先は存在しないか、または空のディレクトリでなければならない
   * `-c,--connection`
     * 接続先の Tsurugi の endpoint URI (現状は `ipc:` のみ対応)
 * optional parameters
+  * `--sql`
+    * テーブル名を指定する代わりに、ダンプ処理の内容を表す SQL 文を直接指定する
   * `--profile`
     * [ダンププロファイル](#ダンププロファイル)名
     * 未指定の場合は `default` という名前のプロファイルを使用する
@@ -81,14 +89,14 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
     * バージョン情報を表示して終了する
     * `--help` と同時に指定された場合、 `--help` を優先する
 * file output
-  * `--to` で指定したディレクトリ配下に `<table-name>` で指定した名前のディレクトリを作成し、作成した各ディレクトリ配下に当該テーブルの内容をダンプしたダンプファイル (群) を作成する
-    * `<table-name>` によってテーブルが複数個指定された場合、テーブルの数だけ `--to` で指定した配下にディレクトリ (テーブルディレクトリ) を作成する
-    * 各テーブルディレクトリには0個以上のファイルが生成される
-    * テーブル名がディレクトリ名として適さない場合、当該箇所を適切な文字に置き換える
+  * `--to` で指定したディレクトリ配下に `<table-name>` または `<query-label>` で指定した名前のディレクトリを作成し、作成した各ディレクトリ配下に当該テーブルの内容または SQL の処理結果をダンプしたダンプファイル (群) を作成する
+    * 指定されたテーブルやクエリの数だけ `--to` で指定した配下にディレクトリ (サブディレクトリ) を作成する
+    * 各サブディレクトリには0個以上のファイルが生成される
+    * テーブル名やクエリラベルがディレクトリ名として適さない場合、当該箇所を適切な文字に置き換える
     * 出力されるダンプ形式は `--profile` で指定したプロファイルに従う
     * `--profile` の種類によっては、 `</path/to/destination-dir>` 配下にその他のファイルを出力する場合もある
     * ダンプファイルは `tsurugidb` プロセスのユーザー権限で書きこまれる (現在の制限)
-  * テーブルディレクトリ名は以下のように計算する
+  * サブディレクトリ名は以下のように計算する
     * 文字集合定義
       * 置換文字: `_` (アンダースコア)
       * 区切り文字: `-` (ハイフン)
@@ -102,10 +110,10 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
         * `.<>:/\|?*"` のいずれか
           * 一部システムでファイル名として利用できないか、特殊な意味を持つもの
     * 操作
-      * テーブル名に含まれる置換対象文字を置換文字に置き換える
-      * テーブル名に含まれる大文字 (uppercase letter: Lu) を小文字 (lowercase letter: Ll) に置き換える
-      * テーブル名の先頭から50文字を残し、残りを除去する
-      * テーブル名が衝突した場合、末尾に区切り文字と任意の数値を加え、衝突を避ける
+      * テーブル名やクエリラベルに含まれる置換対象文字を置換文字に置き換える
+      * テーブル名やクエリラベルに含まれる大文字 (uppercase letter: Lu) を小文字 (lowercase letter: Ll) に置き換える
+      * テーブル名やクエリラベルの先頭から50文字を残し、残りを除去する (クエリラベルはより短い文字列のみ指定可能)
+      * テーブル名やクエリラベルが衝突した場合、末尾に区切り文字と任意の数値を加え、衝突を避ける
     * 備考
       * NFC/NFD については関与しない
         * テーブル名のほうをルール化する際に考える
@@ -114,8 +122,8 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
     * TBD: 将来的に対応を検討。その場合は `--to` で指定したディレクトリ配下に生成
 * standard output
   * 以下のタイミングで出力を行う
-    * 各テーブルのダンプの開始前 (テーブル名と出力先ディレクトリ)
-    * 各テーブルのダンプの終了後 (テーブル名と出力先ディレクトリ)
+    * 各テーブルのダンプの開始前 (テーブル名やクエリラベルと出力先ディレクトリ)
+    * 各テーブルのダンプの終了後 (テーブル名やクエリラベルと出力先ディレクトリ)
   * `--verbose` ではさらに以下の出力を行う (一例)
     * ダンプ処理本体の開始前
     * 各テーブル情報収集の開始前
@@ -153,9 +161,9 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
     ------|------|------
     `kind` | `data` |
     `format` | `dump-info` | ダンプ対象のテーブルをデータベース上に検出したことを表す
-    `table` | 対象のテーブル名 |
+    `table` | 対象のテーブル名 | `--sql` が指定された場合はクエリラベルを出力
     `destination` | 出力先ファイルパス |
-    `columns` | ダンプ対象列の一覧 | 形式は後述
+    `columns` | ダンプ対象列の一覧 | 形式は後述 | `--sql` が指定された場合は absent
 
     `columns` はオブジェクトの配列型で、テーブルに含まれる列ごとに次のプロパティを含むオブジェクトを出力する。
 
@@ -195,25 +203,25 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
     ------|------|------
     `kind` | `data` |
     `format` | `dump-start` | 対象のテーブルのダンプ処理を開始したことを表す
-    `table` | 対象のテーブル名 |
+    `table` | 対象のテーブル名 | `--sql` が指定された場合はクエリラベルを出力
     `destination` | 出力先ディレクトリパス |
 
-  * テーブルディレクトリにダンプファイルが追加された際、以下の `kind=data` のレコード (`format=dump-file`) を出力する
+  * サブディレクトリにダンプファイルが追加された際、以下の `kind=data` のレコード (`format=dump-file`) を出力する
 
     フィールド名 | 内容 | 備考
     ------|------|------
     `kind` | `data` |
     `format` | `dump-file` | ダンプファイルが作成されたことを表す
-    `table` | 対象のテーブル名 |
+    `table` | 対象のテーブル名 | `--sql` が指定された場合はクエリラベルを出力
     `destination` | 出力先ファイルパス |
 
-  * テーブルディレクトリに当該テーブルのすべてのダンプファイルが追加された終わった際、以下の `kind=data` のレコード (`format=dump-finish`) を出力する
+  * サブディレクトリに当該テーブルのすべてのダンプファイルが追加された終わった際、以下の `kind=data` のレコード (`format=dump-finish`) を出力する
 
     フィールド名 | 内容 | 備考
     ------|------|------
     `kind` | `data` |
     `format` | `dump-finish` | 対象のテーブルのダンプ処理が完了したことを示す
-    `table` | 対象のテーブル名 |
+    `table` | 対象のテーブル名 | `--sql` が指定された場合はクエリラベルを出力
     `destination` | 出力先ディレクトリパス |
 
 * exit status
@@ -234,7 +242,7 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
   `connection_failure` | 非 `0` | 対象のデータベースへの接続に失敗した
   `table_not_found` | 非 `0` | 対象のテーブルのいずれかが存在しない
   `begin_failure` | 非 `0` | トランザクションの開始に失敗した
-  `prepare_failure` | 非 `0` | ダンプ命令の解釈に失敗した
+  `prepare_failure` | 非 `0` | ダンプ命令の解釈に失敗した (`--sql` が指定された場合、SQL 文字列に誤りがある)
   `operation_failure` | 非 `0` | ダンプ処理中にエラーが発生した
   `commit_failure` | 非 `0` | ダンプ処理のコミットに失敗した (ダンプファイルは生成されたが、不正確である可能性がある)
   `io` | 非 `0` | ハンドルできないI/Oエラーが発生した

diff --git a/modules/tgdump/README.md b/modules/tgdump/README.md
@@ -32,16 +32,22 @@ Deploy the files mentioned above, and the tgdump command will be available for u
 
 ```sh
 tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --connection <endpoint-uri> ...
+tgdump --sql <query-label>:<query-text> [<query-label>:<query-string> [...]] --to </path/to/destination-dir> --connection <endpoint-uri> ...
 ```
 
 parameters:
 
 * `<table-name>` - the dump target table names
+* `<query-label>` - the label for the accompanying SQL text
+* `<query-text>` - the SQL text for dump operations
 * `--to` - the destination directory
 * `--connection` - the target Tsurugi endpoint URI (must be `ipc:` protocol)
 
 optional parameters:
 
+* `--sql`
+  * use SQL text for dump operations instead of table names
+  * default: use table names
 * `--profile`
   * dump profile name / file path
   * available profile name: