Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

Examples

Working samples for every language that embeds the SQLRite engine.

Phase 5 lands these incrementally — each sub-phase fills in one language. The directory layout is designed so new SDKs slot in cleanly without disturbing the existing ones.

Language Status SDK published Directory
Rust ✅ Phase 5a crates.io as sqlrite-engine (Phase 6d) rust/
C (FFI) ✅ Phase 5b GitHub Releases (Phase 6d) c/
Python ✅ Phase 5c PyPI as sqlrite (Phase 6f) python/
Node.js ✅ Phase 5d npm as @joaoh82/sqlrite (Phase 6g) nodejs/
Go ✅ Phase 5e Go modules (Phase 6i) go/
WASM ✅ Phase 5g npm as @joaoh82/sqlrite-wasm (Phase 6h) wasm/
MCP ✅ Phase 7h crates.io as sqlrite-mcp + per-platform binary tarballs (no examples/ subdir — see docs/mcp.md for the full quickstart with Claude Code / Cursor / mcp-inspector wiring snippets)

See docs/roadmap.md for what each sub-phase delivers.

End-to-end example apps

Beyond the per-SDK quick-start tours above, the SQLR-38 umbrella tracks longer, opinionated example apps that exercise SQLRite end-to-end in real-world shapes:

App Language / SDK What it shows Directory
LLM agent with persistent memory Python Vector + lexical recall, fact extraction, summaries — all in one .sqlrite file python-agent/
Chat with your notes (MCP) Node.js Markdown → SQLRite hybrid retrieval, served to Claude Desktop via sqlrite-mcp --read-only nodejs-notes/
Local-first journaling Tauri 2 + Svelte 5 Markdown daily notes in one .sqlrite file, BM25 full-text search, "ask my journal" natural-language SQL desktop-journal/
Browser SQL playground WASM The full engine in WebAssembly — SQL editor, sample datasets, HNSW vector search, all in a browser tab. Live at sqlritedb.com/playground wasm-playground/
Edge / IoT event collector Go HTTP collector + background uploader writing one .sqlrite buffer concurrently via BEGIN CONCURRENT; durable-buffer-for-unreliable-networks shape, with measured throughput go-collector/

Running the Rust quickstart

cargo run --example quickstart

Walks through opening an in-memory Connection, creating a table, inserting rows, preparing a SELECT, iterating typed Row values, and running a BEGIN / ROLLBACK block. About 50 lines with comments — read rust/quickstart.rs first.

Running the hybrid-retrieval example (Phase 8d)

cargo run --example hybrid-retrieval

Combines BM25 lexical scoring (Phase 8b) with vector cosine distance (Phase 7d) in a single ORDER BY, showing where each ranking shape wins on the same corpus. Pre-baked vectors keep the example self-contained — no embedding-model dependency. Read hybrid-retrieval/README.md for the narrative.

Running the concurrent-writers example (Phase 11.12)

cargo run --example concurrent_writers

End-to-end BEGIN CONCURRENT demo with two sibling Connection handles minted via Connection::connect. Two scenarios: disjoint-row commits both succeed; interleaved same-row commits resolve with one winner and one SQLRiteError::Busy → retry. Reads from rust/concurrent_writers.rs; the canonical conceptual walkthrough lives at docs/concurrent-writes.md.

Running the C sample

cd examples/c && make run

Builds the Rust cdylib (libsqlrite_c.{so,dylib,dll}) and compiles c/hello.c against its generated header. The binary embeds an rpath pointing at the cargo target dir so ./hello runs without any LD_LIBRARY_PATH / DYLD_* dance. Covers open → execute → query → step → column accessors + an explicit transaction block.

See the top of c/hello.c for the ownership rules that apply to every non-Rust binding (opaque handles, sqlrite_free_string for text columns, thread-local sqlrite_last_error).

Running the Python sample

# One-time: install maturin and build the wheel into your Python env.
pip install maturin
cd sdk/python && maturin develop

# Then from the repo root:
python examples/python/hello.py

Mirrors the Rust quickstart shape via the DB-API: sqlrite.connect(":memory:") → cursor.execute → iterate tuples, plus a BEGIN/ROLLBACK block. See python/hello.py and sdk/python/README.md for the full API tour.

Running the Python LLM agent (SQLR-39)

cd examples/python-agent
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
python -m sqlrite_agent          # works offline; no API key required

A full CLI chat agent whose long-term memory is one .sqlrite file. Embeds each turn, hybrid-searches over past messages and a structured facts table on every recall, and survives process restarts. Read python-agent/README.md for the demo script and architecture diagram.

Running the Node.js notes assistant (SQLR-40)

cd examples/nodejs-notes
npm install
node bin/sqlrite-notes.mjs init ~/Documents/notes

Ingests a folder of markdown notes into a notes.sqlrite file with HNSW + BM25 indexes, then sqlrite-notes serve wraps sqlrite-mcp --read-only so Claude Desktop / any MCP client can bm25_search / vector_search / query / ask your local notes directly — no cloud sync, no third-party indexer. Default embedder is fully offline (deterministic hash bag-of-words); flip to --embedder openai with OPENAI_API_KEY set for real semantic recall. Read nodejs-notes/README.md for the Claude Desktop config snippet and the hybrid-retrieval SQL walkthrough.

Running the Node.js sample

# One-time: build the .node binding.
cd sdk/nodejs
npm install
npm run build

# Then from the repo root:
node examples/nodejs/hello.mjs

Mirrors the better-sqlite3 shape: new Database(":memory:") → db.prepare(sql).all() returning row objects, plus a BEGIN/ROLLBACK block with the inTransaction getter. See nodejs/hello.mjs and sdk/nodejs/README.md for the full API tour.

Running the Go sample

# One-time: build the C shared library (the Go driver is cgo-linked).
cargo build --release -p sqlrite-ffi

# Then:
cd examples/go
go run hello.go

Uses the standard library's database/sql API — sql.Open("sqlrite", ":memory:") → db.Query + rows.Scan(&id, &name) into typed Go vars, plus a db.Begin() / tx.Rollback() block. See go/hello.go and sdk/go/README.md for the full API tour.

Running the WASM demo

cd examples/wasm
make          # builds sdk/wasm via wasm-pack, then starts a local server

Opens http://localhost:8080 with a tiny SQL console embedded in a single HTML page — CREATE TABLE / INSERT / SELECT all run client-side via the compiled WebAssembly module. No server backend.

The demo pre-fills the textarea with a users table + three inserts + a SELECT ... ORDER BY age DESC. Hit Run and you'll see the JSON result appear in the output pane. Reset DB drops the handle and spins up a fresh in-memory DB.

See wasm/index.html and sdk/wasm/README.md for the full API tour and build options (--target web / bundler / nodejs).

Design notes

  • One shape across languages. Every SDK exposes Connection, prepare, execute, and typed Row access. The language-specific file in each subdir shows the same CRUD + transaction walkthrough, so users picking up a new binding recognize the surface immediately.
  • No build step required for end users. Phase 6 ships prebuilt wheels (Python), .node binaries (Node.js), libsqlrite.{so,dylib,dll} (for Go / C), and @joaoh82/sqlrite-wasm (browser) — no "install Rust first" tax.
  • Examples track the engine. Each sub-phase's commit lands the example alongside the binding itself, so the sample always works against the current library shape.