transaction-correctness
This guide explains Turso's Write-Ahead Logging system, covering how transactions are written, read, and checkpointed back to the main database file. It details the concurrency model where one writer coexists with multiple readers, checkpoint strategies from passive to truncate modes, and the recovery process after crashes. The guide also maps Turso's implementation to its core storage layer, distinguishing per-connection state from shared WAL structures.
Transaction-correctness explains how Turso's WAL mode ensures durable, atomic, isolated transactions with consistent reader snapshots.
AI-generated summary based on this skill's SKILL.md
Install
tursodatabase/turso/transaction-correctness · repository language: Rust
git clone https://github.com/tursodatabase/turso
cp -r turso/.claude/skills/transaction-correctness ~/.claude/skills/transaction-correctnessFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How does Turso handle WAL transactions?
Turso's transaction-correctness system uses Write-Ahead Logging (WAL) where all changes are written to a log before modifying the main database file. When you begin a transaction, Turso allocates frames in the WAL, writes your changes there, and only after fsync confirms durability does the transaction commit. This ensures that even if the database crashes, the WAL can replay committed transactions during recovery, maintaining ACID properties and preventing lost updates.
What are Turso's checkpoint types and how do they work?
Turso's transaction-correctness guide defines four checkpoint modes. Passive checkpoints merge WAL frames into the main database without blocking writers. Full checkpoints wait for all writers to finish before merging. Restart checkpoints truncate the WAL after merging, freeing space. Truncate checkpoints are like restart but used in specific scenarios. Each mode balances durability, concurrency, and storage efficiency differently, allowing you to choose based on your workload's needs.
How does Turso manage concurrent readers and writers?
Turso's concurrency model allows exactly one writer and multiple readers simultaneously. The writer appends frames to the WAL while readers access either the main database file or WAL frames depending on which version they need. Readers take snapshots at specific WAL frame numbers, ensuring consistent views. The in-memory WAL index tracks which frames are committed, preventing readers from seeing uncommitted data and coordinating safe concurrent access.
What is Turso's in-memory WAL index and frame cache?
Turso's transaction-correctness implementation uses an in-memory WAL index that maps page numbers to their frame locations in the WAL, replacing SQLite's shared-memory file (.shm). The frame cache stores recently accessed WAL frames in memory for fast retrieval. This design reduces system calls and improves performance compared to traditional SQLite, while the index helps readers quickly locate the correct version of each page for their snapshot.
How does Turso ensure crash recovery and database consistency?
After a crash, Turso's transaction-correctness recovery process scans the WAL to identify committed transactions (those with valid checksums and complete frame data). Uncommitted frames are discarded. Committed frames are replayed into the main database file in order, restoring the database to its last consistent state. The pager validates frame integrity and uses the WAL index to determine which frames apply, ensuring no partial or corrupted transactions are applied.
What distinguishes connection-private state from shared WAL structures in Turso?
Turso's transaction-correctness design separates per-connection state (like read snapshots and transaction context) from shared structures (the WAL file, in-memory index, and frame cache). Each connection maintains its own snapshot version, preventing interference between transactions. Shared structures are protected by coordination logic so that one writer's changes become visible to new readers only after commit, while existing readers continue using their snapshot until they refresh.
SKILL.md
rendered from the published skill — quoted content, verbatim
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.
WAL grows → checkpoint triggered (default: 1000 pages) → pages copied to DB → WAL reused
Checkpoint types: - PASSIVE: Non-blocking, stops at pages needed by active readers - FULL: Waits for readers, checkpoints everything - RESTART: Like FULL, also resets WAL to beginning - TRUNCATE: Like RESTART, also truncates WAL file to zero length
WAL-Index
SQLite uses a shared memory file (-shm) for WAL index.
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.claude/skills/transaction-correctness/SKILL.md