用户手册
本页介绍TataruBook支持的所有命令及选项。
命令行和快捷菜单
TataruBook是基于命令行的程序，但是在Windows 10或更高版本中提供了右键快捷菜单的调用方式。所有快捷菜单项都是对特定命令行的封装：当你在某个DB文件上使用快捷菜单命令时，TataruBook会自动转换成对应的命令行并填入文件名、表名等参数。因此，如果你想要查看快捷菜单中某个命令的解释，查看对应的命令行解释即可。
以下是可以用快捷菜单调用的命令列表。列表以外的命令只能通过命令行来调用。
| 触发方式 | 快捷菜单项 | 对应命令 |
|---|---|---|
| 文件夹内容空白处点右键 | TataruBook create DB file | init |
| DB文件上点右键 | TataruBook check | check |
| DB文件上点右键 | TataruBook export table | export |
| DB文件上点右键 | TataruBook export view | export |
| DB文件上点右键 | TataruBook paste | paste |
| DB文件上点右键 | TataruBook upgrade | upgrade |
Windows 11会默认隐藏一部分快捷菜单项，你需要先指定显示所有的菜单项才能找到某些命令。
TataruBook有两种安装方式，与之对应的有两种命令行用法：可执行文件用法和Python脚本用法。为了简便起见，本文档都以可执行文件用法为示例。如果采用的是Python脚本用法，则需要将所有命令开头从tatarubook换成python tatarubook.py（假设你的解释器通过python运行）。比如，要创建一个名为example.db的数据库文件，需要将tatarubook init example.db命令改为python tatarubook.py init example.db。
通用特性
下面介绍一些和多个命令都有关的特性：
字符编码格式
默认设置下，TataruBook使用操作系统默认字符编码格式读写文件。但是注意非英文Windows操作系统的默认字符编码格式不是UTF-8，因此在Windows下读取UTF-8格式的CSV文件时，TataruBook可能会遇到解码错误。为了解决这个问题，TataruBook在用其他格式解码失败时，会再尝试使用UTF-8解码一次。
如果想要TataruBook使用其他的字符编码格式读写文件，可以在相关命令中使用--encoding选项指定字符编码格式，支持的编码格式列表见这里。
自动生成的索引字段
有一些字段的值是在插入时自动生成的，比如accounts表的account_index，postings表的posting_index等等。当用insert命令插入这些表的记录时，这些字段的值应当填写为NULL；用import或paste命令导入记录时，这个字段对应单元格的内容应当为空。这样，TataruBook会自动找到一个与其他记录不同的新索引值填入这个字段。
日期的输入格式
在输入日期时，TataruBook要求一个日期包含且仅包含年、月、日三个成员，且成员排列顺序依次为年、月、日。成员之间可以用/、-、.三种字符中的任一种分隔，但是分隔符必须一致。年必须是4位数字，月和日可以是1位或2位数字，可以有或者没有前导0。
年、月、日之间也可以没有分隔符，但没有分隔符时整个日期必须是8位数字，形式为yyyymmdd。
以下日期格式都是合法的：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表的记录，可以写成这样（如果你不明白为什么posting_index下面的单元格是空的，见自动生成的索引字段）：
| posting_index | trade_date | src_account | src_change | dst_account | comment |
|---|---|---|---|---|---|
| 2023-01-07 | 萨雷安银行活期 | -67.5 | 餐饮消费 | 背水咖啡厅晚餐 |
插入时，TataruBook会自动查找accounts表中哪条记录的account_name为萨雷安银行活期，哪条记录的account_name为餐饮消费，并把这两条记录的account_index填到对应的字段。
不光import和paste命令支持这个功能，insert命令也支持这个功能。上面的这条记录也可以直接用一条命令插入：
tatarubook insert example.db postings NULL 2023-01-07 萨雷安银行活期 -67.5 餐饮消费 背水咖啡厅晚餐
TataruBook根据名字查找索引的具体规则如下：
- 首先把字段内容看成是索引，如果该索引对应的记录存在，那么直接用这个索引值不做转换。例如：如果存在一条记录的索引是
666，那么输入的666会被直接解释为索引——即使其他记录中存在名字是666的，也会被忽略。 - 如果该索引对应的记录不存在，那么查找名字等于或者包含字段内容的唯一记录。如果找到了，把字段内容转换为这条记录的索引。这个过程由本节中前面的例子所展示。
- 如果没有记录的名字等于或者包含该字段内容，或者找出的记录不止一条，那么执行失败并报错。例如：如果存在两条
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_extras表的记录写入这个posting_index，最后再插入posting_extras表的记录。
这个过程显然很麻烦。为了简化交易记录的插入，TataruBook支持自动插入关联表的记录功能。当插入postings表的记录时，如果在末尾多写一个字段，TataruBook即认为这是要关联插入posting_extras表，这个多出的字段是posting_extras表的dst_change字段的值。
举例：用paste命令插入下面的记录，或者用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只根据位置来识别字段，不关心表头的内容。
accounts表也支持关联插入功能：如果要插入的accounts表记录对应的asset_types表记录也需要插入，那么可以用一次操作完成，使用的表格内容如下：
| account_index | account_name | asset_index | is_external | asset_name | asset_order |
|---|---|---|---|---|---|
| 莫古证券_加隆德股份 | 0 | 加隆德炼铁厂股份 | 0 |
这种场景常见于买入新的基金/股票品种时，需要同时添加新的资产类型和新的账户。
命令使用方法
help
使用-h或--help参数时，会给出命令帮助信息。分两种情况：
- 没有子命令时（比如输入
tatarubook -h），会列出所有其他命令的简要功能说明。 - 有子命令时（比如输入
tatarubook insert -h），会提示对应子命令的详细用法。
init
创建并初始化一个空的DB文件。
命令格式：
tatarubook init [-h] db_file
参数：
db_file：DB文件名，可带路径。如果该文件已存在，不会执行任何操作，只打印错误信息。如果路径和文件名中有空格，需要在这个参数两侧加上引号。
check
检查DB文件中的数据是否符合一致性约束。
v1.1版本新增功能：检查DB文件中所有的表、索引、视图定义与当前版本是否一致。
命令格式：
tatarubook check [-h] db_file
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。
数据一致性约束分为两种：
- 强制性约束：如果不满足，那么修改操作会立即失败，数据会马上回滚。一般来说，字段值类型/范围约束、外键有效性都是强制性约束。由于强制性约束已经由底层数据库保证，在正常情况下不可能被违反，所以
check命令不会检查强制性约束。 - 警示性约束：如果不满足，数据仍然允许修改，但是会提示需要修复。这种约束大多通过特定的
check视图来检查，比如要求特定日期特定资产需要有价格信息。check命令只检查警示性约束。
想了解数据一致性约束包含哪些检查，可以查看表和视图中的说明。
由于数据一致性对很多报表的正确性都有影响，因此TataruBook在执行了任何修改DB文件的操作后，都会自动运行一次数据一致性检查并报告结果。
export
把指定表/视图或者所有表/视图的内容导出到CSV文件。
命令格式：
tatarubook export [-h] [--table TABLE] [--encoding ENCODING] db_file
参数：
--table TABLE（可选）：指定名字为TABLE的表或视图。如果没有这个参数，导出所有的表和视图。--encoding ENCODING（可选）：指定字符编码。见字符编码格式中的说明。db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。
生成文件名的规则：对应表/视图的名字加上.csv后缀。如果遇到某个文件已经存在，则会跳过这个文件，但仍会导出其他没有冲突的文件（如果存在的话）。
insert
插入指定表的一条记录（通常是一条，除非触发自动插入关联表的记录功能）。
命令格式：
tatarubook insert [-h] db_file table values
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。table：表名。values：所有字段的值，字段之间以空格分隔。如果某个字段中含有空格，需要用引号括起来。
插入操作有一些特殊的处理，见通用特性中的说明。
import
使用CSV文件批量导入（新增）指定表的一批记录，表中已经存在的记录不受影响。
命令格式：
tatarubook import [-h] [--table TABLE] [--encoding ENCODING] db_file csv_file
参数：
--table TABLE（可选）：指定名字为TABLE的表。如果没有这个参数，则根据csv_file的文件名判断导入哪个表。--encoding ENCODING（可选）：指定字符编码。见字符编码格式中的说明。db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。csv_file：CSV文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。
TataruBook会自动判断CSV文件有没有表头，判断方式是：如果CSV的第一行所有列都不是数字，那么就认为是表头。注意：TataruBook只判断并跳过表头，不会根据表头的内容来调整字段顺序。字段顺序必须和表定义一致。
如果在插入某条记录时处理失败，那么TataruBook会执行回滚，整个DB文件会被还原到执行这条import命令之前的状态，即使CSV文件中其他记录可以插入成功，也不会被插入。
导入操作有一些特殊的处理，见通用特性中的说明。
overwrite
把指定表的所有内容删除，然后插入一条记录。这个命令只适用于仅含一个字段的表：start_date、end_date、standard_asset。
命令格式：
tatarubook overwrite [-h] db_file table content
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。table：表名，必须是start_date、end_date、standard_asset之一。content：插入的唯一一条记录的唯一字段的内容。
这个命令可看作是对仅含一个值的表的快捷修改方式。
paste
这是v1.2版本新增的命令。该命令使用PowerShell来读取剪贴板内容，只能在Windows系统中使用。
将剪贴板中的内容解析为指定表的一条或多条记录，并插入到该表中。剪贴板中多条记录需要以换行分隔，一条记录的多个字段需要以制表符分隔，每个字段的内容不允许包含制表符。
如果你从文本编辑器（如记事本）中复制内容到剪贴板，那么需要自行遵循上面的格式要求。如果你从Excel中复制内容到剪贴板，那么Excel复制的格式即符合该要求，但是你必须保证每个单元格内容中不包含制表符。注意不要用文本编辑器打开CSV文件并复制内容，因为CSV文件的各个字段是用逗号分隔的，不符合格式要求。你应该用Excel打开CSV文件再复制。
当table参数是start_date、end_date、standard_asset之一时，该命令执行overwrite的操作；否则，对剪贴板中每条记录执行insert的操作。
命令格式：
tatarubook paste [-h] db_file table
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。table：表名。
TataruBook会自动判断剪贴板中的内容是否包含表头，判断方式是：如果第一行所有列都不是数字，那么就认为是表头。注意：TataruBook只判断并跳过表头，不会根据表头的内容来调整字段顺序。字段顺序必须和表定义一致。
如果在插入某条记录时处理失败，那么TataruBook会执行回滚，整个DB文件会被还原到执行这条paste命令之前的状态，即使剪贴板中其他记录可以插入成功，也不会被插入。
插入操作有一些特殊的处理，见通用特性中的说明。
delete
删除指定表指定索引的一条记录。
命令格式：
tatarubook delete [-h] db_file table values
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。table：表名。values：指定的索引值。如果索引包含了多个字段，字段之间以空格分隔。如果某个字段中含有空格，需要用引号括起来。
注意delete命令输入的values只含索引字段的值，不要输入所有字段。
当删除postings表的记录时，如果有与之对应的posting_extras表记录，那么posting_extras表中的这条记录也会被一并删除。
prune
删除指定表中由CSV文件给出的一个或多个索引对应的一批记录。
命令格式：
tatarubook prune [-h] [--table TABLE] [--encoding ENCODING] db_file csv_file
参数：
--table TABLE（可选）：指定名字为TABLE的表。如果没有这个参数，则根据csv_file的文件名判断操作哪个表。--encoding ENCODING（可选）：指定字符编码。见字符编码格式中的说明。db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。csv_file：CSV文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。
TataruBook会自动判断CSV文件有没有表头，判断方式是：如果CSV的第一行所有列都不是数字，那么就认为是表头。注意：TataruBook只判断并跳过表头，不会根据表头的内容来调整索引字段的顺序。索引字段的顺序必须和表定义一致。
注意CSV文件中每一行只含索引字段的值，不要包含其他的字段。
当删除postings表的记录时，如果有与之对应的posting_extras表记录，那么posting_extras表中的这条记录也会被一并删除。
如果在删除某个索引时处理失败，那么TataruBook会执行回滚，整个DB文件会被还原到执行这条prune命令之前的状态，即使CSV文件中其他索引可以删除成功，也不会被删除。
execsql
执行自定义的SQL命令。
命令格式：
tatarubook execsql [-h] db_file cmd
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。cmd：SQL命令字符串，需要在这个参数两侧加上引号。
TataruBook不对SQL命令进行任何检查和约束，执行自定义的SQL命令所造成的后果由用户自己负责。如果SQL命令修改了表/视图的定义，可能导致这个DB文件以后无法再被TataruBook正确处理。
由于TataruBook没有查询命令，如果想在命令行直接查询某个表/视图的内容（而不是导出到CSV文件），可以使用execsql命令来完成。比如，下面这条命令可以查询statements视图的内容：
tatarubook execsql example.db "select * from statements"
upgrade
这是v1.1版本新增的命令。
尝试将DB文件中所有的表、索引、视图定义修改为与当前版本一致。
命令格式：
tatarubook upgrade [-h] db_file
参数：
db_file：DB文件名，可带路径。如果路径和文件名中有空格，需要在这个参数两侧加上引号。
通常DB文件的表、索引、视图定义与当前版本不一致是由于TataruBook软件升级导致的。如果TataruBook软件和DB文件的表、索引、视图定义不一致，可能在操作时出现无法预知的错误。建议每次TataruBook升级以后，先用upgrade命令修改DB文件与当前版本一致。
如果DB文件中存在表、索引的定义在当前TataruBook中不存在，或者与TataruBook中的定义不一致，则upgrade命令会拒绝升级并报告错误。因为如果删除或者修改这些表、索引定义，可能会造成用户数据丢失。通常TataruBook软件升级时只会修改视图的定义而不会修改表、索引的定义。
强烈建议在使用upgrade命令之前备份DB文件。