Skip to content

Local database usage

Use DB when your code can access the LMDB environment directly.

This is optional. Prefer the client/server flow when you want a more flexible setup, especially over a Unix socket.

Open a database

from shelfdb.shelf import DB

with DB("./db") as db:
    ...

Write data

from shelfdb.shelf import DB

with DB("./db") as db:
    with db.transaction(write=True) as tx:
        users = tx.shelf("users")
        users.put("alice", {"role": "admin", "age": 30})
        users.put("bob", {"role": "user", "age": 25})

Read data

from shelfdb.shelf import DB

with DB("./db") as db:
    with db.transaction(write=False) as tx:
        users = tx.shelf("users")

        count = users.count()
        alice = users.key("alice").item()
        admins = list(users.filter(lambda item: item.value["role"] == "admin"))

        print(count)
        print(alice)
        print(admins)

Stored None values

None is a valid stored value, not a missing record. Since version 3.1.1, value-loading queries preserve it in .items(), .item(), filters, sorting, and updates:

from shelfdb.shelf import DB, Item

with DB("./db") as db:
    with db.transaction(write=True) as tx:
        tx.shelf("settings").put("optional", None)

    with db.transaction(write=False) as tx:
        settings = tx.shelf("settings")
        assert settings.key("optional").item() == Item("optional", None)
        assert settings.key("optional").exists() is True
        nulls = list(settings.filter(lambda item: item.value is None))

A missing key has .exists() == False; calling .item() on it raises ValueError. Callbacks must handle None if the selected values can contain it. Older releases may skip stored nulls when loading values; upgrading requires no storage migration.

Select keys by prefix

keys_prefix() is available starting with version 3.2.0.

Use literal prefixes to group records within one shelf:

with DB("./db") as db:
    with db.transaction(write=True) as tx:
        records = tx.shelf("records")
        records.put("user:alice", {"role": "admin"})
        records.put("user:bob", None)
        records.put("order:001", {"total": 100})

    with db.transaction(write=False) as tx:
        users = tx.shelf("records").keys_prefix("user:")
        items = list(users.items())
        reverse_keys = list(users.desc().keys())

The scan seeks directly to the prefix group in LMDB key order. Matching is case-sensitive with no Unicode normalization, globbing, or segment parsing: "user:1" also matches "user:10". .keys() yields Item(key, UNDEF), not bare strings. An empty prefix selects all keys; an overlength prefix selects none.

Prefix selection replaces earlier .key(), .keys_range(), or prefix selection; it does not intersect them. Direction and transforms are preserved, including when a selector is called after a filter or slice. For example, records.keys_range("a", "b").keys_prefix("user:") selects the "user:" group, not its intersection with ["a", "b").

Use .filter(), .slice(), .count(), .update(), or .delete() on the selected stream as usual. Prefix scans do not make value filters indexed or arbitrary sorting bounded. put() and put_many() remain direct shelf writes and do not restrict inserted keys to the selected prefix.

Query style

tx.shelf("users") returns a ShelfQuery, so you can chain selectors and transforms.

The transaction query syntax is a bit different from client usage: local queries run directly, while remote client usage ends with .query().

with DB("./db") as db:
    with db.transaction(write=False) as tx:
        users = tx.shelf("users")

        result = list(
            users
            .filter(lambda item: item.value["age"] >= 25)
            .sort(reverse=True)
            .slice(0, 2)
        )

Common local patterns:

  • users.key("alice").item()
  • users.key("alice").exists()
  • list(users.keys_range("bob", "d"))
  • list(users.items())
  • users.count()
  • users.key("alice").update(...)
  • users.key("alice").delete()