FlaxKV2 是一个面向 Python 的持久化键值存储库。使用熟悉的 db[key] = value 保存数据， 支持字典、列表、NumPy 数组和可选的 Pandas DataFrame。

适合本地缓存、数据处理的中间结果、任务状态和数组存储。本地模式直接读写 LMDB 文件， 多个进程可共享同一数据库；跨机器访问时，可以启用 ZeroMQ 服务。

快速开始

需要 Python 3.10 或更新版本。

pip install flaxkv2

import numpy as np
from flaxkv2 import FlaxKV

with FlaxKV("app", "./data") as db:
    db["config"] = {"retries": 3, "timeout": 30}
    db["embedding"] = np.array([0.1, 0.2, 0.3], dtype=np.float32)

# 重新打开，继续读取之前保存的数据。
with FlaxKV("app", "./data") as db:
    print(db["config"]["retries"])   # 3
    print(db["embedding"].shape)     # (3,)

with 管理数据库的生命周期，退出时关闭数据库并刷新写缓冲。

按需安装扩展：

pip install 'flaxkv2[pandas]'     # Pandas DataFrame
pip install 'flaxkv2[vector]'     # hnswlib 向量索引
pip install 'flaxkv2[migration]'  # 旧版 LevelDB 数据迁移

flaxkv2[full] 包含 Pandas 和向量索引；Web UI 是独立包，见 Inspector 指南。

核心能力

批量读写与范围迭代

from flaxkv2 import FlaxKV

with FlaxKV("users", "./data") as db:
    db.update({"user:alice": {"score": 95}, "user:bob": {"score": 87}})
    scores = db.batch_get(["user:alice", "user:bob"])

    for key, value in db.items_iter(prefix="user:"):
        print(key, value)

迭代器支持 prefix、start、stop 和 reverse。使用 *_iter() 可避免一次加载全部值； 普通序列化模式下仍会收集键集合。排序和范围比较基于编码后的键字节，详见 遍历与一致性。

TTL 与嵌套更新

from flaxkv2 import FlaxKV

with FlaxKV("sessions", "./data", default_ttl=3600) as db:
    db["session:alice"] = {"role": "editor"}
    db.set_ttl("session:alice", 300)

with FlaxKV("settings", "./data", auto_nested=True) as db:
    db["server"] = {"host": "localhost", "port": 8080}
    db["server"]["port"] = 9000

auto_nested=True 让字段独立存储，适合频繁修改大型对象的局部内容；默认关闭。

跨 Sub-DB 事务

同名数据库的多个 sub_db 共享一个 LMDB 环境。可以在一个事务中完成条件判断和写入：

from flaxkv2 import FlaxKV, cross_db_txn

with (
    FlaxKV("service", "./data", sub_db="counters") as counters,
    FlaxKV("service", "./data", sub_db="grants") as grants,
):
    with cross_db_txn(counters, grants) as txn:
        used = txn.get(counters, "used", 0)
        if used < 10:
            txn.put(counters, "used", used + 1)
            txn.put(grants, f"slot:{used}", {"status": "reserved"})

本地字典的 pop / setdefault 也在单个事务内完成读写；远程版本不保证原子性。 事务内使用 txn 读写，不能跨 await 持有。大批量、可重放的事务可使用 atomic_txn， 详见事务与并发原语。

持久化数据结构

沿用相同的名称、路径和上下文管理方式：

from flaxkv2 import FlaxList

with FlaxList("events", "./data") as events:
    events.append({"type": "click", "user": "alice"})
    events.extend([{"type": "scroll"}, {"type": "submit"}])
    print(events[-1])

更多示例见数据结构指南。

远程访问

先在本机启动服务：

flaxkv2 run --port 5555 --data-dir ./data

再通过 URL 连接：

from flaxkv2 import FlaxKV

with FlaxKV("shared", "tcp://127.0.0.1:5555") as db:
    db["status"] = {"ready": True}
    print(db["status"])

服务默认监听回环地址。跨机器访问需设置 --host，并配置加密认证或可信隧道， 见密码认证指南。远程后端与本地后端的 事务和部分配置能力不同，不应直接互换这些保证。

Inspector 可以直接浏览本地数据库：

flaxkv2 inspect keys app --path ./data
flaxkv2 inspect get app config --path ./data
flaxkv2 inspect stats app --path ./data

性能与持久性

默认使用无缓存的 RawLmdbDict，LMDB 写事务提交时执行 fsync。 需要优化时，根据访问模式选择：

from flaxkv2 import CachedLmdbDict

with CachedLmdbDict(
    "cache", "./data", read_cache_size=10_000, enable_write_buffer=False
) as db:
    db["model:config"] = {"dimensions": 768}
    print(db["model:config"])

缓存容量按条目数计。FlaxKV 当前只传 read_cache_size 仍会附带写缓冲并发出 FutureWarning；仅需读缓存时使用上面的显式配置。读缓存会在检测到其他进程提交后失效。

开启写缓冲后，正常 close() 会刷新数据，进程崩溃仍会丢失未刷新的内容。 flush() 将缓冲写入 LMDB；sync() 在刷新后强制同步到磁盘。缓冲落盘失败时会抛出 FlushError 并保留缓冲数据。sync / metasync 是同一 LMDB 环境共享的配置， performance_profile 只设置 map_size 和 max_readers。

性能数字受硬件、文件系统、数据大小和缓存状态影响。使用仓库中的脚本在目标环境测量：

python tests/benchmarks/benchmark_core.py
python tests/benchmarks/benchmark_durability.py

更多配置见快速参考和缓存设计。

信任边界

复杂对象可能使用 pickle 编解码，只应读取可信来源的数据库。远程客户端默认 allow_pickle=False，需要 pickle 的值会被拒绝；只有所有写入方可信时才应开启。

文档

完整目录见 docs/README.md。

参与开发

安装、测试和提交说明见贡献指南。问题和功能建议可提交到 GitHub Issues。

FlaxKV2 基于 LMDB、py-lmdb 和 ZeroMQ，采用 Apache License 2.0。