FerrumDB Python Bindings

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
• TTL Support — keys auto-expire after a configurable duration
• Built-in Dashboard — launch Ferrum Studio from your app

Installation

From PyPI (recommended)

pip install ferrumdb

From source (requires Rust toolchain + maturin)

pip install maturin
git clone https://github.com/MuhammadUsmanGM/FerrumDB.git
cd FerrumDB/ferrumdb-python
maturin develop --release

Quick Start

from ferrumdb import FerrumDB, Transaction

# 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})

# TTL — auto-expires after 60 seconds
db.set_ex("session:abc", {"token": "xyz"}, 60)

# Read back (returns native Python dict!)
user = db.get("user:1")
print(user)  # {'name': 'alice', 'role': 'admin', 'score': 99}

print(db.count())  # 2
print(db.keys())   # ['user:1', 'user:2']

# Key existence check (O(1), no disk read)
if db.exists("user:1"):
    print("User exists!")

# Prefix scanning
user_keys = db.keys_with_prefix("user:")
print(user_keys)  # ['user:1', 'user:2']

# Database statistics
stats = db.stats()
print(f"Keys: {stats['key_count']}, Disk: {stats['disk_size_bytes']} bytes")

# Delete
db.delete("user:2")

Encryption

Open a database with AES-256-GCM encryption at rest:

db = FerrumDB.open("secure.db", encryption_key="my_super_secret_key_32_bytes_!!?")
db.set("secret", {"classified": True})

The key must be exactly 32 characters.

Secondary Indexing

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

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

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

db.create_index("role")
admins = db.find("role", '"admin"')
print(admins)  # ["user:1", "user:3"]

Transactions

tx = Transaction()
tx.set("key1", {"value": 1})
tx.set_ex("cache:temp", {"data": 123}, 300)  # TTL in transactions too
tx.delete("old_key")
db.commit(tx)  # all-or-nothing

Ferrum Studio (Web Dashboard)

Launch the built-in web dashboard directly from your app:

db = FerrumDB.open("myapp.db")
db.start_studio(7474)  # http://localhost:7474

Browse keys, inspect values, set/delete entries, and view real-time metrics — no extra tools needed.

API Reference

Transaction

Limitations

• 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

What's New in v0.2.0

• Native Python dicts — get() now returns Python dicts instead of JSON strings
• CRC32 checksums — Early corruption detection with clear error messages
• Encrypted file caching — O(1) reads after first access (was O(n) on every read)
• New API methods: exists(), stats(), keys_with_prefix(), export_json(), import_json()
• Auto-compaction — Automatic dead data cleanup when threshold is exceeded

See GitHub for full documentation.

License

MIT — See LICENSE for details.