with one click
transaction-correctness
How WAL mechanics, checkpointing, concurrency rules, recovery work in tursodb
Menu
How WAL mechanics, checkpointing, concurrency rules, recovery work in tursodb
How to benchmark and analyze memory usage in Turso using the memory-benchmark crate and dhat heap profiler. Use this skill whenever the user mentions memory usage, memory profiling, allocation tracking, heap analysis, memory regression, memory benchmarking, dhat, or wants to understand where memory is being allocated during SQL workloads. Also use when investigating memory growth in WAL or MVCC mode. IMPORTANT - If you modify the perf/memory crate (add profiles, change CLI flags, change output format, etc.), update this skill document to reflect those changes so it stays accurate for future agents.
Use when working with Turso yield injection or synthetic failure injection machinery for safe resumable state-machine boundaries, including YieldInjector, FailureInjector, YieldPointMarker, inject_transition_yield!, inject_io_yield!, inject_transition_failure!, CommitYieldPoint, CheckpointYieldPoint, CursorYieldPoint, deterministic interleaving tests, abandoned statement/commit tests, and concurrent-simulator yield plans.
Use when migrating Turso core code to crate::alloc, allocator-api2, cfg(nightly) allocator aliases, fallible collection APIs, try_vec!, try_collect, or LimboError::OutOfMemory handling. Covers import style, allocator-aware aliases, stable/nightly boundaries, shuttle Arc compatibility, and how to keep allocator foundation commits separate from module migrations. Read this when changing code that does allocations.
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
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
Overview of Experimental MVCC feature - snapshot isolation, versioning, limitations
| name | transaction-correctness |
| description | How WAL mechanics, checkpointing, concurrency rules, recovery work in tursodb |
Turso uses WAL (Write-Ahead Logging) mode exclusively.
Files: .db, .db-wal (no .db-shm - Turso uses in-memory WAL index)
Transfers WAL content back to main DB.
WAL grows → checkpoint triggered (default: 1000 pages) → pages copied to DB → WAL reused
Checkpoint types:
SQLite uses a shared memory file (-shm) for WAL index. Turso does not - it uses in-memory data structures (frame_cache hashmap, atomic read marks) since multi-process access is not supported.
On crash:
Key files:
Per-Connection (private):
Pager - page cache, dirty pages, savepoints, commit stateWalFile - connection's snapshot view:
max_frame / min_frame - frame range for this connection's snapshotmax_frame_read_lock_index - which read lock slot this connection holdslast_checksum - rolling checksum stateShared across connections:
WalFileShared - global WAL state:
frame_cache - page-to-frame index (replaces .shm file)max_frame / nbackfills - global WAL progressread_locks[5] - read mark slots (TursoRwLock with embedded frame values)write_lock - exclusive writer lockcheckpoint_lock - checkpoint serializationfile - WAL file handleDatabaseStorage - main .db fileBufferPool - shared memory allocation