Shelfdb Usage

ShelfDB usage

Use ShelfDB in one of two modes:

• Remote client/server: start shelfdb server, connect with shelfdb.client.Client, open async transactions, and end remote reads or writes with await ...query().
• Local direct DB: open shelfdb.shelf.DB(...), use local transactions, and run queries directly without .query().

Core rules

• Prefer the remote client flow for application code and flexible deployment.
• Use local DB access only when the process can open the database directly.
• For remote usage, remember: builder methods do nothing until await .query().
• For local usage, do not add .query(); local operations run directly.
• Use client.transaction() for reads and client.transaction(write=True) for mutations.
• Close remote clients with await client.close().
• Start the server with shelfdb server; default URL is tcp://127.0.0.1:31337 and default DB path is db.

Read the bundled docs for details

Read the skill-local docs under ai-skill/shelfdb-usage/docs/ as needed:

• docs/index.md — overview, fit, and navigation
• docs/usage/installation.md — install and CLI verification
• docs/usage/server.md — server startup and URL formats
• docs/usage/remote.md — async client usage and .query() behavior
• docs/usage/local.md — direct local DB usage
• docs/api/index.md — API reference index
• docs/api/client.md — remote client API
• docs/api/local.md — local DB API
• docs/api/cli.md — CLI reference

Practical guidance

• If the user asks for app code that talks to a running ShelfDB instance, use the remote client API.
• If the user asks for simple in-process storage examples, use DB(...) and local transactions.
• If the user is confused about why nothing happens remotely, check whether .query() is missing.
• If the user needs a server command example, prefer shelfdb server --db-path ./db --url tcp://127.0.0.1:31337 unless they need a Unix socket.

Source: keenlycode/shelfdb — distributed by TomeVault.