Merge pull request #44 from project-tsurugi/docs-tgdump-sql

docs: spec plan of `tgdump` with any SQL statements.

README.md

@@ -3,7 +3,7 @@
 ## Available Tools
 
 * [tgsql](./modules/tgsql) - Text based SQL client program.
-* [tgdump](./modules/tgdump) - Table Dump Tool.
+* [tgdump](./modules/tgdump) - Dump Tool.
 
 ## Requirements
 

docs/tgdump-design_ja.md

@@ -34,17 +34,29 @@
 
 ```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-text>` (`--sql` が指定された場合)
+    * ダンプ処理の内容を表す SQL 文字列
   * `--to`
     * 出力先のディレクトリ
     * 出力先は存在しないか、または空のディレクトリでなければならない
   * `-c,--connection`
     * 接続先の Tsurugi の endpoint URI (現状は `ipc:` のみ対応)
 * optional parameters
+  * `--sql`
+    * テーブル名を指定する代わりに、ダンプ処理の内容を表す SQL 文を直接指定する
+  * `<query-label>` (`--sql` が指定された場合)
+    * 直後の `<query-text>` を識別するためのクエリラベル
+    * クエリラベルに以下のいずれの文字も含めることはできない
+      * 空白文字 (タブや改行を含む)
+      * クウォート文字 (`'`, `"`)
+      * コロン (`:`)
+    * 未指定の場合は、 "`<sql><引数の位置>`" という名前のラベルを自動的に付与する (引数の位置は 1 から始まる整数)
   * `--profile`
     * [ダンププロファイル](#ダンププロファイル)名
     * 未指定の場合は `default` という名前のプロファイルを使用する
@@ -81,14 +93,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 +114,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 +126,8 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
     * TBD: 将来的に対応を検討。その場合は `--to` で指定したディレクトリ配下に生成
 * standard output
   * 以下のタイミングで出力を行う
-    * 各テーブルのダンプの開始前 (テーブル名と出力先ディレクトリ)
-    * 各テーブルのダンプの終了後 (テーブル名と出力先ディレクトリ)
+    * 各テーブルのダンプの開始前 (テーブル名やクエリラベルと出力先ディレクトリ)
+    * 各テーブルのダンプの終了後 (テーブル名やクエリラベルと出力先ディレクトリ)
   * `--verbose` ではさらに以下の出力を行う (一例)
     * ダンプ処理本体の開始前
     * 各テーブル情報収集の開始前
@@ -153,9 +165,11 @@ tgdump <table-name> [<table-name> [...]] --to </path/to/destination-dir> --conne
     ------|------|------
     `kind` | `data` |
     `format` | `dump-info` | ダンプ対象のテーブルをデータベース上に検出したことを表す
-    `table` | 対象のテーブル名 |
+    `type` | ダンプの種類 | `--sql` の指定がない場合は `table`, ある場合は `query`
+    `table` | テーブル名 | `--sql` が未指定の場合はクエリラベル
+    `query` | クエリ文字列 | `--sql` が未指定の場合は absent
     `destination` | 出力先ファイルパス |
-    `columns` | ダンプ対象列の一覧 | 形式は後述
+    `columns` | ダンプ対象列の一覧 | 形式は後述 | `--sql` が指定された場合は absent
 
     `columns` はオブジェクトの配列型で、テーブルに含まれる列ごとに次のプロパティを含むオブジェクトを出力する。
 
@@ -195,25 +209,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 +248,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エラーが発生した

modules/tgdump/README.md

@@ -1,6 +1,6 @@
-# `tgdump` - Tsurugi Table Dump Tool
+# `tgdump` - Tsurugi Dump Tool
 
-Tsurugi Table Dump Tool extracts the contents of table data and saves them on files.
+Tsurugi Dump Tool extracts the contents of table data or query result and saves them on files.
 
 ## Build and Install
 
@@ -32,16 +32,24 @@ 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-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
+* `<query-label>`
+  * the label for the accompanying SQL text (`<query-text>`)
+  * default: auto-generated label
 * `--profile`
   * dump profile name / file path
   * available profile name:
@@ -65,7 +73,7 @@ optional parameters:
   * default: no transaction labels
 * `--threads`
   * the number of client threads in dump operations
-    * The number of simultaneous processing tables is limited to the number of this threads.
+    * The number of simultaneous processing tables/queries is limited to the number of this threads.
   * default: `1`
 * `-v,--verbose`
   * print verbose messages during executions.