GO — Healthy across the board

• Last commit today
• 13 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Turso is a Rust-based in-process SQL database engine that achieves SQLite compatibility while reimplementing the core engine from scratch. It provides a drop-in replacement for SQLite with support for multiple language bindings (Python, JavaScript, Java, C#, Go) and cloud deployment via Turso Cloud, solving the problem of embedding a reliable relational database in applications without server overhead. Monorepo with Cargo workspace spanning core engine (core/), language bindings (bindings/{python,javascript,java,dotnet,rust}), CLI tooling (cli/), extensions system (extensions/{crypto,csv,regexp,etc}), and 12+ testing/benchmarking crates (testing/differential-oracle/, testing/stress/, perf/). Core database logic lives in core/ crate; SQLite compatibility layer in sqlite3/; sync engine in sync/engine/.

Full-stack developers and database engineers building edge-first applications who need SQLite compatibility but want modern Rust performance, better concurrency support, and the option to run locally or sync with Turso Cloud. Also relevant for teams maintaining SQLite-dependent systems seeking a production-grade alternative.

BETA status with substantial production signals: the codebase is actively developed (monorepo with 18M+ Rust LOC across 40+ member crates), has comprehensive CI/CD via GitHub Actions (workflows for Rust testing, Antithesis fuzzing), and includes mature testing infrastructure (differential fuzzer, stress tests, sqlite_test_ext). However, official warning states it 'may still contain bugs'—suitable for new projects with risk tolerance, not legacy migration without vetting.

Complex system with multi-crate dependencies across 40+ workspace members (bindings, extensions, testing tools) increasing coordination risk. BETA status means breaking changes possible. Single organization maintainer (Turso Inc.) with undisclosed contributor count. However, mitigated by: comprehensive differential fuzzing against SQLite (testing/differential-oracle/), active CI signals, and MIT licensing. Main risks are API instability during BETA and potential resource constraints during critical bugs.

Active BETA development: workspace includes recent additions like concurrent-simulator (testing/), differential fuzzing infrastructure (testing/differential-oracle/ with sql_gen and fuzzer crates), encryption benchmarking (perf/encryption/), and CDC (Change Data Capture) skill documentation. GitHub Actions includes Antithesis scheduled fuzzing (antithesis-schedule.yml). Sync engine and sdk-kit crates suggest cloud replication features in active development.

git clone https://github.com/tursodatabase/turso.git
cd turso
cargo build --release  # Build all workspace members
cargo test --all       # Run comprehensive test suite
cargo run -p cli -- --version  # Test CLI

Daily commands:

cargo run -p cli -- db test.db  # Interactive CLI shell
cargo run -p turso --example basic  # Run example from core/examples/
cargo test -p core --lib       # Test core database engine
cargo test -p sqlite3 --lib    # Test SQLite compatibility

Dev container provided (.devcontainer/Dockerfile with compose) for isolated environment.

• core/Cargo.toml — Core library manifest defining Turso's primary dependency tree and feature flags that affect all downstream builds.
• Cargo.toml — Workspace root manifest organizing 20+ members (bindings, extensions, testing, sync) — essential to understand build structure.
• .claude/skills/mvcc/SKILL.md — Documents multi-version concurrency control implementation, the architectural core enabling Turso's SQLite compatibility.
• .claude/skills/storage-format/SKILL.md — Defines Turso's on-disk storage format and serialization strategy, foundational to data durability and migration.
• .github/workflows/rust.yml — Primary CI/CD pipeline orchestrating compilation, testing, and validation of the Rust codebase on every commit.
• README.md — Project overview documenting Turso's value proposition, compatibility scope, and supported language bindings.
• CONTRIBUTING.md — Contributor guidelines covering PR workflow, code style, and development environment setup.

Add a new SQL extension function

1. Create a new crate in extensions/ directory (e.g., extensions/mynewfunc/) with Cargo.toml defining the function signature (extensions/core/Cargo.toml)
2. Implement the function using Turso's function registration macros (check extensions/crypto for pattern) (extensions/crypto)
3. Register the extension in extensions/tests to validate SQL-level behavior (extensions/tests)
4. Update core/Cargo.toml to add the new extension as an optional feature and dependency (core/Cargo.toml)

Add support for a new language binding

1. Create a new directory under bindings/ (e.g., bindings/go) with its own Cargo.toml and FFI layer (bindings/rust)
2. Expose the public Rust API surface via #[no_mangle] C functions following the pattern in bindings/javascript (bindings/javascript)
3. Create corresponding GitHub Actions workflow (reference .github/workflows/java.yml) to build, test, and publish the new binding (.github/workflows/java.yml)
4. Update Cargo.toml workspace members list to include the new binding crate (Cargo.toml)

Add a new conformance or fuzz test

1. Add test case to testing/simulator or create a new test module in tests/ directory following the test harness patterns (testing/simulator)
2. If testing differential correctness, integrate into Antithesis-compatible test in Dockerfile.antithesis (Dockerfile.antithesis)
3. Create or update .github/workflows/*.yml to run the new test in CI (reference .github/workflows/fuzz.yml for fuzzing or .github/workflows/conformance.yml for compatibility) (.github/workflows/fuzz.yml)
4. Document test objectives and coverage in the corresponding SKILL.md (e.g., .claude/skills/transaction-correctness/SKILL.md) (.claude/skills/transaction-correctness/SKILL.md)

• Rust — Memory safety without garbage collection, enabling embedded in-process database without GC pauses; zero-cost abstractions for performance-critical MVCC and storage layers
• MVCC (Multi-Version Concurrency Control) — Enables non-blocking concurrent reads and writes, critical for in-process databases serving multiple tasks without lock contention
• SQLite compatibility layer — Allows existing SQLite users and tools to migrate with minimal changes; leverages 20+ years of SQL semantics validation
• Multi-language bindings (NAPI, JNI, FFI) — Maximizes adoption across JavaScript, Python, Java, .NET, Go ecosystems while maintaining single Rust implementation
• Deterministic event simulator — Enables reproducible testing of concurrent behavior without flaky timing-dependent tests; critical for database correctness
• Antithesis continuous fuzzing — Differential fuzzing against SQLite reference catches subtle correctness bugs that unit tests miss; increases confidence in distributed scenario correctness

• In-process vs. server-process database

  • Why: Eliminates network latency and serialization overhead; simplifies deployment for single-machine applications
  • Consequence: No built-in multi-machine replication (sync engine is separate); shared memory limits compared to external database; not suitable for applications requiring strict separation of concerns

• MVCC over simpler locking schemes

  • Why: Eliminates reader-writer lock contention, enabling true concurrent read-write workloads
  • Consequence: Increased memory overhead (multiple versions retained); more complex GC of old versions; slightly higher CPU for write coordination

• Rust implementation over C (like SQLite)

  • Why: Memory safety guarantees reduce vulnerability surface; better tooling and ecosystem for testing (miri, clippy, fuzzing)
  • Consequence: Slightly larger binary; longer compilation time; fewer developers familiar with Rust compared to C

• SQLite compatibility over custom SQL dialect

  • Why: Massive existing SQL corpus, test suites, and user knowledge
  • Consequence: Must maintain compatibility surface; cannot diverge on semantics without ecosystem confusion; slower adoption of newer SQL features

• Distributed primary-replica consensus (Turso itself is single-instance; sync engine handles replication separately)
• Multi-machine network transparent clustering (users deploy multiple instances; replication via CDC sync engine)
• Network protocol compatibility with SQL servers (not a TCP server; users must use language bindings)
• Real-time change notifications to remote subscribers (CDC is event-log based, not pub/sub; subscribers poll or use SDK kit)

Workspace coordination: modifying core/ requires updating versions in 20+ dependent crates—use cargo update carefully. Extension loading: extensions/ use plugin architecture; incorrect ABI versions between core and extension cause silent failures. SQLite compatibility: differential fuzzer (testing/differential-oracle/) is the source of truth for correctness—changes to core/ should re-run fuzzer before PR. Testing environment: sqlite_test_ext requires SQLite dev headers (ubuntu: libsqlite3-dev); CI handles this but local dev may need setup. MVCC implementation: transaction ordering is non-obvious—see .claude/skills/mvcc/SKILL.md before modifying transaction.rs.

• MVCC (Multi-Version Concurrency Control) — Core transaction isolation mechanism in Turso replacing SQLite's simpler locking—see .claude/skills/mvcc/SKILL.md to understand transaction interleaving, snapshot visibility, and write conflict detection
• Differential Fuzzing — Primary correctness validation strategy (testing/differential-oracle/ crate)—learns how Turso behavior diverges from SQLite reference by executing identical SQL on both and comparing results
• Change Data Capture (CDC) — Enables replication and sync features (.claude/skills/cdc/SKILL.md)—tracks mutations for cloud sync in sync/engine/; critical for understanding row versioning
• SQLite Wire Protocol — Turso achieves compatibility by implementing wire protocol (sqlite3/src/)—allows clients expecting SQLite to connect unchanged; see .claude/skills/debugging/references/ for protocol details
• Storage Format (B-tree variant) — Turso reimplements SQLite's B-tree storage format—see .claude/skills/storage-format/SKILL.md for index structure, page layout, and fragmentation handling affecting performance
• Async I/O Model — Modern async execution (.claude/skills/async-io-model/SKILL.md) replaces SQLite's synchronous I/O—affects query scheduling, concurrency limits, and latency profile under load
• Property-Based Testing / Shrinking — testing/differential-oracle/sql_gen_prop/ generates random valid SQL schemas and statements—reduces fuzzer findings to minimal failing case (shrinking) for faster debugging

• sqlite/sqlite — Reference implementation and compatibility target—differential fuzzer (testing/differential-oracle/) validates Turso behavior against this
• libsql/libsql — Alternative SQLite fork by same team behind Turso—shares similar replication goals but different architecture approach
• tursodatabase/turso-cli — Companion CLI tooling for Turso Cloud interactions—complements the core database engine
• rusqlite/rusqlite — Mature Rust SQLite bindings—used in benchmarks (perf/throughput/rusqlite/) as performance baseline
• tursodatabase/libsql-client-py — Official Python client library for Turso—reference implementation of bindings/python/ protocol

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for differential-oracle fuzzer

The repo has a sophisticated differential-oracle testing framework (testing/differential-oracle/fuzzer, sql_gen, sql_gen_prop) but lacks visible integration tests that verify the fuzzer can catch actual divergences between Turso and SQLite. This would ensure the fuzzer infrastructure is working correctly and catch regressions early.

• [ ] Create testing/differential-oracle/fuzzer/tests/integration_tests.rs with test cases that intentionally inject bugs into Turso and verify the fuzzer detects them
• [ ] Add tests that verify the differential-oracle can correctly identify SQL generation edge cases
• [ ] Add a CI workflow step in .github/workflows/fuzz.yml that runs these integration tests before the full fuzzing schedule
• [ ] Document the test setup in .claude/skills/differential-fuzzer/SKILL.md

Add CDC (Change Data Capture) integration tests and documentation

The skills directory shows CDC is a documented capability (.claude/skills/cdc/SKILL.md) but there are no visible dedicated test suites or examples. New contributors should add concrete test cases covering CDC correctness, edge cases, and transaction semantics.

• [ ] Create tests/cdc_integration_tests.rs with tests for: basic change capture, transaction boundaries, schema changes, and concurrent write handling
• [ ] Add CDC examples to the core module documentation showing how to use CDC with the async-io model
• [ ] Verify CDC behavior under the MVCC implementation by adding transaction-correctness tests in tests/ that specifically target CDC scenarios
• [ ] Update .claude/skills/cdc/SKILL.md with concrete example code and known limitations

Add missing GitHub Actions workflow for JavaScript/Node.js binding compatibility across platforms

The repo publishes to npm (bindings/javascript) and has publish workflows, but examining .github/workflows shows no dedicated Node.js cross-platform (Windows/macOS/Linux) testing workflow. This is critical for browser and Electron compatibility.

• [ ] Create .github/workflows/javascript-ci.yml that tests bindings/javascript and bindings/javascript/sync against Node LTS versions (18, 20, 22) on ubuntu-latest, windows-latest, and macos-latest
• [ ] Add WASM build verification steps using the napi build process shown in .github/workflows/napi.yml as reference
• [ ] Include tests for both CommonJS and ESM module formats in bindings/javascript
• [ ] Add a check that published npm package types are correct by testing with TypeScript strict mode enabled

• Add benchmarking harness for new extensions: perf/memory/ and perf/throughput/ exist for core, but extensions/{csv,regexp,ipaddr} lack dedicated memory footprint tests—create perf/throughput/extension-benchmarks crate following existing patterns.
• Implement missing CDC tests: sync/engine/src/ has change data capture API but testing/differential-oracle/fuzzer/ doesn't validate CDC correctness against SQLite—add sql_gen rules to generate CDC-triggering schemas.
• Document MVCC isolation levels: .claude/skills/mvcc/SKILL.md exists but contains no concrete examples; add test cases in core/tests/ demonstrating READ_UNCOMMITTED vs SERIALIZABLE behavior with cross-crate references.

The Turso codebase demonstrates a mature approach to security with comprehensive testing infrastructure (fuzzing, differential testing, property-based testing) and multiple language bindings. However, the distributed nature of bindings, complex testing infrastructure, and Docker/CI-CD configuration create moderate security concerns. No critical vulnerabilities were identified, but several medium-severity issues exist around security boundaries, infrastructure isolation, and documentation. The project would benefit from centralized security documentation, formal threat modeling, and explicit security requirements for language bindings and CI/CD pipelines.

• Medium · Multiple Language Bindings Without Clear Security Boundaries — bindings/ directory (java, javascript, python, dotnet, rust). The codebase includes bindings for Java, JavaScript, Python, .NET, and Rust. Each binding represents a potential attack surface. Without visible security documentation in the file structure, there's risk that language-specific security best practices may not be consistently applied across all bindings. Fix: Implement comprehensive security documentation for each binding language. Establish security review processes for FFI/interop code. Create security testing requirements specific to each language binding.
• Medium · Testing Infrastructure May Expose Security Issues — testing/ directory, particularly differential-oracle/, simulator/, and fuzzing-related workflows. The codebase includes differential fuzzing, SQL fuzzing (SQLancer), and property-based testing tools. While these are security-positive, the test infrastructure and fuzzing configurations could potentially be exploited or misused if not properly isolated. Fix: Isolate fuzzing and testing infrastructure from production systems. Implement secure artifact handling for crash reproductions and coverage data. Review CI/CD workflows for potential exfiltration paths.
• Medium · Docker Infrastructure Exposes Squid Proxy Configuration — .devcontainer/squid.conf, .devcontainer/init-firewall.sh, .devcontainer/docker-compose.yml. The devcontainer includes a Squid proxy configuration (.devcontainer/squid.conf) and firewall initialization script. If development containers are accidentally exposed or misconfigured, this could create network security risks. Fix: Ensure development containers are never exposed to production networks. Implement network policies restricting container communication. Review and restrict Squid proxy ACLs. Document proper firewall initialization procedures.
• Low · GitHub Actions Workflows Lack Visible Security Hardening — .github/workflows/ (multiple .yml files). The .github/workflows directory contains numerous automation pipelines (antithesis, fuzzing, publishing). Without visibility into workflow content, there's potential for secrets management issues, untrusted action usage, or improper artifact handling. Fix: Implement workflow security scanning tools. Use OIDC for cloud authentication instead of static tokens. Pin GitHub Action versions to commits. Implement branch protection rules. Audit all third-party actions used.
• Low · SQLite3 Binding May Inherit SQLite Vulnerabilities — sqlite3/ directory, bindings/sqlite3 references. The project wraps SQLite (bindings/sqlite3). While Turso aims for compatibility, any vulnerabilities in underlying SQLite could affect this project if not properly isolated or patched. Fix: Maintain an inventory of SQLite CVEs. Implement vulnerability scanning for SQLite dependencies. Document any Turso-specific mitigations or deviations from SQLite behavior. Create a process for rapid patching of upstream vulnerabilities.
• Low · Encryption Benchmark Exposes Cryptographic Implementation — perf/encryption/. The perf/encryption directory suggests custom cryptographic performance testing or implementation. Cryptographic code requires special scrutiny and is prone to side-channel attacks if not implemented carefully. Fix: Conduct cryptographic code review by security specialists. Perform side-channel analysis. Consider using well-audited cryptographic libraries. Document cryptographic algorithms and key derivation functions used.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tursodatabase/turso shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tursodatabase/turso repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tursodatabase/turso.

What it runs against: a local clone of tursodatabase/turso — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tursodatabase/turso | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tursodatabase/turso. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tursodatabase/turso.git
#   cd turso
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tursodatabase/turso and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tursodatabase/turso(\\.git)?\\b" \\
  && ok "origin remote is tursodatabase/turso" \\
  || miss "origin remote is not tursodatabase/turso (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "core/Cargo.toml" \\
  && ok "core/Cargo.toml" \\
  || miss "missing critical file: core/Cargo.toml"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f ".claude/skills/mvcc/SKILL.md" \\
  && ok ".claude/skills/mvcc/SKILL.md" \\
  || miss "missing critical file: .claude/skills/mvcc/SKILL.md"
test -f ".claude/skills/storage-format/SKILL.md" \\
  && ok ".claude/skills/storage-format/SKILL.md" \\
  || miss "missing critical file: .claude/skills/storage-format/SKILL.md"
test -f ".github/workflows/rust.yml" \\
  && ok ".github/workflows/rust.yml" \\
  || miss "missing critical file: .github/workflows/rust.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tursodatabase/turso"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.