add docs about dblog maintenance util and dblog repair process

docs/dblog-repair_ja.md

@@ -0,0 +1,26 @@
+# 破損した永続化データの修復アルゴリズム
+
+* 2024-03-25 ban
+    * for 1.0.0-BETA4
+
+## durable でない pWAL エントリの存在 (pWAL ファイルをディスクに書き終えたが, 永続化マーカを書き終えていなかった)
+
+実装の現状
+* 1.0.0-BETA2 よりデータベースサービス起動時の recovery 処理中に自動修復をする対象である
+
+修復処理の概要
+* (判定) pWAL ファイル中の破損していない完全な epoch 断片のうち, epoch が 永続化マーカが示すものより大きかった場合
+* (処置) epoch 断片ヘッダエントリの entry_type を `marker_begin (0x02)` から `marker_invalidated_begin (0x06)` に書き換える
+
+## pWAL ファイルの末尾が破損している (ファイルが途中で終わっている, あるいは末尾に NUL 文字が埋まっている)
+
+実装の現状
+* 1.0.0-BETA4 より tglogutil ツールで自動修復をする対象である
+
+修復処理の概要
+* (判定) pWAL ファイルの epoch 断片走査中に, 予期しない (ブロックの途中での) EOF に遭遇した場合
+* (判定) pWAL ファイルの epoch 断片走査中に, entry_type 0 のブロックに遭遇した場合
+* (処置) epoch 断片ヘッダエントリの entry_type を `marker_begin (0x02)` から `marker_invalidated_begin (0x06)` に書き換える
+* (処置) このファイルの末尾に追記されないように, 未ローテートのファイルであった場合には必ずローテートをする (ローテートされているかはファイル名から判断する).
+* (補足) 起動時の recovery 処理中には `marker_invalidated_begin (0x06)` の epoch 断片走査中に EOF もしくは entry_type 0 に遭遇した場合には, エラーにせずそれ以降のファイル内容を読み捨てる.
+    * `marker_invalidated_begin (0x06)` に遭遇したら即座に読み捨てるわけではないことに注意. epoch 断片として揃っていた場合には, その epoch 断片を読み飛ばすがその後続データは通常のデータとして処理される.

docs/tglogutil_ja.md

@@ -0,0 +1,65 @@
+# 永続化データディレクトリ管理ツール
+
+* 2024-03-25 ban
+    * for 1.0.0-BETA4
+
+## この文書について
+
+永続化データディレクトリ管理ツール tglogutil について説明する.
+
+## 基本的なデザイン・方針
+
+* tsurugi の永続化データディレクトリの管理的操作を行なうツールであり, 単体コマンドとして機能する.
+    * tsurugi の設定ファイルを読まず, その情報を利用しない.
+* 操作対処ディレクトリを, コマンドパラメータで指定する.
+    * tsurugi の構成定義ファイルにおいて `[datastore]` セクションの `log_location` パラメータが指す場所に相当する.
+
+## 対応する破損の種類
+
+* durable でない pWAL エントリの存在 (pWAL ファイルをディスクに書き終えたが, 永続化マーカを書き終えていなかった) (`nondurable`)
+    * 1.0.0-BETA2 よりデータベースサービス起動時に自動修復をする対象である
+    * 本ツールの自動修復の対象である
+* pWAL ファイルの末尾が破損している (pWAL ファイルのディスクへの書き込みが途中までで終わっている (`truncated`), 末尾に 0 が埋まっている (`damaged`))
+    * データベースサービス起動時に自動修復をする対象ではない (エラーを出して異常終了する)
+    * 本ツールの自動修復の対象である
+
+## 機能一覧 (サブコマンド)
+
+* repair: 永続化データディレクトリの内容を修復する.
+
+### サブコマンド repair (自動修復)
+
+```
+$ tglogutil repair [options] <dblogdir>
+```
+
+指定された永続化データディレクトリの内容を自動修復する.
+ディレクトリ内部の pWAL ファイルを修復のため書き換える. 
+デフォルトでは書き換えは情報を損なわない範囲 (エントリ中のフラグバイトを変更する, ファイル名を変更する, 等) で実施されるが,
+オプション指定により, もとのファイルの情報を損なう処理 (ファイルの切りつめ等) を実施する.
+
+修復にあたり変更された内容を表示する.
+
+動作オプション
+* `--thread-num=<number>`
+    * pWAL ファイル修復の並行処理スレッド数の指定. デフォルト値は 1.
+* `--epoch=<epoch>`
+    * 採用する epoch の上限を数値で指定する. 指定しない場合のデフォルト動作は永続化マーカが示す数値.
+* `--cut=<bool>`
+    * 破損タイプ `truncated`, `damaged` の修復時にファイル末尾切り捨てを実施するか. デフォルト動作は切り捨てない (`false`).
+
+リターンコード
+* 0: 処理が正常終了
+    * もともと正常であったためなにも変更されなかった, あるいは 自動修復が正常終了.
+* 1: 処理が異常終了
+    * 自動修復できない破損に遭遇した.
+* 64以上: 扱えないデータ形式であった.
+    * dblogdir が存在しない.
+    * dblogdir がアクセス不能.
+    * dblogdir ファイル形式異常.
+        * 永続化データディレクトリでないディレクトリを指定した
+        * 永続化データディレクトリの永続化データフォーマットバージョンがサポートしているバージョンでない
+        * epoch ファイルが存在しない
+
+使用上の注意
+* データの書き換えを伴うため, ディレクトリのバックアップを取っておくことが望ましい.