Metadata-Version: 2.4
Name: sqlite-bytes-store
Version: 0.1.0
Summary: Fast SQLite-backed mutable mapping for bytes keys and values.
Keywords: bytes,database,dbm,key-value store,sqlite
Author: Moritz R. Schäfer
Author-email: Moritz R. Schäfer <moritz.schaefer-f91@rub.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Dist: pdoc>=16 ; extra == 'docs'
Maintainer: Moritz R. Schäfer
Maintainer-email: Moritz R. Schäfer <moritz.schaefer-f91@rub.de>
Requires-Python: >=3.10
Project-URL: Repository, https://gitlab.com/M0M097/sqlite-bytes-store
Project-URL: Documentation, https://sqlite-bytes-store-f4d3d6.gitlab.io/
Project-URL: Issues, https://gitlab.com/M0M097/sqlite-bytes-store/-/issues
Provides-Extra: docs
Description-Content-Type: text/markdown

# 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

```bash
python -m pip install sqlite-bytes-store
```

```bash
uv add sqlite-bytes-store
```

## Usage

```python
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:

```python
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:

```bash
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

```bash
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.
