CavemanDB：像Python字典一样简单的嵌入式键值数据库

搞过几年自动化脚本的人，大概都有过这种尴尬：程序里需要存一点中间状态，最不该惊动数据库。本地爬虫跑了一半要断点续爬，定时任务想记一下上次执行时间，脚本之间要传一份名单……结果你一搜方案，全是MySQL、Redis、MongoDB，装完服务端比写业务代码还费劲。后来我在一个开源项目列表里翻到一个小库，名字就叫CavemanDB——caveman直译过来就是穴居人，它的设计哲学跟名字一样原始：单文件、零依赖、像Python字典一样存数据。这篇记录就围绕这个“穴居人”数据库，把该踩的坑和该用的API都梳理一遍，给同样被本地存储困扰的人一个真正轻量的选择。

1. “穴居人”数据库到底是个啥

1.1 名字里的开发哲学

第一眼看到CavemanDB，我以为是给什么远古生物建模的工具，看完README才知道是个数据库。不过仔细想想这名字起得挺妙。现代数据库像座装修精致的摩天楼，使用前得配工程师、办门禁、拉网线；CavemanDB则直接把东西塞回山洞，洞口竖块牌子“货在这，自己拿”。它的设计目标就是原始、简单、能用。

技术层面，CavemanDB是Python生态里的嵌入式键值数据库。嵌入式意味着它不像MySQL那样有一个独立服务端，你的程序启动时它就在，程序退出后就安安静静躺成一个文件。键值则意味着你不需要写SQL，不需要建表、建索引、配权限，所有操作都围绕“键”和“值”展开。值本身可以是字典、列表、字符串、数字这类JSON能表达的数据，所以结构上的自由度反而很高。

你也许会觉得：这跟SQLite有什么区别？区别在于SQLite再怎么说也带一套SQL引擎，你得知道CREATE TABLE、INSERT、SELECT怎么写，碰到复杂查询还要想JOIN。而CavemanDB把这一切都剥掉了，留下来的就是Python开发者最熟悉的字典操作。从“数据库思维”退回到“数据结构思维”，这是它最核心的差异化。

1.2 能解决什么问题，适合谁

它擅长解决一类问题：本地脚本想要一个能跨重启保存的“大字典”。我举几个切身例子：爬虫跑到一半中断，需要一个集合记录哪些URL已经处理；定时任务每次启动要读上一次运行时间；内网工具需要维护一份用户名单，让不同脚本共享。这些需求用MySQL是杀鸡用牛刀，用JSON文件又得自己处理读写和一致性，而CavemanDB在中间给了一个刚刚好的台阶。

适合看这篇内容的人，我猜是这三类。第一类，正在写各类自动化脚本，被“本地状态怎么存”困扰的开发者；第二类，个人项目起步阶段不想为一小块数据引入重型组件的独立开发者；第三类，刚学Python不久，想理解“原来数据落盘可以这么简单”的新手。如果你属于这三类，下面的内容基本可以照单全收。

2. 安装与初体验：三步跑起来

2.1 环境要求与安装

先解决环境问题。CavemanDB是纯Python实现的，这意味着只要你的机器能跑Python，大概率就能跑它。我在Python 3.8、3.10、3.11上实测过，没遇到编译或依赖问题。官方建议用新版本解释器，你本地如果还停留在Python 3.6之前，建议先把解释器升一升，毕竟很多语法糖和新库都不再支持老版本了。

安装命令一句话：

pip install cavemandb

这里有个容易踩的坑：项目在README里写作CavemanDB，PyPI上的包名却是全小写cavemandb，大小写拼错就装不上。如果你用国内镜像源，直接装这个包名也一样能用。装完之后可以用pip show cavemandb确认版本和安装路径，顺便看看它依赖了哪些第三方包——正常情况下列表里几乎只有它自己。

2.2 验证安装是否OK

装完先不着急写业务代码，跑一个最简单的冒烟测试：

python -c "from cavemandb import CavemanDB; db = CavemanDB('smoke'); db['ping'] = 'pong'; print(db['ping']); db.close()"

正常会输出pong，同时在你当前目录下生成一个以smoke为前缀的数据库文件。注意这个动作本身就在测试两件重要的事：模块能导入、数据能落盘。如果输出正常，说明CavemanDB的底层存储通道已经通了。

我习惯再多一步：打开Python交互式解释器，连敲一遍写入、修改和遍历。因为后面我会用到的API比较多，提前在交互环境里试错，比直接塞进大工程里省事得多。

2.3 第一段代码：写入、读取、关闭

第一次使用的完整代码可以简单到让人怀疑：

from cavemandb import CavemanDB db = CavemanDB('users') db[1] = {'name': 'Bob', 'age': 25} print(db[1]) db.close()

这里发生了三件事。第一，CavemanDB('users')如果users库不存在就新建，存在就打开。第二，db[1] = ...把一条记录写入数据库，键是数字1，值是一个字典。第三，db.close()把内存里的数据写回文件。很多人第一次写的时候容易漏掉close，在交互式环境里可能感觉不到问题，等脚本一退出数据就丢了。

到这里CavemanDB的轮廓已经很清楚：你把它当成一个会自动保存的字典来用，就成功了一半。

3. 核心API逐项拆解与实测

3.1 写入数据：像写字典一样自然

核心写入方式就是赋值语句，db[key] = value。键用什么类型？官方推荐用字符串或数字，实际用元组这种不可变类型也能撑住，但我不太建议在键上玩花样——键的意义就是唯一定位，保持简单最好。值只要是JSON兼容的结构都可以，字符串、数字、列表、字典随意嵌套。

有一点必须提醒：同样的键再次赋值会直接覆盖旧值。如果你只是想更新一个字段，后面讲的update更合适。另外，数据库文件里存的字段顺序不会保证和你赋值顺序一致，所以别写依赖字段顺序的代码，要用键访问而不是按下标猜。

3.2 读取数据：get、in与KeyError

读数据最直接的方式是：

record = db[1]

键不存在时会抛KeyError，这跟dict行为一致。如果不希望抛异常，就改用get：

record = db.get(1) print(record) # None

通过in判断键是否存在也很好用：if 1 in db。这三个操作组合起来，几乎覆盖日常所有读取需求。

值得多说一句的是，db.get返回的是一个普通的Python对象副本，而不是指向数据库内部的引用。你拿到后随便改都不会影响数据库文件，必须再赋值回去才能生效。这个特性很多人一开始意识不到，后面我会专门讲它引发的经典Bug。

3.3 更新与删除：修改数据的正确姿势

如果value是字典，全量覆盖会丢掉没提到的字段。比如任务记录里有status和runs两个字段，你想单独改status，直接db[key] = {'status': 'done'}会把runs清空。CavemanDB为此提供了update方法：

db.update(1, {'status': 'done'})

update做的是字段级合并，已有字段更新，没有字段新增，未提到的字段保持原样。这个语义非常像Redis里的hset，特别适合存配置类数据。

删除记录用pop：

db.pop(1)

pop返回被删除的值，键不存在时会抛KeyError，你可以先判断或者捕获。整体来看，更新和删除都保持了“字典手感”，但方法论上有微妙区别：赋值是整体替换，update是局部修补，选错就会丢数据。

3.4 遍历、批量处理与库大小

遍历数据库所有记录，最标准的写法是：

for key, value in db: print(key, value)

CavemanDB实现了迭代协议，所以你不用额外调items()之类的方法。库里还提供forEach，适合传回调函数：

db.forEach(lambda k, v: print(k, v))

两者效果类似，forEach在你想把处理逻辑封装成一个函数时更顺手。

统计数量用db.size()，返回当前记录条数。判断某键存在用db.exists(key)，效果和in一样。这里容易踩一个心理预期上的坑：遍历顺序不等于写入顺序。底层存储经过序列化之后，数据在文件里的排布方式跟你write的先后没有必然关系，所以写业务逻辑时别默认第一条就是最早那条，需要有序就自己维护时间戳字段。

3.5 条件查询与模糊匹配

纯按键存取已经能解决很多问题，但业务里难免要“找所有年龄大于30的人”这种需求。CavemanDB提供了一个轻量查询方法query，用法大致如下：

adults = db.query('age', '>=', 30) for row in adults: print(row)

第一个参数是字段名，第二个是比较操作符，第三个是目标值。官方支持的比较符包括=、>、<、>=、<=这些常见操作。我建议查询前先确认字段实际类型，因为底层序列化后，数字和字符串是严格区分的。如果你存的时候age是整数，query时传的'30'是字符串，可能查不到任何结果。宁可统一：存整数，查整数；或者存字符串，查字符串。

很多版本还带一个find方法，用来做基于键的模糊查找，比如找到所有键里包含某个子串的记录。这个方法名字听着好用，但不同版本返回结构有过调整，如果你用的版本行为跟自己预期不一致，先跑一遍dir(db)看看帮助文档，再决定怎么处理返回值。

3.6 close与持久化原理

最后一个关键操作是close。很多资料一句话带过“用完记得关闭”，但没解释为什么。CavemanDB底层用了延迟写回的存储机制，数据在内存里改了之后，并不会每一个瞬间都同步到磁盘。不管底层实际的同步策略如何，close都是最可靠的数据落盘时机。写脚本时最稳妥的姿势是放进try/finally里，或者干脆给db封装一个with用法：

from contextlib import contextmanager @contextmanager def open_caveman(name): db = CavemanDB(name) try: yield db finally: db.close()

以后就可以写成with open_caveman('users') as db:，再也不用担心忘关。这个自定义封装几乎是我所有用到CavemanDB的脚本必不可少的标配。

4. 完整实操：做一个“本地任务状态记录器”

4.1 需求拆解：这个小工具要做什么

前面API讲得再多，不如一个完整例子来得踏实。我选了一个特别贴近日常的场景：本地任务状态记录器。假设你有一堆定时脚本：每天备份数据库、每周生成报表、定期清理日志。你想知道每个任务上次什么时候跑的、跑了多少次、最近状态是什么。这个信息放MySQL太重复，放纯文本要自己解析，用CavemanDB刚刚好。

拆开来看需求就三点：能按任务名记录状态；能更新状态的同时保留其他字段；能遍历所有任务看总览。这正好对应update、赋值、for遍历三个操作，没有多余的复杂度。

4.2 完整代码与配置思路

代码我贴一个能跑的版本：

from datetime import datetime from cavemandb import CavemanDB db = CavemanDB('task_status') def mark_running(task_name): db.update(task_name, { 'status': 'running', 'started_at': datetime.now().strftime('%Y-%m-%d %H:%M:%S'), }) def mark_done(task_name): record = db.get(task_name) if record is None: record = {'status': 'pending', 'runs': 0} record['status'] = 'done' record['finished_at'] = datetime.now().strftime('%Y-%m-%d %H:%M:%S') record['runs'] = record.get('runs', 0) + 1 db[task_name] = record def show_all(): for key, value in db: print(key, value) mark_running('daily_backup') mark_done('daily_backup') mark_done('report_generate') show_all() db.close()

这段代码有几个关键设计可以拎出来讲。mark_done里没有用update直接改runs加一，而是先get出来整体修改再赋值回去，因为update做的是“合并”，不能做“自增运算”。这正好呼应了3.2里说过的“读出来的是副本”的概念。而mark_running用update，是因为“每天开始跑的时候标记running，不允许覆盖掉之前的runs历史”，这种场景合并更新才安全。

4.3 运行效果与数据验证

运行上面的脚本，输出大致如下：

daily_backup {'status': 'done', 'runs': 1, 'started_at': '2025-03-20 10:00:00', 'finished_at': '2025-03-20 10:00:03'} report_generate {'status': 'done', 'runs': 1, 'finished_at': '2025-03-20 10:00:03'}

你会注意到daily_backup这条记录里同时存在started_at和finished_at，report_generate没有started_at字段，这正是update合并和整体赋值混用的结果。任务记录天然就是这样：有的任务需要记录开始时间，有的任务只关心结束时间。第二次运行脚本，daily_backup的runs会变成2，这就验证了数据真正持久化了，而不是每次脚本一跑就从头开始。

如果想确认文件确实在磁盘，可以直接看当前目录下的task_status前缀文件。文件不是人类可读的JSON文本，不要尝试用编辑器改它，改坏了数据就真没了。真要改数据就写Python脚本走API。

4.4 扩展思路

这个例子的骨架其实可以套用到很多场景。想记录爬虫断点，就把task_name换成url_hash，把status换成processed/unprocessed；想当临时缓存，就把key换成接口地址，value塞API响应和过期时间；想当简单的分组配置中心，就把key换成用户ID，value放分组信息。CavemanDB不提供索引、不提供SQL聚合查询，但正因为没有这些，用起来反而没有任何心智负担。

5. 该用它和不该用它：场景边界与选型

5.1 真正值得用的四个场景

第一个：单机脚本的状态保存。比如爬虫去重集合、定时任务状态、批量处理进度，数据量不大，但必须跨重启保留。第二个：小工具的原型验证。想法还没跑通，不想先建库建表，用一个键值库把流程串起来，等验证完再考虑换不换重型存储。第三个：配置与名单共享。几个脚本之间要共享一份白名单或映射关系，用API读写比手工编辑多个JSON文件更不容易出错。第四个：临时或内部演示项目。给同事演示一个Demo，数据库就是程序目录下一个文件，拷到哪都能跑，不用装服务。

这些场景的共同点是：单进程、低频写、数据规模小、查询简单。

5.2 不建议使用的场景

反过来，碰到下面几种情况，我会直接劝退。第一，多进程或多用户同时写同一个库文件，CavemanDB底层不是为高并发设计的，两个进程同时写很容易出现数据损坏或互相覆盖，它没有事务、锁和WAL这些机制。第二，数据量超过几十万条或者单条记录很大，每次读写都涉及序列化和文件同步，性能会很吃力。第三，业务需要复杂查询，比如跨多个键做关联、按多个字段排序分页，这些是数据库引擎的本职，键值存储硬做只会写出又慢又绕的代码。第四，强一致性和事务性要求，比如多步操作要么全成功要么全失败，这类场景必须交给成熟的事务数据库。

5.3 与SQLite、MySQL、Redis的横向对比

为了方便选型，我整理了一张对比表，纯按“本地小工具”这个视角来看：

看这张表你会发现，CavemanDB和SQLite其实有重叠区间，但定位并不冲突。SQLite适合需要SQL能力但不想开服务器的单机应用，CavemanDB适合“根本不需要SQL”的纯键值场景。如果你的需求一句话就能描述清楚，CavemanDB更省事；如果你脑子里已经开始冒出“要按日期分组统计”这种念头，直接选SQLite。

5.4 选型心法：一个“洞穴”够不够

我自己的选型心法很简单：先用最原始的工具把想法验证出真伪，是程序员很珍贵的习惯。很多本地脚本的寿命只有几天，根本等不到它长成庞大系统的那一天。与其一开始就上重型存储，不如先用一个字典式数据库跑起来，等真的出现性能瓶颈或并发需求，再迁移也不迟。迁移数据无非就是读出来再写进去，键值结构迁移到SQLite或者MySQL都极其直接。

6. 常见问题与避坑实录

6.1 数据没落盘：最常见的翻车现场

我见过最多的求助就是“明明写进去了，程序一重启什么都没了”。排查顺序很简单：先看有没有调close。脚本正常结束倒还好，如果程序被Ctrl+C中断、被kill、或运行中有异常抛出，close不一定能执行。解决办法就是try/finally或者我之前给的自定义上下文管理器，把close交给流程保证。其次看是不是改了内存副本没写回，比如db[key]['a']=1，这种操作在CavemanDB里不会自动触发文件保存，必须db[key]=整条记录。

6.2 改嵌套字段不生效：字典引用的幻觉

承接上面，很多人觉得“我明明改了字典啊”。原因是db[key]返回的是一个Python字典的副本，你改副本上的嵌套字段时，数据库里对应的旧值没有被任何机制追踪到。这种代码不会报错，但效果就是静默失效，排查起来很费眼神。根治方法就是统一写回：先读出来，改完之后用db[key] = record整个赋回去，或者能用update就用update。记住一条原则：CavemanDB不做对象级联动，一切以显式写回为准。

6.3 类型与序列化边界

CavemanDB的值最终要能被序列化存储，所以set集合、自定义类实例、bytes这类类型大概率会出问题。我测试过set直接写入会报错，bytes在不同版本下表现也不统一，总之别在边界上试探。遇到set就先转成list，遇到对象就转成dict，规规矩矩用JSON兼容的类型。键也一样，虽然理论上支持不可变类型，但为了跨版本稳定，字符串和数字已经覆盖绝大多数场景。

6.4 并发写与多进程

多进程同时打开同一个库，读写时机完全不可控。我做过一次惨痛实验：两个脚本同时往里写统计数据，跑了一晚上，第二天发现文件里的记录互相覆盖，数据整个废掉。如果你非要并发，建议加一个本机进程锁，把写操作串行化。更稳妥的做法是只在主进程使用，其他进程通过管道或消息队列把数据交给主进程写。CavemanDB的定位就是“一个程序自己用”，别指望它是共享存储。

6.5 数据库文件不见了或者“找不着”

文件位置由当前工作目录决定，而不是脚本文件所在目录。如果你在项目根目录跑python src/main.py，文件就会出现在项目根目录；如果你在src目录里跑，文件就在src目录里。同一个脚本在不同目录运行会读到不同的库，这经常造成“为什么数据时有时无”的错觉。解决方案是在初始化之前用绝对路径：

import os from cavemandb import CavemanDB db_path = os.path.join(os.path.dirname(__file__), 'data', 'task_status') db = CavemanDB(db_path)

提前把目录固定下来，就不会出现“文件神秘失踪”的问题。

6.6 常见问题速查表

这张表基本是我从真实翻车经历里整理出来的，每条都能对应一个具体场景。建议新项目刚开始的时候，把这几条先记在脑子里，能省下不少调试时间。

7. 最后：从“穴居人”到开发者的原始本能

聊完CavemanDB，忍不住想多说一句题外的“穴居人”。在编程圈子里，有个词叫caveman debugging，指的是不靠复杂的日志系统、链路追踪、性能分析工具，而是直接用print把关键变量打出来，一步步缩小问题范围的老派调试法。老一辈程序员嘴上嫌弃它不优雅，手上却诚实得很——遇到诡异Bug，第一反应还是加print。

CavemanDB其实呼应了同一种哲学：在系统复杂度膨胀的时代，刻意保持原始和简单，本身就是一种能力。我自己做本地小工具越多，越觉得大部分需求根本不需要“数据库”三个字背后的那些宏大概念。一个字典能装下的东西，就不要给它准备一间机房。

如果你最近正打算为一个小脚本装Redis或者MySQL，我劝你先缓一缓。用pip install cavemandb试两天，把数据从“不知道存哪”变成“随手就能存”，再把注意力放回业务本身。很多时候，最简单的方案反而是最不容易出错的方案。希望这篇记录能帮你省掉一些纠结，也少踩几个我踩过的坑。