README.md

shelfdb

Tiny LMDB-backed shelf database utilities.

Development

Install development dependencies:

uv sync --dev

Serve the docs locally:

uv run python -m dev docs serve --port 9001 --livereload

Publish the docs with mike to the docs branch:

uv run python -m dev docs publish

Override the publish target when needed:

uv run python -m dev docs publish --publish-version 2.1.0rc1 --alias latest --branch docs --remote origin

Server

Run the protocol server:

shelfdb server

Run the protocol server on a custom address:

shelfdb server --url "tcp://0.0.0.0:17001" --db-path ./db

Client

Connect a client:

from shelfdb.client import Client

client = await Client.connect("tcp://127.0.0.1:31337")

Unix sockets also work:

from shelfdb.client import Client

client = await Client.connect("unix:///tmp/shelfdb.sock")

Example

from shelfdb.client import Client

client = await Client.connect("tcp://127.0.0.1:31337")

try:
    async with client.transaction() as tx:
        users = tx.shelf("users")

        count = await users.count().query()
        alice = await users.key("alice").item().query()
        admins = await users.filter(
            lambda item: item.value["role"] == "admin"
        ).sort(reverse=True).query()

    async with client.transaction(write=True) as tx:
        users = tx.shelf("users")

        await users.put("eve", {"role": "user"}).query()
        await users.key("eve").update(
            lambda item: {**item.value, "role": "admin"}
        ).query()
finally:
    await client.close()