turso: Instructions file for Codex

Turso Agent Guidelines

SQLite rewrite in Rust. 40+ crate workspace.

Quick Reference

cargo build                    # build (debug; release builds are slow and double the target dir)
cargo check                    # type check. prefer to `cargo build`
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 (debug build)

make test                      # TCL compat + sqlite3 + extensions + MVCC
make test-single TEST=foo.test # single TCL test
make -C sqlite/conformance run-rust ARGS='--snapshot-filter __never__'  # sqltest runner (preferred for new tests)
CI=1 make -C sqlite/conformance run-rust  # use only if snapshot tests are required

scripts/diff.sh "SQL" [label]  # compare sqlite3 vs tursodb output

Testing

Running Tests

• cargo test - Rust unit and integration tests
• make test - broad compatibility suite (TCL, sqlite3, extensions, MVCC)
• make test-single TEST=foo.test - single legacy TCL test
• make -C sqlite/conformance run-rust ARGS='--snapshot-filter __never__' - preferred .sqltest runner for new coverage
• CI=1 make -C sqlite/conformance run-rust - only when snapshot tests are required
• make -C postgres/conformance run - run the PostgreSQL .sqltest corpus against tursopg
• make -C postgres/conformance run-postgres - run the PostgreSQL .sqltest corpus against a real PostgreSQL server (needs Docker, or a server at PG_DSN)

Test Organization

Default: add coverage to the narrowest existing test harness that can express the bug. Prefer extending an existing test file or directory over creating a new one.

• sqlite/conformance/sqlite-sqltests/ - preferred for SQL conformance coverage. These tests run the same scenario against both Turso and SQLite, so use them first for parser, planner, executor, and SQL semantics work that fits the .sqltest DSL.
• tests/integration/ - primary fallback when the behavior cannot be expressed cleanly in .sqltest. Put API-level regressions, multi-connection orchestration, storage assertions, injected failures, timeout behavior, and other Rust-driven scenarios here.
• sqlite/conformance/upstream/ - imported upstream SQLite golden tests. They are fixed compatibility coverage, so a Turso behavior change should be fixed in Turso rather than by editing them; edits here are for upstream syncs or harness maintenance.
• postgres/conformance/pg-sqltests/ - .sqltest coverage for the PostgreSQL frontend. Tests are meant to pass on both tursopg (run) and real PostgreSQL (run-postgres).
• testing/cli_tests/ - CLI-focused Python coverage for shell behavior and end-to-end command workflows.
• tests/fuzz/ - minimized fuzz regressions and targeted edge cases that are easier to keep as Rust tests.
• testing/simulator/ and testing/concurrent-simulator/ - deterministic concurrency, scheduling, and failure-injection coverage for state-machine and I/O correctness.
• testing/differential-oracle/ and testing/stress/ - differential and long-running stress tooling. Use these for deeper investigation or specialized validation, not as the first stop for a focused regression test.