pickledb,一个轻量的 Python 库

大家好，我是木木。

今天给大家分享一个轻量的 Python 库，pickledb。

pickledb

pickledb 是一个很轻的本地 key-value 存储库，新版本提供同步/异步统一接口，也支持 SQLite 后端。它适合命令行工具、小脚本、机器人本地状态、临时配置和少量结构化数据。需要注意的是，轻量并不等于万能；如果数据量大、并发写多或需要复杂查询，还是应该换成 SQLite、DuckDB 或正式数据库。

项目地址：https://github.com/patx/pickledb

官方文档：https://patx.github.io/pickledb/

三大特点

简单直达

set、get、all 这些接口很直接，小工具保存状态不用搭数据库。

异步可用

同一套方法能在同步和异步代码里使用，适合脚本和机器人场景。

后端可选

文件模式轻便，SQLite 后端更适合需要多 key 持久化的场景。

最佳实践

安装方式：pip install pickledb。

第一段代码解决的问题是：用 JSON 文件保存少量 key-value 数据，并手动 save 到磁盘。

importos,tempfilefromimportlib.metadataimportversionfrompickledbimportPickleDBpath=os.path.join(tempfile.gettempdir(),"pickledb_demo.json")ifos.path.exists(path):os.remove(path)db=PickleDB(path).load()print("package:",version("pickledb"))print("initial keys:",db.all())db.set("user:1",{"name":"Alice","points":18})db.set("user:2",{"name":"Bob","points":9})db.save()print("keys:",sorted(db.all()))print("alice points:",db.get("user:1")["points"])

第二段代码解决的问题是：在 async 代码里使用同一套 PickleDB API，适合异步机器人或任务脚本。

importasyncio,os,tempfilefrompickledbimportPickleDBasyncdefmain():path=os.path.join(tempfile.gettempdir(),"pickledb_async.json")ifos.path.exists(path):os.remove(path)asyncwithPickleDB(path)asdb:awaitdb.set("task:1",{"status":"queued"})awaitdb.set("task:2",{"status":"done"})print("async keys:",sorted(awaitdb.all()))print("task 1:",(awaitdb.get("task:1"))["status"])asyncio.run(main())

环境与版本信息

本文示例使用 Python 3.11，pickledb 1.6。示例写入系统临时目录，运行结束后不会依赖固定外部服务。

高级功能

进阶一点看 SQLite 后端。它仍然是 key-value 接口，但底层每个 key 会作为 SQLite 行保存。

importos,tempfilefrompickledbimportPickleDBSQLitepath=os.path.join(tempfile.gettempdir(),"pickledb_demo.sqlite3")ifos.path.exists(path):os.remove(path)db=PickleDBSQLite(path)new_key=db.set(None,{"event":"signup","score":3})db.set("quota:api",{"limit":100})print("generated key:",len(new_key)==36)print("sqlite count:",len(db.all()))print("quota:",db.get("quota:api")["limit"])db.close()

适用场景

适合 CLI 状态、本地配置、小型机器人状态、少量缓存和不想额外部署数据库的轻量脚本。

不适用场景

不适合高并发写入、大量复杂查询、强事务、多用户权限或需要审计的数据系统。

上线检查

1. 明确数据量上限，不要把它当通用数据库。
2. 重要数据要定期备份文件或 SQLite 数据库。
3. 并发写入场景先压测，避免覆盖或锁竞争问题。

总结

pickledb 适合那些“不值得上数据库，但又不想手写 JSON 文件”的场景。边界小，反而很好用。