コマンドマニュアル
このページでは、TataruBookでサポートされているすべてのコマンドについて説明します。
TataruBookには２つのインストール方法があり、それに対応するコマンドラインの使用法が２つあります。これらは、Pythonスクリプト方式と実行ファイル方式です。説明を簡単にするために、このページは、実行ファイル方式を例にとって説明します。Pythonスクリプト方式を使用する場合は、すべてのコマンドの冒頭をtatarubookからpython tatarubook.pyに置き換える必要があります。たとえば、example.dbというデータベースファイルを作成するには、tatarubook init example.dbというコマンドをpython tatarubook.py init example.dbに変更する必要があります。
共通特性
以下では、複数のコマンドに関連する共通特性について説明します。
文字コード形式
初期設定では、TataruBookはOSの既定の文字コード形式を使用してファイルを読み書きします。しかし、英語以外のWindows OSでは、既定の文字コードが UTF-8 ではないため、Windowsで UTF-8形式のCSVファイルを読み込む際に、TataruBookがデコードエラーを起こすことがあります。この問題を解決するため、TataruBookは既定の文字コードでのデコードに失敗した場合、UTF-8で再度デコードを試みます。
TataruBookで他の文字コード形式を使用してファイルを読み書きする場合は、関連するコマンドで--encodingオプションを使用して文字コード形式を指定できます。サポートされている文字コード形式の一覧は、こちらで確認できます。
自動生成されたインデックスフィールド
accountsテーブルのaccount_indexやpostingsテーブルのposting_indexなど、挿入時に自動生成されるフィールドの値があります。これらのテーブルに含まれるレコードをinsertコマンドを使用してデータベースファイルに挿入する場合、これらのフィールドの値はNULLを設定してください。また、importコマンドを使用してレコードをインポートする場合、このフィールドに対応するセルは空欄にしてください。そうすることで、TataruBookは他のレコードとは異なる新しいインデックス値を自動的にこのフィールドに入力します。
日付の入力形式
日付を入力する際、TataruBookでは、日付には年、月、日、順という三つの要素を、この順に入力する必要があります。要素同士は/、-、.のいずれかの区切り文字で分けることができますが、区切り文字は一貫して使用する必要があります。年は4桁の数字で入力し、月と日は1桁または2桁の数字で、先頭にゼロがあってもなくてもかまいません。
区切り文字を使用しない場合、日付全体はyyyymmdd形式の8桁の数字である必要があります。
以下の形式はすべて有効です: 2023/5/3、2023-5-3、2023.5.3、2023-05-03、2023/5/03、20230503。
以下の形式はすべて無効です: 2023-5/3（区切り文字が一貫していない）、23-05-03（年が4桁の数字ではない）、2023053（区切り文字がないが、8桁ではない）。
名前によるインデックスの検索
あるテーブルのレコードが別のテーブルのレコードを参照する場合、データベース設計の原則に従って、参照するのはレコードのインデックス（index）です。ただし、インデックスを手動で入力するのは手間がかかり、間違いが発生しやすくなります。たとえば、accountsテーブルの内容が次のようになっているとします。
| account_index | account_name | asset_index | is_external |
|---|---|---|---|
| 1 | シャーレアン銀行普通預金 | 1 | 0 |
| 2 | 飲食費用 | 1 | 1 |
シャーレアン銀行普通預金のアカウントから発生した飲食費用の支出を表すレコードをpostingsテーブルに挿入しようとする場合、このレコードは次のようになります。
| posting_index | trade_date | src_account | src_change | dst_account | comment |
|---|---|---|---|---|---|
| 1 | 2023-01-07 | 1 | -67.5 | 2 | ラストスタンドの夕食 |
ただし、このレコードを作成する際には、シャーレアン銀行普通預金のaccount_indexが1であることを確認してsrc_accountフィールドに入力し、飲食費用のaccount_indexが2であることを確認してdst_accountフィールドに入力する必要があります。特に、accountsテーブルに何十ものレコードが存在する場合、この検索作業は非常に大変です。
この問題を解決するため、TataruBookでは、ではインデックスの代わりに名字（アカウント名）を入力することが可能です。たとえば、上記のレコードをpostingsテーブルに挿入する場合、CSVファイルに次のように記述します (posting_indexのセルが空欄である理由については、自動生成されたインデックスフィールドを参照してください)）。
| posting_index | trade_date | src_account | src_change | dst_account | comment |
|---|---|---|---|---|---|
| 2023-01-07 | シャーレアン銀行普通預金 | -67.5 | 飲食費用 | ラストスタンドの夕食 |
その後、importコマンドを使用入力します。TataruBookは、シャーレアン銀行普通預金と飲食費用に対応するaccount_nameをaccountsテーブルから自動的に検出し、対応するレコードのaccount_indexを各フィールドに入力します。
この機能はimportコマンドだけでなく、insertコマンドでも利用可能です。上記のレコードは、次のようなコマンドを使用して直接挿入することもできます。
tatarubook insert example.db postings NULL 2023-01-07 シャーレアン銀行普通預金 -67.5 飲食費用 ラストスタンドの夕食
TataruBookの名前によるインデックス検索に関する具体的なルールは次のとおりです。
- まず、フィールドの内容をインデックスとして扱います。対応するインデックスレコードが存在する場合は、そのインデックス値を変換せずに直接参照します。たとえば、インデックス値が
666のレコードが存在する場合、入力された666はそのままインデックスとして認識されます。この場合、他に666という名前のレコードがあっても無視されます。 - インデックスに対応するレコードが存在しない場合、フィールドの内容と一致する、もしくはそれを含む唯一の名前を持つレコードを検索します。該当するレコードが見つかった場合、フィールドの内容をそのレコードのインデックスに変換されます。この処理は前述のimport和insertコマンドの例と同じです。
- フィールドの内容と一致する、もしくはそれを含むレコードが存在しないか、または複数のレコードが見つかった場合、実行は失敗し、エラーが報告されます。たとえば、
シャーレアン銀行普通預金とシャーレアン年金という２つのレコードはaccountsテーブルに存在し、フィールドの内容がシャーレアンであった場合、TataruBookはどのインデックスを参照すべきか判断できないため、エラーを報告します。
名前によるインデックス検索機能をサポートするフィールドの一覧は以下のとおりです。
| テーブル | フィールド | 参照テーブル | 検索対象の名前 | 変換後のインデックス |
|---|---|---|---|---|
| postings | src_account | accounts | account_name | account_index |
| postings | dst_account | accounts | account_name | account_index |
| interest_accounts | account_index | accounts | account_name | account_index |
| accounts | asset_index | asset_types | asset_name | asset_index |
| prices | asset_index | asset_types | asset_name | asset_index |
| standard_asset | asset_index | asset_types | asset_name | asset_index |
レコードを挿入する際には、インデックス値ではなく名前を入力することを強くお勧めします。この方法により、入力ミスを大幅に減らすことができます。
関連テーブルに自動挿入する
posting_extrasテーブルは、基本的にpostingsテーブルと同時に、対応するレコードが挿入されます。これは同一の取引記録に関するデータであるためです。そのため、取引記録を追加する際には、まずpostingsテーブルにレコードを挿入し、その後で挿入されたレコードのposting_index値を取得し、そのposting_index値に基づいてposting_extrasテーブルを編集し、最後に編集されたposting_extrasテーブルに挿入する必要があります。
このプロセスは明らかに手間がかかります。取引記録の挿入を簡素化するため、TataruBookは関連テーブルへの自動挿入機能が備わっています。postingsテーブルにレコードを挿入する際に、末尾に追加のフィールドを記入することで、TataruBookは同時に関連するposting_extrasテーブルにもデータを挿入します。この追加フィールドはposting_extrasテーブルのdst_changeの値に対応します。
例：import コマンドを使用して以下のようなCSVファイルをインポートすると、postingsテーブルとposting_extrasテーブルのそれぞれに一つのレコードが同時に挿入され、両方のレコードは同じposting_index値を持ちます。（src_accountとdst_accountの値が数字でない理由がわからない場合は、名前によるインデックスの検索を参照してください。posting_index下のセルが空欄になっている理由がわからない場合は、自動生成されたインデックスフィールドを参照してください）
| posting_index | trade_date | src_account | src_change | dst_account | comment | dst_change |
|---|---|---|---|---|---|---|
| 2023-05-22 | シャーレアン銀行普通預金 | -10000 | ガーロンド・アイアンワークス社の株 | 株を買う | 500 |
insertコマンドもこの機能をサポートしており、次のコマンドで同じ結果が得られます。
tatarubook insert example.db postings NULL 2023-05-22 シャーレアン銀行普通預金 -10000 ガーロンド・アイアンワークス社の株 株を買う500
dst_changeフィールドは必ず末尾に配置する必要があることに注意してください。TataruBookは位置に基づいてフィールドを識別するだけであり、CSVファイルのヘッダ一行の内容には考慮しません。
また、accountsテーブルも関連するレコードの挿入機能をサポートしています。accountsテーブルとasset_typesテーブルに関連するレコードをそれぞれ同時に挿入する必要がある場合は、importコマンドを一回実行するだけで完了します。使用するCSVファイルの内容は以下のようになります。
| account_index | account_name | asset_index | is_external | asset_name | asset_order |
|---|---|---|---|---|---|
| モーグリ証券_ガーロンドの株 | 0 | ガーロンド・アイアンワークス社の株 | 0 |
こうした状況は、新しいファンドや株式を購入する際、新しい資産タイプとアカウントを同時に追加する必要がある場合によく見られます。
コマンドの使用方法
help
-hまたは--helpパラメータを指定すると、コマンドのヘルプ情報が表示されます。次の２つのケースがあります。
- サブコマンドがない場合（例：
tatarubook -hと入力）、他のすべてのコマンドの簡単な機能説明がリストされます。 - サブコマンドがある場合（例：
tatarubook insert -hと入力）、該当するサブコマンドの詳細な使用方法が表示されます。
init
空のデータベースファイルを作成して初期化します。
コマンド形式：
tatarubook init [-h] db_file
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。ファイルがすでに存在している場合、操作は実行されず、エラーメッセージのみが表示されます。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。
check
データベースファイル内のデータが一貫性制約に準拠しているかどうかを確認します。
v1.1 の新機能:：データベースファイル内のすべてのテーブル、インデックス、およびビューの定義が現在のバージョンと一致しているかどうかを確認します。
コマンド形式：
tatarubook check [-h] db_file
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。
データの一貫性制約には２種類があります。
- 必須制約: 制約を満たさない場合、更新操作は直ちに失敗し、データは即座にロールバックされます。一般的に、フィールドタイプ、フィールド範囲、外部キーの有効性に関する制約がこれに該当します。必須制約は基礎となるデータベースにより保証されており、通常は違反できないため、
checkコマンドでは必須制約のチェックは行いません。 - 参照制約: 制約を満たさない場合でも、データの更新は可能ですが、修正が必要であることが通知されます。このような制約は、特定の日付における特定の資産に単位価格情報が必要である場合など、主に
checkビューを通じて確認されます。checkコマンドは、参照制約のみをチェックします。
データ一貫性の制約に関する詳細は、テーブルとビューの説明を参照してください。
データの一貫性は多くのレポートの正確性に影響するため、データベースファイルの更新が実行された後、TataruBookは自動的に一貫性チェックを実行し、その結果を報告します。
export
指定したテーブルやビュー、またはすべてのテーブルやビューの内容をCSVファイルにエクスポートします。
コマンド形式：
tatarubook export [-h] [--table TABLE] [--encoding ENCODING] db_file
パラメ—タ—：
--table TABLE（任意）：名前がTABLEであるテーブルまたはビューを指定します。このパラメータを指定しない場合、すべてのテーブルおよびビューがエクスポートされます。--encoding ENCODING（任意）：文字コード形式を指定します。文字コード形式の説明を参照してください。db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。
ファイル名の生成ルール: 対応するテーブルやビューの名前に.csvという拡張子が追加されます。同名のファイルがすでに存在する場合、そのファイルはスキップされますが、コンフリクトしない他のファイル があればエクスポートが続行されます。
insert
指定されたテーブルにレコードを挿入します（関連テーブルへの自動挿入がトリガーされない限り、通常は1件です）。
コマンド形式：
tatarubook insert [-h] db_file table values
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。table：テーブル名です。values：すべてのフィールドの値です。フィールドはスペースで区切られます。フィールドにスペースが含まれる場合は、引用符で囲む必要があります。
挿入操作には特別な処置が必要です。共通特性の説明を参照してください。
import
CSVファイルを使用して、指定されたテーブルに複数のレコードを一括インポート (または追加) します。テーブルに既に存在するレコードには影響しません。
コマンド形式：
tatarubook import [-h] [--table TABLE] [--encoding ENCODING] db_file csv_file
パラメ—タ—：
--table TABLE（任意）：名前がTABLEであるテーブルまたはビューを指定します。このパラメータを指定しない場合、csv_fileのファイル名に基づいてインポートするテーブルを自動的に判断します。--encoding ENCODING（任意）：文字コード形式を指定します。文字コード形式の説明を参照してください。db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。csv_file： csvファイル名です (パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。
TataruBookは、CSVファイルにヘッダー行があるかどうかを判別します。判別方法は、CSVの先頭行のすべてのセルが数値でない場合、その行をヘッダー行として認識します。注: TataruBookはヘッダー行を判別とスキップのみ行い、ヘッダー行に基づいてフィールドの順序を変更することはありません。フィールドの順序はテーブル定義に一致している必要があります。
レコードの挿入に失敗した場合、TataruBookはロールバックを実行し、importtコマンドを実行する前の状態に戻します。CSVファイル内の他のレコードが挿入可能であっても、データベースファイルには挿入されません。
インポート操作には特別な処置が必要です。共通特性の説明を参照してください。
overwrite
指定されたテーブルのすべての内容を削除し、新しいレコードを1件挿入します。このコマンドは、１つのフィールドしか含まないテーブルstart_date、end_date、standard_assetにのみ適用されます。
コマンド形式：
tatarubook overwrite [-h] db_file table content
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。table：テーブル名です。start_date、end_dateまたはstandard_assetのいずれかである必要があります。content：挿入された唯一のレコードの唯一のフィールドの内容です。
このコマンドは、１件のレコードのみを含むテーブルを迅速に変更できます。
delete
指定されたテーブル内で、指定されたインデックスに対応するレコードを削除します。
コマンド形式：
tatarubook delete [-h] db_file table values
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。table：テーブル名です。values：指定されたインデックスです。インデックスに複数のフィールドが含まれている場合、フィールドはスペースで区切られます。フィールドにスペースが含まれている場合は、引用符で囲む必要があります。
deleteコマンドでvaluesを入力する際は、指定されたインデックスを含むフィールドのみを入力し、すべてのフィールドを入力しないように注意してください。
postingsテーブルドのレコードが削除されると、もし対応するレコードがposting_extrasテーブルに存在する場合、そのレコードも同時に削除されます。
prune
CSVファイルのインデックスに対応する、指定されたテーブル内のレコードを一括で削除します。
コマンド形式：
tatarubook prune [-h] [--table TABLE] [--encoding ENCODING] db_file csv_file
パラメ—タ—：
--table TABLE（任意）：名前がTABLEであるテーブルを指定します。このパラメータが存在しない場合は、csv_fileのファイル名に基づいて操作対象のテーブルを判断します。--encoding ENCODING（任意）：文字コード形式を指定します。文字コード形式の説明を参照してください。db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。csv_file： csvファイル名です (パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。
TataruBookは、CSVファイルにヘッダー行があるかどうかを判別します。判別方法は、CSVの先頭行のすべてのセルが数値でない場合、その行をヘッダー行として認識します。注: TataruBookはヘッダー行を判別とスキップのみ行い、ヘッダー行に基づいてフィールドの順序を変更することはありません。フィールドの順序はテーブル定義に一致している必要があります。
注:CSVファイルの各行にはインデックスフィールドの値のみを含め、他のフィールドは含めないでください。
postingsテーブルドのレコードが削除されると、もし対応するレコードがposting_extrasテーブルに存在する場合、そのレコードも同時に削除されます。
あるインデックスの削除に失敗した場合、TataruBookはロールバックを実行し、pruneコマンドを実行する前の状態に戻します。CSVファイル内の他のインデックスが削除可能であっても、削除されません。
execsql
カスタムSQLコマンドを実行します。
コマンド形式：
tatarubook execsql [-h] db_file cmd
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。cmd：SQL コマンド文字列です。このパラメータを引用符で囲む必要があります。
TataruBookでは、SQLコマンドに対していかなるチェックや制約を一切行わないため、カスタムSQLコマンドの実行による結果はユーザー自身が責任負います。SQLコマンドによってテーブルやビューの定義が変更された場合、対応するデータベースファイルはTataruBookで正しく処理されなくなる可能性があります。
また、TataruBookには検索コマンドがないため、テーブルやビューの内容を直接検索したい場合には、CSVファイルにエクスポートする代わりにexecsqlコマンドを使用することができます。たとえば、次のコマンドでstatementsビューの内容を検索できます。
tatarubook execsql example.db "select * from statements"
upgrade
これはv1.1で追加された新しいコマンドです。
データベースファイル内のすべてのテーブル、インデックス、およびビューの定義を現在のバージョンと一致するように更新します。
コマンド形式：
tatarubook upgrade [-h] db_file
パラメ—タ—：
db_file：データベースファイル名です(パスの指定も可能)。パスやファイル名にスペースが含まれる場合は、このパラメータを引用符で囲む必要があります。
通常、データベースファイルのテーブル、インデックス、ビューの定義が現在のバージョンと一致しなくなるのは、TataruBookのアップグレードによるものです。TataruBookとデータベースファイル内のテーブル、インデックス、ビューの定義が一致しない場合、操作中に予期しないエラーが発生する可能性があります。TataruBookをアップグレードするたびに、まずupgradeコマンドを使用してデータベースファイルを最新バージョンに合わせることをお勧めします。
データベースファイルに含まれるテーブルやインデックスの定義が、現在のTataruBookに存在しない、または一致しない場合、upgradeコマンドはアップグレードを拒否し、エラーを報告します。これらのテーブルとインデックスの定義を削除または変更すると、ユーザーデータが失われる可能性があるためです。通常、TataruBookのアップグレードではビューの定義のみが変更され、テーブルやインデックスの定義は変更されません。
upgradeコマンドを使用する前に、データベースファイルをバックアップすることを強くお勧めします。