jsondb-rb

把一个 JSON 文件当数据库读写的 Ruby 库。零运行时依赖（纯标准库），MongoDB-lite 查询语法，落盘永远原子。

gem 名 jsondb-rb（rubygems 的 jsondb 已被 2014 年旧库占用）；require 路径与模块名不变：require 'jsondb' → JsonDb。

require 'jsondb'

db = JsonDb.open('app.json')
users = db[:users]

users.insert(name: 'Ann', age: 31, tags: %w[ruby db])
users.insert_many([{ name: 'Bob', age: 17 }, { name: 'Cara', age: 45 }])

users.where(age: { gte: 18 }).order(:name).limit(10).to_a
users.where('profile.city' => 'SZ', age: (18..60)).count
users.where('$or' => [{ vip: true }, { 'score' => { '$gte' => 90 } }]).pluck(:name)

users.update_many({ age: { '$lt' => 18 } }, '$set' => { 'minor' => true })
users.upsert({ name: 'Ann' }, '$inc' => { 'login_count' => 1 })

db.transaction do
  db[:orders].insert(user: 'Ann', total: 99)
  db[:users].update_one({ name: 'Ann' }, '$push' => { 'orders' => 'o-1' })
end # 一次落盘；块内抛错自动回滚

db.close

数据文件长什么样，人可以直接编辑（改完下次读取自动重载）：

{
  "users": [
    { "name": "Ann", "age": 31, "_id": "5f3a…" }
  ]
}

• 单文件：顶层对象，键 = 集合名，值 = 文档数组。备份就是复制文件。
• 内存权威：读写都走内存；写操作后默认即时落盘（autoflush: true）。
• 原子落盘：同目录临时文件 → fsync → rename → 目录 fsync。任何时刻磁盘上只有完整的旧文件或新文件，绝无半截 JSON。
• _id：文档唯一键；插入时缺省自动生成 24 位 hex。可自定义（insert(_id: 'u1', …)），不可变更。
• 键与值的字符串化：symbol 键/值入库时深度转为字符串（name: :active ↔ "active"），保证 JSON 往返一致；查询过滤器里的 symbol 自动同样处理。

链式：where(...).where(...)（AND 叠加）order / limit / offset / pluck / first / count / exists?，惰性执行，枚举时取快照。

字段名支持点路径，含数组下标：'profile.city'、'tags.0'。

操作符支持两种写法：字符串 '$gt' 与裸符号 gt:（age: { gte: 18 }）。显式 $ 前缀写错操作符名会抛错；裸符号不在操作符表内则按数据 Hash 等值匹配。

排序对混合类型安全（false < true < 数值 < 字符串 < 数组 < 对象 < nil，nil/缺失垫底；平键保持插入序）。order(:name)、order(:age, :desc)、order(age: :desc, name: :asc) 均可，多次调用逐键追加。

update_one / update_many（批量）、update(id, changes)（按 _id）、upsert(filter, changes)（无则插：过滤条件 ⊕ 更新集合成文档）。操作符中途失败时该次调用全部不落地（先在副本上应用成功再写入）。

删除：delete(id) / delete_one(filter) / delete_many(filter) / clear!；db.drop(:name) 连集合一起删。

• JsonDb.open(path, pretty: true, autoflush: true)；pretty: false 出紧凑 JSON。
• 批量写入：JsonDb.open(path, autoflush: false) 后手动 db.flush；或用 db.transaction { … }（块内禁即时落盘，正常结束一次落盘，抛错整体回滚到事务前）。
• db.close 落盘并封存实例；db.reload! 丢弃内存改动强制重读。
• 外部改动：无未落盘改动时，下次读取自动察觉（mtime+size）并重载——手编文件、多进程读都新鲜。本地有未落盘改动且文件又被他方改写时，打印一次警告，落盘以本地为准。

• 单进程多线程：安全（Monitor 串行化，含 fork 前后语义）。
• 跨进程：写经数据文件旁的 <path>.lock flock 串行化，落盘原子；多进程并发写为文件级 last-write-wins，不合并——两进程同时各自写不同文档，后落盘者覆盖整文件。写者之间靠 mtime 重载尽量累积对方改动，但读-改-写竞态窗口内的丢失不设防。需要强一致多写，请单写者或外部协调（这也是同类库 lowdb/TinyDB 的共同边界）。
• 读永远一致：任何进程任何时刻读文件，只会看到完整的某一版。

• 文档只支持 JSON 原生类型（Hash/Array/String/Numeric/Boolean/nil）；Date/Time 等请自行转字符串。symbol 自动转字符串。
• 无索引：每次查询全集合扫描。万级文档以下舒适，十万级请上真数据库。
• $elemMatch、投影（projection）、聚合：暂无，见需再加。

复现：rake bench（微基准 ips）/ rake bench[scale]（规模表）。脚本在 benchmark/，数据为本机实测（Ruby 4.0.6, arm64 M 系列 MacBook，2026-10）。

缩放表（预填后 autoflush 关闭测内存操作，flush 单列；查询无索引全扫描）：

单操作亮点（1 000 文档，微基准）：

读数要点（诚实边界）：

• 扫描吞吐约 50–60 万文档/秒（无索引线性扫，与集合规模基本无关的单文档成本 ~2–3 µs）
• 每次落盘 ≈ 1.9–2.2 ms（tempfile+fsync+rename+目录 fsync 的真实代价）；高频写建议 autoflush: false 批量 flush，或 transaction 合并
• update/delete 按过滤条件为全扫（未命中尤甚，上表 update 行即最坏情形）；按 _id 命中快
• 排序为比较器全排（20k 文档 ~350 ms），键已预计算（装饰-排序-去装饰）；跨类型安全比较是刻意设计，换取任意 schema 不抛错
• 万级文档舒适，十万级且高频查询请上真索引型数据库

# Gemfile（gem 名 jsondb-rb，require 路径 jsondb）
gem 'jsondb-rb', '~> 0.1'

gem install jsondb-rb   # 然后 require 'jsondb'

发版走 git tag（v*）触发 release.yml，经 rubygems OIDC trusted publishing 推送。

rake test   # 44 例：CRUD / 查询操作符 / 持久化 / 事务 / 多线程 / 多进程 fork 并发

Ruby >= 3.1，纯标准库。