larzdb

A crash-safe, single-file, embedded document + key-value database. Zero dependencies.

SQLite's best idea — one file, no server, ACID — applied to JSON documents, in a few hundred lines of pure Python you can actually read.

from larzdb import Database

db = Database("app.larz")

# key-value
db.put("config:theme", "dark")
db.get("config:theme")                      # "dark"

# documents
users = db.collection("users")
uid = users.insert({"name": "Ada", "age": 36, "role": "admin"})
users.find({"role": "admin", "age": {"$gte": 18}})

# atomic, all-or-nothing, durable
with db.transaction() as tx:
    tx.put("balance:a", 40)
    tx.put("balance:b", 60)

Why

• Durable — every commit does flush() + os.fsync(); when a write returns, it's on disk.
• Crash-safe — a process killed mid-write leaves a torn tail frame that recovery simply drops. You never see half a transaction. (There are on-disk tests that truncate and corrupt the log, then reopen and assert integrity.)
• Atomic transactions — a whole batch of writes lands as one checksummed frame, or not at all.
• Real queries — Mongo-style filters ($gt, $in, $or, nested fields…) with optional in-memory secondary indexes.
• One file — trivial to back up, copy, or delete. compact() reclaims space from overwritten/deleted records.
• Zero dependencies — pure standard library. Nothing to install, nothing to compile, nothing to run as a server.

Install

pip install larzdb

How it stores data

larzdb is a log-structured store (the idea behind Bitcask and write-ahead logs). Every change is appended to the file as a self-describing, CRC-checked frame:

MAGIC(2) | payload_len(4) | crc32(4) | payload

Each frame is one committed transaction. On open, larzdb replays every valid frame to rebuild its in-memory index and stops at the first torn or CRC-failing frame — so an interrupted write can never corrupt earlier data. compact() rewrites the file with just the live records, atomically via a temp-file-and-rename so a crash during compaction leaves the original intact.

This makes writes fast (sequential appends) and recovery simple, at the cost of keeping the key index in memory — a great fit for embedded app state, caches, job queues, config, game saves, small services, and CLIs.

Documents & queries

users = db.collection("users")
users.insert({"name": "Ada", "age": 36, "role": "admin"})
users.insert({"name": "Bo",  "age": 17, "role": "user"})

users.find({"age": {"$gte": 18}})                       # ranges
users.find({"role": {"$in": ["admin", "user"]}})        # membership
users.find({"$or": [{"role": "admin"}, {"age": {"$lt": 18}}]})
users.find({"address.city": "Lagos"})                   # nested fields
users.find(sort="age", reverse=True, limit=10)          # sort + limit
users.find_one({"name": "Ada"})
users.count({"role": "admin"})
users.delete_many({"role": "user"})

Operators: $eq $ne $gt $gte $lt $lte $in $nin $exists $regex at the field level, $and $or $not for logic.

Indexes

users.ensure_index("role")            # in-memory; rebuilt from the log on open
users.find({"role": "admin"})         # now uses the index instead of scanning

Indexes live in memory and are reconstructed when you reopen the database, so they add nothing to the file and never get out of sync.

Transactions

with db.transaction() as tx:
    tx.put("a", 1)
    tx.delete("b")
    tx.collection("log").insert({"event": "transfer"})
# all three land atomically here — or none of them if the block raised

If the with block raises, nothing is written. Otherwise the whole batch is persisted as a single durable frame.

API at a glance

Scope & honesty

larzdb is an embedded, single-writer database (like SQLite), guarded by a file lock so two processes won't open the same file at once. It keeps the key index in RAM, so it's built for datasets that fit comfortably in memory — think megabytes-to-gigabytes of app data, not a multi-terabyte warehouse. It is not a networked/multi-master server and does not do SQL. For what it targets — local, durable, queryable state with zero operational overhead — that's the point.

Tests

python -m unittest discover -s tests -v      # 28 tests incl. crash recovery, zero deps

The Larz stack

Pure-Python, zero-dependency building blocks:

• larz — money-native web framework
• larzchain — from-scratch PoW blockchain
• larzmoney — exact, penny-perfect money
• larzcrypt — pure-Python cryptography toolkit
• larzdb — this database

License

MIT © larz-scripter