transaction-correctness
WAL mechanics, checkpointing, concurrency, and recovery in Turso's SQLite implementation.
- 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
- 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)
- Each connection maintains private page cache, dirty pages, and snapshot view; shared state includes frame cache, read lock slots, write lock, and checkpoint lock across all connections
- Recovery replays valid commits from WAL on crash; durability, atomicity, isolation, and no-lost-updates invariants enforced through fsync on COMMIT and checkpoint coordination
Transaction Correctness Guide
Turso uses WAL (Write-Ahead Logging) mode exclusively.
Files: .db, .db-wal (no .db-shm - Turso uses in-memory WAL index)
WAL Mechanics
Write Path
- Writer appends frames (page data) to WAL file (sequential I/O)
- COMMIT = frame with non-zero db_size in header (marks transaction end)
- Original DB unchanged until checkpoint
Read Path
- Reader acquires read mark (mxFrame = last valid commit frame)
- For each page: check WAL up to mxFrame, fall back to main DB
- Reader sees consistent snapshot at its read mark
Checkpointing
Transfers WAL content back to main DB.
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
604testing
How to write tests, when to use each type of test, and how to run them. Contains information about conversion of `.test` to `.sqltest`, and how to write `.sqltest` and rust tests
598