testing
SQL and Rust testing guide covering test types, execution, and writing patterns.
- 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 - Run tests via
make testfor the full suite,make -C testing/sqltests run-clifor SQL tests, orcargo testfor Rust tests .sqltestformat uses simple declarative syntax with@database,testblocks, andexpectsections; TCL tests are being converted automatically with theconvertcommand, though manual adjustment of expected results is often needed due to database seed differences- Every functional change requires a test that fails without the change and passes with it; prefer in-memory databases (
:memory:) for test isolation
Testing Guide
Test Types & When to Use
| Type | Location | Use Case |
|---|---|---|
.sqltest |
testing/sqltests/tests/ |
SQL compatibility. Preferred for new tests |
TCL .test |
testing/ |
Legacy SQL compat (being phased out) |
| Rust integration | tests/integration/ |
Regression tests, complex scenarios |
| Fuzz | tests/fuzz/ |
Complex features, edge case discovery |
Note: TCL tests are being phased out in favor of testing/sqltests. The .sqltest format allows the same test cases to run against multiple backends (CLI, Rust bindings, etc.).
Running Tests
# Main test suite (TCL compat, sqlite3 compat, Python wrappers)
make test
# Single TCL test
More from tursodatabase/turso
code-quality
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
1.0Kindex-knowledge
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
657debugging
How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools
631async-io-model
Explanations of common asynchronous patterns used in tursodb. Involves IOResult, state machines, re-entrancy pitfalls, CompletionGroup. Always use these patterns in `core` when doing anything IO
604storage-format
SQLite file format, B-trees, pages, cells, overflow, freelist that is used in tursodb
604pr-workflow
General guidelines for Commits, formatting, CI, dependencies, security
596