graphitesql

A pure, safe, no_std-capable Rust re-implementation of SQLite, as a single crate, aiming for byte-for-byte compatibility with the SQLite 3 database file format.

Status: read engine working. graphitesql opens real SQLite files and runs SELECT queries — table/index b-trees, overflow pages, the schema catalog, a SQL parser, and an expression/aggregate executor are implemented and tested against databases produced by sqlite3. Writing (the b-tree writer, journal, WAL) is next. The full build plan and status is in ROADMAP.md.

Why

SQLite is the most-deployed database in the world, but it's C. graphitesql brings the same file format and SQL dialect to places where a safe, dependency-free, no_std Rust library shines:

• WebAssembly — run a real SQLite-compatible database in the browser or in a wasm sandbox with no JS shim and no Emscripten.
• Embedded / bare-metal — no_std + alloc, bring-your-own storage.
• Sandboxed / capability-based hosts — no unsafe, no FFI, no syscalls except through a Vfs trait you control.

Goals

• ✅ File-format compatible. Open a database written by sqlite3; write one sqlite3 can open. Verified with differential tests against the C library.
• ✅ Safe. #![forbid(unsafe_code)] across the whole crate.
• ✅ Portable. #![no_std] + alloc. Optional std feature for real files.
• ✅ Single crate. Storage, B-tree, SQL parser, and VM all live in graphitesql.
• ✅ No dependencies. Only core and alloc.

Non-goals (at least initially)

• Being a faster SQLite. Correctness and compatibility first.
• 100% of every SQLite extension (FTS5, R-Tree, sessions, …). These are layered in later, behind features. See the roadmap.
• Drop-in C ABI (libsqlite3.so). A C-API shim is a possible future crate, not the core.

Usage

Today you can open a real SQLite database and query it (read-only):

use graphitesql::{Connection, Value};

let db = Connection::open("app.db")?; // a file written by sqlite3
let result = db.query("SELECT id, name FROM users WHERE id > 1 ORDER BY name")?;

for row in &result.rows {
    if let (Value::Integer(id), Value::Text(name)) = (&row[0], &row[1]) {
        println!("{id}: {name}");
    }
}

// Aggregates, GROUP BY, expressions, scalar functions all work:
let r = db.query("SELECT count(*), max(id) FROM users")?;

The write path (CREATE/INSERT/UPDATE/DELETE, :memory: creation) is under construction — see the roadmap. Low-level format primitives are also public (graphitesql::format::DatabaseHeader, graphitesql::btree, …).

Feature flags

Disable default features for no_std. An in-memory VFS (:memory:) is always available, including on wasm.

Building & testing

cargo test                                   # full suite (std)
cargo build --no-default-features            # no_std build
cargo clippy --all-targets                   # lints (unsafe is forbidden)

Reference material & attribution

graphitesql is an independent re-implementation. It uses SQLite's public-domain source and documentation purely as a specification reference — no SQLite code is compiled into this crate. Fetch the (git-ignored, hash-verified) reference tree with:

./reference/fetch.sh

Deep gratitude to D. Richard Hipp and the SQLite developers. See NOTICE and ATTRIBUTION.md.

License

Public domain, mirroring SQLite. In place of a legal notice, graphitesql carries a blessing — see LICENSE. The SPDX identifier is blessing (the SQLite Blessing).