SQLRite: an embedded database written in Rust to learn how SQLite works

A crate named sqlrite-engine that imports as sqlrite

SQLRite, also called Rust-SQLite, is a simple embedded database modelled off SQLite but developed with Rust, and the README states the goal plainly: to get a better understanding of database internals by building one, with a Feynman quote about not understanding what you cannot create. That framing is the first thing to weigh, because it tells you what the project optimises for.

The packaging has a wrinkle that will bite you the first time you add the dependency. The crate is published on crates.io as sqlrite-engine, because the name sqlrite was already taken by an unrelated project, a RAG oriented SQLite wrapper. The library target keeps the name sqlrite, so downstream Rust code still writes use sqlrite::Database, and only the cargo add line and the dependency declaration change.

[dependencies]
sqlrite-engine = "0.2"
# then in code: use sqlrite::{Database, …};

Any workspace member that depends on the engine uses the package key so the import name stays sqlrite internally, which is the same trick that keeps the internal code readable. The manifest also pins edition 2024 with a rust-version of 1.85, and the description in the manifest is a light version of SQLite developed with Rust.

The repository is a Cargo workspace with the engine at the root, plus a desktop Tauri app, the desktop journal example's Tauri crate, the C FFI shim, the ask and MCP crates, the Python and Node.js SDKs, and a benchmarks crate. The root package doubles as the workspace root's own package for historical compatibility, since scripts assume that cargo build at the repository root produces the REPL binary.

A series of posts that build the engine in public

The project publishes a written series alongside the code, and the four posts map closely onto the structure of the engine. Part 0 is an overview. Part 1 covers understanding SQLite and setting up a CLI application and REPL. Part 2 is the SQL statement and meta command parser with error handling, and Part 3 is about the B-Tree and its role in database design.

That ordering is the design of the project made visible. A parser first, then the storage engine underneath it, which is the reverse of how most people meet a database, through the SQL surface. The README also carries the SQLite architecture diagram, and there is an asciinema recording of CREATE TABLE and INSERT statements working in the REPL, so the intended first experience is typing SQL at a prompt.

The design and discussion material lives in a separate repository, sqlrite/design, and there is a Discord server for talking about databases. The API documentation is published on docs.rs for sqlrite-engine, and the project website plus the getting started material is a Next.js 15 site with Tailwind v4 in the web/ directory, previewed locally with npm install and npm run dev and deployable to Vercel. The repository also carries an AGENTS.md, a CLAUDE.md, a MAINTAINERS file, a rust-toolchain.toml and a code of conduct.

An MCP server gives an agent seven tools over one file

The sqlrite-mcp crate exposes a SQLRite database as a Model Context Protocol stdio server. You spawn it from any MCP client, with Claude Code, Cursor and mcp-inspector named, and the agent gets seven tools: list_tables, describe_table, query, execute, schema_dump, vector_search, and ask for natural language to SQL, all without custom integration code.

cargo install sqlrite-mcp

Per platform prebuilt binaries are also published in the latest release, for Linux x86_64 and aarch64, macOS aarch64 and Windows x86_64. The wiring into Claude Code is a JSON block in the configuration file.

{
  "mcpServers": {
    "sqlrite": {
      "command": "sqlrite-mcp",
      "args": ["/absolute/path/to/your.sqlrite"],
      "env": { "SQLRITE_LLM_API_KEY": "sk-ant-…" }
    }
  }
}

The read-only flag is the detail to notice. Passing --read-only opens the database with a shared lock and hides the execute tool, so an agent can inspect a file without being able to change it. The environment variable carries the key for the provider behind the ask tool, and the remaining six tools are documented in docs/mcp.md.

This is the part of the project that has a life of its own beyond the database engine, because a database you can hand to an agent is a different object from a database you query yourself, and the read-only mode is the sensible default for that use case.

The desktop app, the FFI shim and the SDKs around the engine

A Tauri 2.0 and Svelte 5 desktop GUI ships alongside the REPL, in the desktop/ directory with its own documentation, and prebuilt installers are published for Linux x86_64 as AppImage, deb and rpm, for macOS Apple Silicon as dmg and app tarball, and for Windows x86_64 as msi and NSIS exe. The readme is explicit that the installers are unsigned until a later phase wires up code signing certificates, and it spells out the first launch friction: a quarantine attribute to strip on macOS, a SmartScreen override on Windows, and chmod +x on the AppImage. The macOS note is worth reading carefully, because the damaged message is a Gatekeeper path triggered by a quarantined ad-hoc signature rather than a broken application. From source, the desktop app is built with npm install and npm run tauri dev, and the interface has a query editor with a line number gutter, a comment toggle and a selection aware run button that executes only the highlighted statement.

Around the engine there is a C FFI shim in sqlrite-ffi, the ask crate behind the natural language tool, and SDK wrappers for Python and Node.js under sdk/. The WASM SDK is deliberately not a workspace member, because its target is wasm32-unknown-unknown and a native workspace build would fail on a wasm only crate, so wasm-pack drives that build separately.

The end to end example apps are where the pieces get exercised together, and they are tracked under the SQLR-38 umbrella. A Python LLM agent with persistent memory does vector and lexical recall, fact extraction and summaries in a single .sqlrite file. A Node.js chat with your notes turns Markdown into a hybrid HNSW and BM25 index and serves it to Claude Desktop through sqlrite-mcp in read-only mode. And a local-first journaling desktop app uses Markdown daily notes with BM25 full text search and an ask my journal panel, with the whole data layer in one file. There are also quickstarts for C, Go, Rust, Python, Node.js and WebAssembly, plus a wasm playground.

Where SQLRite is the wrong tool

Three cases argue against it. The first is production storage. The project says outright that the goal is understanding database internals by building one, and the version number 0.14.0 says the same thing. A database you are about to put user data into needs a track record of not losing it, a storage format you can rely on across versions, and a maintenance commitment, and none of those follow from a learning project with a REPL and a desktop app attached.

The second case is a project that needs SQLite's feature set or its file format. This is a reimplementation modelled on SQLite, not a binding to it, so the two do not share a file format, and the SQL surface that exists here is the subset the author has built. If your requirement is that an existing .sqlite file opens, or that a specific SQL feature works, this is the wrong tool and the C library with a language binding is the right one.

The third case is a team that wants a query engine rather than a storage engine. The example apps in the repository lean on vector search, hybrid HNSW plus BM25 retrieval and natural language to SQL, which tells you the direction of travel, but the README's own description of the project is a light version of SQLite, and the effort is going into the engine rather than into a broad analytical surface.

There is also a security consideration in the MCP path that deserves a moment. The ask tool takes a provider API key through an environment variable, and the read-only flag protects the database from the agent but not from whoever can read the environment. Giving an agent a key and a database is a decision about trust, and the flag only covers half of it.

On the maintenance side, the last push was on 2026-09-19 and the newest release is v0.14.0 from 2026-06-11, with a Rust engine release and a separate WASM release tagged the same day, so the two artifacts move together. The Makefile gives the benchmark story a name, with a bench target running the SQLRite against SQLite comparison in a lean profile and a second target enabling a DuckDB driver for one group of benchmarks, which is the shape of a project measuring itself against the thing it is modelled on.

Editorial conclusion

SQLRite suits a developer who wants to understand how a file backed database is built, and who can accept a partial reimplementation with the rough edges that implies. It does not suit a production application, since the project states its goal is understanding database internals by building one, and it does not suit a team that needs the full SQLite feature set or the file format compatibility. Before you build on it, check which SQL features and which storage guarantees are actually implemented for your case, and note that the last push was on 2026-09-19 with the newest release v0.14.0 from 2026-06-11.

Frequently asked questions

Official sources

1. joaoh82/rust_sqlite on GitHub
2. License: MIT
3. Project website
4. README
5. Releases