Metadata-Version: 2.4
Name: mathdb
Version: 0.1.1
Summary: 基于 Polars/Pandas 的持久化内存数据库，支持 WAL 和快照恢复
Project-URL: Homepage, https://github.com/mathdb/mathdb
Project-URL: Repository, https://github.com/mathdb/mathdb
Project-URL: Documentation, https://github.com/mathdb/mathdb#readme
Project-URL: Issues, https://github.com/mathdb/mathdb/issues
Author: BethJiang
License-Expression: MIT
Keywords: database,memory,persistence,polars,snapshot,wal
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: polars>=0.20.0
Requires-Dist: pyarrow>=14.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# MathDB

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

## 特性

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

## 安装

```bash
pip install mathdb
```

## 快速开始

```python
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()} 条记录")
```

## 配置选项

```python
# 自定义刷盘间隔（默认 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 + 快照             │
              └───────────────────────────────┘
```

## 开发

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

# 运行测试
pytest

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

## 许可证

MIT
