MathDB

基于 Polars/Pandas 的持久化内存数据库，支持 WAL 和快照恢复。

特性

• 🚀 高性能: 直接从内存中使用 Polars DataFrame 读取
• 💾 持久化: WAL 段 + 周期性快照用于崩溃恢复
• ⏱️ 近零丢失: 最大数据丢失窗口 ≤ 3 秒
• 🔒 并发控制: 单写入者 + 多读者 (RWLock)
• 🔄 完整 CRUD: 支持 Insert、Update、Delete、Upsert 操作

安装

pip install mathdb

快速开始

from mathdb import Table, TableSchema, ColumnDef

# 定义表结构
schema = TableSchema(
    name="users",
    columns=[
        ColumnDef("id", "Int64", primary_key=True),
        ColumnDef("name", "Utf8"),
        ColumnDef("age", "Int32"),
    ]
)

# 创建持久化表
with Table(schema, data_dir="./data") as table:
    # CRUD 操作
    table.insert({"id": 1, "name": "Alice", "age": 30})
    table.update(pk=1, row={"id": 1, "name": "Alice", "age": 31})
    table.upsert({"id": 2, "name": "Bob", "age": 25})
    table.delete(pk=1)

    # 使用原生 Polars API 查询
    import polars as pl

    df = table.to_dataframe()
    result = df.filter(pl.col("age") > 20).group_by("name").count()

# 重新打开时自动恢复数据
with Table(schema, data_dir="./data") as table:
    print(f"恢复了 {table.count()} 条记录")

配置选项

# 自定义刷盘间隔（默认 3 秒）
table = Table(schema, data_dir="./data", flush_interval=1.0)

# 禁用自动刷盘（手动控制）
table = Table(schema, data_dir="./data", flush_interval=0)
table.insert({"id": 1, "name": "Alice", "age": 30})
table.flush()  # 手动刷盘

架构

┌─────────────────────────────────────────────────────────────┐
│                          Table                            │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │   Reader    │  │ WriterActor  │  │ Flusher/Snapshotter│  │
│  └──────┬──────┘  └──────┬───────┘  └─────────┬─────────┘   │
│         │                │                    │             │
│         ▼                ▼                    ▼             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │            CurrentTable (Polars DataFrame)          │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │   磁盘: WAL + 快照             │
              └───────────────────────────────┘

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=mathdb --cov-report=html

许可证

MIT