Python rocksdb 的 Python 封装

python-rocksdb是当前最稳定、文档最全、维护最活跃的rocksdb python封装，pypi上的rocksdb包已废弃，安装或导入会失败。

rocksdbs Python 封装到底该选 python-rocksdb 还是 rocksdb

直接说结论：python-rocksdb 是当前最稳定、文档最全、维护最活跃的封装，rocksdb（PyPI 上那个仅 10 行 setup.py 的包）早已废弃，安装会失败或导入报 ModuleNotFoundError。

常见错误现象：pip install rocksdb 成功但 import rocksdb 失败；或者 pip install python-rocksdb 报编译错误被误以为“不支持”。

• python-rocksdb 绑定的是 RocksDB C++ 6.x+，需本地有 C++11 编译器和 cmake；macos 用户常卡在 clang: error: unsupported option '-fopenmp'
• windows 用户必须用 visual studio 2019+ 构建，MinGW 不支持；建议直接用预编译 wheel：pip install python-rocksdb --only-binary=python-rocksdb
• 它不兼容 PyPy；如果项目跑在 PyPy 上，这条路走不通，得换存储方案

初始化 DB 时路径权限和锁冲突怎么避免

不是所有路径都能开库——尤其在容器或 CI 环境里，RocksDB 默认启用 create_if_missing=True，但若父目录不可写，会静默失败或抛出模糊的 IOError；更隐蔽的是已有进程占着 LOCK 文件导致 IOError: Unable to lock file。

• 务必确保传入的路径是**绝对路径**，相对路径在 daemon 或多进程下极易错位；推荐用 os.path.abspath("data/db")
• 检查 LOCK 文件是否存在且未被占用：lsof -i | grep LOCK（linux/macOS），或直接删掉旧 LOCK（仅限开发调试，生产环境必须确认无其他实例在读写）
• 如需多进程只读访问，显式设 read_only=True，否则即使不写也会尝试加锁

put() 和 write() 的性能差异在哪

简单存一个 key-value？用 put() 没问题。但批量写入（比如万级数据导入），直接循环 put() 是最慢的选择——每次调用都触发一次 WAL flush 和可能的 compaction 触发。

立即学习“Python免费学习笔记（深入）”；

• 用 write() + Writebatch：先 batch = db.write_batch()，再 batch.put(k, v) 多次，最后 db.write(batch) 一次提交
• 默认 WriteBatch 不开启 sync，如需强持久化，构造时传 sync=True，但会明显降速
• 注意：write_batch() 返回的对象不能跨线程复用；每个线程应新建自己的 batch

字符串 key/value 编码容易踩的坑

python-rocksdb 底层只认 bytes，Python 3 的 str 默认是 Unicode，直接传会报 TypeError: key must be bytes，但错误信息不提示怎么修。

• 统一用 .encode("utf-8") 转 key 和 value，别依赖系统默认编码；db.put(b"key", b"value") 安全，db.put("key", "value") 必炸
• 反序列化时记得 .decode("utf-8")，尤其从 iter() 遍历时，所有 key 和 value 都是 bytes
• 如果存的是 msgpack / pickle 数据，也得先 bytes 化，别漏掉 encode 步骤

真正麻烦的是混合类型场景：比如 key 是 int，有人会 str(i).encode()，但排序行为就和原生 int 不一致了；这时候要么固定长度字节编码（i.to_bytes(4, "big")），要么接受字符串序。