sqlite-bytes-store

sqlite-bytes-store is a small, typed, dependency-free MutableMapping for bytes keys and bytes values, backed by SQLite.

It is meant for write-heavy byte stores where a plain dict is too temporary, shelve is the wrong shape, and the stdlib dbm.sqlite3 backend spends too much time committing individual updates.

Install

python -m pip install sqlite-bytes-store

uv add sqlite-bytes-store

Usage

from sqlite_bytes_store import SQLiteBytesStore

with SQLiteBytesStore("cache.sqlite") as store:
    store[b"alpha"] = b"payload"
    store[b"beta"] = b"another payload"

    assert store[b"alpha"] == b"payload"
    assert store.get(b"missing", b"default") == b"default"
    assert b"beta" in store

    store.commit()

The store implements collections.abc.MutableMapping[bytes, bytes], so the usual mapping operations work: len(store), iteration over keys, get, assignment, deletion, clear, and membership checks.

Useful options:

SQLiteBytesStore(
    "positions.sqlite",
    reset=False,              # remove an existing database before opening
    table_name="items",       # validated SQLite identifier
    commit_interval=10_000,   # writes between automatic commits
)

close() commits pending writes and closes the connection. sync() is an alias for commit() for compatibility with other mapping-store APIs.

Why It Is Fast

The table is deliberately simple:

• key BLOB PRIMARY KEY
• value BLOB NOT NULL
• WITHOUT ROWID
• WAL journal mode
• synchronous=NORMAL
• batched commits

That makes it a focused persistence layer for byte-to-byte data, not a general SQLite abstraction.

Benchmark

The repository includes a reproducible benchmark:

uv run --python 3.14 python benchmarks/benchmark_stores.py --items 2000 --repeats 3

dbm.sqlite3 was added in Python 3.13; the package itself only requires Python 3.10 or newer.

Results from this machine:

• Date: 2026-06-02
• Python: CPython 3.14.2
• SQLite: 3.50.4
• Platform: Linux 5.15.161btrfs, Intel Core i5-7200U CPU @ 2.50GHz
• Workload: 2,000 pre-generated 16-byte keys, 128-byte values, 3 fresh databases
• Metric: median time; speedup is relative to dbm.sqlite3 total time

The read-only path is in the same ballpark here; the big win is the write-heavy path where SQLiteBytesStore batches commits.

Development

uv sync --group dev --extra docs
uv run ruff format .
uv run ruff check .
uv run python -m pytest
uv build --clear
uv run twine check dist/*

License

sqlite-bytes-store is distributed under the GPL-3.0-or-later license.