Metadata-Version: 2.4
Name: ferrumdb
Version: 0.1.2
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: maturin>=1.0 ; extra == 'dev'
Provides-Extra: dev
Summary: FerrumDB — Zero-setup embedded document database for Python. No server. No config. Just open a file and go.
Keywords: database,embedded,json,rust,key-value,document-store,local-first
Author-email: Muhammad Usman <muhammadusmangm@gmail.com>
Maintainer-email: Muhammad Usman <muhammadusmangm@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/MuhammadUsmanGM/FerrumDB/releases
Project-URL: Documentation, https://github.com/MuhammadUsmanGM/FerrumDB/tree/main/ferrumdb-python
Project-URL: Homepage, https://github.com/MuhammadUsmanGM/FerrumDB
Project-URL: Repository, https://github.com/MuhammadUsmanGM/FerrumDB

# FerrumDB Python Bindings

[![PyPI](https://img.shields.io/pypi/v/ferrumdb.svg)](https://pypi.org/project/ferrumdb/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/ferrumdb.svg)](https://pypi.org/project/ferrumdb/)
[![Python Versions](https://img.shields.io/pypi/pyversions/ferrumdb.svg)](https://pypi.org/project/ferrumdb/)

**FerrumDB** is a zero-setup embedded document database for Python, powered by Rust.

- 🔥 **Zero-setup** — no server, no config, just `open()`
- ⚡ **Rust-speed** — AOF writes, in-memory index for O(1) reads
- 🔐 **AES-256 Encrypted** — optional encryption at rest
- 📄 **Native JSON** — store any structured document
- 🔍 **Secondary Indexing** — query by JSON fields

## Installation

### From PyPI (recommended)

```bash
pip install ferrumdb
```

### From source (requires Rust toolchain + maturin)

```bash
# Install maturin
pip install maturin

# Clone and build
git clone https://github.com/MuhammadUsmanGM/FerrumDB.git
cd FerrumDB/ferrumdb-python
maturin develop --release
```

## Quick Start

```python
from ferrumdb import FerrumDB

# Zero-setup: creates myapp.db if it doesn't exist
db = FerrumDB.open("myapp.db")

# Store any JSON-serializable value
db.set("user:1", {"name": "alice", "role": "admin", "score": 99})
db.set("user:2", {"name": "bob", "role": "user", "score": 45})
db.set("counter", 42)

# Read back
user = db.get("user:1")
print(user)  # {"name": "alice", "role": "admin", "score": 99}

print(db.count())  # 3
print(db.keys())   # ["user:1", "user:2", "counter"]

# Delete
db.delete("counter")
```

## Secondary Indexing

Query by JSON field values in O(1) time:

```python
from ferrumdb import FerrumDB

db = FerrumDB.open("myapp.db")

# Add data
db.set("user:1", {"name": "alice", "role": "admin"})
db.set("user:2", {"name": "bob", "role": "user"})
db.set("user:3", {"name": "charlie", "role": "admin"})

# Create index on 'role' field
db.create_index("role")

# Query by indexed field
admins = db.find("role", '"admin"')
print(admins)  # ["user:1", "user:3"]
```

## API Reference

| Method | Description |
|--------|-------------|
| `FerrumDB.open(path)` | Open/create database at path |
| `db.set(key, value)` | Store any JSON-serializable value |
| `db.get(key)` | Retrieve value (returns `None` if not found) |
| `db.delete(key)` | Delete a key (returns `True` if existed) |
| `db.keys()` | List all keys |
| `db.count()` | Total number of entries |
| `db.create_index(field)` | Build secondary index on JSON field |
| `db.find(field, value)` | Query by indexed field (value as JSON string) |

## Limitations

FerrumDB makes specific trade-offs for simplicity and performance:

- **Entire index in RAM** — Best for databases <1GB
- **Single-writer only** — One process per database file
- **No range queries** — Only exact value matches on indexed fields
- **No nested field indexes** — Only top-level JSON fields supported

See [GitHub](https://github.com/MuhammadUsmanGM/FerrumDB) for full documentation.

## Ferrum Studio (Web Dashboard)

Browse your database visually using the standalone CLI:

```bash
cargo install ferrumdb-cli
ferrumdb web myapp.db
# http://localhost:7474
```

## License

MIT — See LICENSE for details.

