Skip to content

buckethead.interfaces

Typed views on the in-memory SQLite. Interface is the ABC; KVStore is the first concrete implementation.

buckethead.interfaces.base

buckethead.interfaces.base

Abstract base class for typed views on BucketHead state.

An Interface owns one or more SQLite tables (and optionally an R2 prefix) and is constructed by BucketSQLite.start() after the snapshot is restored. Schema bootstrap is idempotent so the tables exist whether or not they were present in the restored snapshot.

First concrete implementation: buckethead.interfaces.kv.KVStore. Future examples (not implemented yet) include NumPy array storage and Pandas DataFrame storage, both of which will also inherit from Interface.

Interface 

Interface(
    conn: Connection,
    bucket_client: BucketClient | None = None,
)

Bases: ABC

Base class for typed interfaces attached to a BucketSQLite instance.

Subclasses implement _init_schema() to create the tables they own using CREATE TABLE IF NOT EXISTS. The base class calls it during construction so every subclass gets the schema up before its public methods are ever invoked.

Reserved table-name convention: Interface subclasses should prefix their tables with bh_ so user tables never collide. KVStore uses bh_kv; future Interface subclasses should follow suit. (FileStore's filestore table predates this convention and is grandfathered in.)

Source code in src/buckethead/interfaces/base.py 
37
38
39
40
41
42
43
44
def __init__(
    self,
    conn: sqlite3.Connection,
    bucket_client: BucketClient | None = None,
) -> None:
    self._conn = conn
    self._bucket = bucket_client
    self._init_schema()

buckethead.interfaces.kv

buckethead.interfaces.kv

KVStore: a simple string key-value interface with an explicit bytes escape hatch.

Canonical API is str in, str out — what most callers want. For binary payloads (small pickles, protobufs, etc.), use the set_bytes / get_bytes methods. Both APIs share a single bh_kv.value BLOB column under the hood.

Values are stored inline in SQLite — keep individual values small (under roughly 1 MB each). For larger values, use FileStore.

Supports the standard dict protocol (__getitem__, __setitem__, __delitem__, __contains__, __len__) in its string form.

Gotcha: if you store a value via set_bytes with non-UTF-8 bytes and then retrieve via get(), you'll get UnicodeDecodeError. Retrieve via get_bytes in that case. The error message tells you what went wrong, but the split API makes this easy to avoid.