tursodatabase/turso▌

Production-grade code standards emphasizing correctness, crash-safety, and Rust idioms over convenience. \n \n Prioritizes data integrity: crash on invalid state rather than corrupt data; assert invariants aggressively; handle all errors explicitly \n Rust-specific patterns: make illegal states unrepresentable, use exhaustive pattern matching and enums over strings, minimize allocations \n Comments document why , not what ; avoid temporal markers, AI conversation references, and code-repeating e

Guidelines for commits, pull requests, CI workflows, and secure dependency management. \n \n Emphasizes atomic, focused commits with clear messages; recommends git rebase -i for clean history and avoiding mixed logic/formatting changes \n PR best practices include keeping changes small and focused, running tests before submission, and using WIP states in GitHub Actions when needed \n Security checklist: never commit .env files, credentials, or secrets \n Dependency additions require a license fi

Debugging tools for Turso database using bytecode comparison, logging, and deterministic simulation. \n \n Bytecode comparison workflow identifies whether behavior differences stem from code generation bugs or VM/storage layer issues by comparing SQLite and Turso EXPLAIN output \n Logging via RUST_LOG environment variable captures detailed traces from turso_core and simulator components during test runs \n ThreadSanitizer stress tests detect threading issues across configurable thread counts and

Cooperative async patterns using explicit state machines, completions, and re-entrancy safeguards for Turso's I/O model. \n \n Core types: IOResult<T> (returns Done or IO requiring re-call) and Completion for tracking individual operations \n CompletionGroup aggregates multiple completions into one, with nesting and cancellation support \n State machine pattern encodes progress in enum variants to safely handle re-entry across yield points \n Critical pitfall: mutating shared state before y

Generates hierarchical AGENTS.md knowledge base files with complexity-scored subdirectory documentation. \n \n Discovers project structure through parallel explore agents, bash analysis, LSP codemap, and existing documentation to build a complete codebase map \n Scores directories by file count, code ratio, symbol density, and module boundaries to determine which subdirectories warrant their own AGENTS.md files \n Generates root AGENTS.md with overview, structure, conventions, and anti-patterns,

$22

Property-based fuzzer that compares Turso against SQLite to catch SQL correctness bugs. \n \n Generates random SQL statements and schemas, then executes them on both Turso and SQLite to detect mismatches in row sets, error handling, or schema state \n Supports deterministic reproduction via seed-based runs, configurable statement/table/column counts, and verbose output for debugging \n Includes continuous loop mode for extended fuzzing campaigns and Docker runner for CI with configurable timeout

WAL mechanics, checkpointing, concurrency, and recovery in Turso's SQLite implementation. \n \n Turso uses WAL (Write-Ahead Logging) exclusively with in-memory WAL index instead of SQLite's shared memory file, supporting one writer and concurrent readers without blocking \n Checkpointing transfers WAL pages back to the main database in four modes: PASSIVE (non-blocking), FULL (waits for readers), RESTART (resets WAL), and TRUNCATE (truncates WAL file) \n Each connection maintains private page ca

SQL and Rust testing guide covering test types, execution, and writing patterns. \n \n Three primary test formats: .sqltest (preferred for SQL compatibility across backends), TCL .test (legacy, being phased out), and Rust integration tests for regression and complex scenarios \n Run tests via make test for the full suite, make -C testing/sqltests run-cli for SQL tests, or cargo test for Rust tests \n .sqltest format uses simple declarative syntax with @database , test blocks, and expect sections

SQLite file format internals: pages, B-trees, cells, overflow chains, and freelist structure used in Turso. \n \n Database organized as fixed-size pages (default 4096 bytes) containing B-tree nodes, overflow pages, and freelist pages; header stores magic bytes, page size, encoding, and freelist pointers \n Two B-tree types: table B-trees use 64-bit rowid keys and store row data; index B-trees use arbitrary keys (index columns + rowid) \n Cells encode payloads with varint-prefixed rowid/keys; ove