SQLite rewrite in Rust. 40+ crate workspace.
cargo build # build. never build with release.
cargo test # rust unit/integration tests
cargo fmt # format (required)
cargo clippy --workspace --all-features --all-targets -- --deny=warnings # lint
cargo run -q --bin tursodb -- -q # run the interactive cli
make test # TCL compat + sqlite3 + extensions + MVCC
make test-single TEST=foo.test # single TCL test
CI=1 make -C testing/sqltests run-rust # sqltest runner (preferred for new tests)
scripts/diff.sh "SQL" [label] # compare sqlite3 vs tursodb outputlimbo/
├── core/ # Database engine (translate/, storage/, vdbe/, io/, mvcc/)
├── parser/ # SQL parser (lexer, AST, grammar)
├── cli/ # tursodb CLI (REPL, MCP server, sync server)
├── bindings/ # Python, JS, Java, .NET, Go, Rust
├── extensions/ # crypto, regexp, csv, fuzzy, ipaddr, percentile
├── testing/ # simulator/, concurrent-simulator/, differential-oracle/
├── sync/ # engine/, sdk-kit/ (Turso Cloud sync)
├── sdk-kit/ # High-level SDK abstraction
└── tools/ # dbhash utility
| Task | Location | Notes |
|---|---|---|
| Query execution | core/vdbe/execute.rs |
12k LOC bytecode interpreter |
| SQL compilation | core/translate/ |
AST → bytecode, optimizer in optimizer/ |
| B-tree/pages | core/storage/btree.rs |
10k LOC, SQLite-compatible format |
| WAL/durability | core/storage/wal.rs |
Write-ahead log, checkpointing |
| SQL parsing | parser/src/parser.rs |
11k LOC recursive descent |
| Add extension | extensions/core/ |
ExtensionApi, scalar/aggregate/vtab traits |
| Add binding | bindings/ |
PyO3, NAPI, JNI, FRB, CGO patterns |
| Deterministic tests | testing/simulator/ |
Fault injection, differential testing |
| New SQL tests | testing/sqltests/tests/ |
.sqltest format preferred |
| Quick sqlite3 diff | scripts/diff.sh |
Compare sqlite3 vs tursodb output for a query |
| MVCC testing REPL | cli/mvcc_repl.rs |
Multi-conn concurrent txn testing REPL |
- Testing - test types, when to use, how to write
- Code Quality - correctness rules, Rust patterns, comments
- Debugging - bytecode comparison, logging, sanitizers
- PR Workflow - commits, CI, dependencies
- Transaction Correctness - WAL, checkpointing, concurrency
- Storage Format - file format, B-trees, pages
- Async I/O Model - IOResult, state machines, re-entrancy
- MVCC - experimental multi-version concurrency (WIP)
- Correctness paramount. Production DB, not a toy. Crash > corrupt
- SQLite compatibility. Compare bytecode with
EXPLAIN - Every change needs a test. Must fail without change, pass with it
- Assert invariants. Don't silently fail. Don't hedge with if-statements
- Own your regressions. If tests fail after your change, they are your regressions. Debug them directly. Never stash/revert to "check if they fail on main" — that wastes time and is categorically banned.
- Validate your hypotheses.: If you suspect a given cause for a bug, validate it and provide incontrovertible evidence. NEVER make unearned assumptions.
Running in GitHub Action? Max-turns limit in .github/workflows/claude.yml. OK to push WIP and continue in another action. Stay focused, avoid rabbit holes.