sqlite-bytes-store 0.1.0

Fast SQLite-backed mutable mapping for bytes keys and values.

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

Implementation	Insert median	Read median	Total median	Speedup	Disk
SQLiteBytesStore	0.0306s	0.0205s	0.0537s	92.73x	352.0 KiB
dbm.sqlite3	4.9745s	0.0103s	4.9844s	1.00x	372.0 KiB

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.