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
Decision gist · record as of 2026-07-28
Transaction-correctness explains how Turso's WAL mode ensures durable, atomic, isolated transactions with consistent reader snapshots. 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.
Use it when
- Turso's transaction-correctness guide defines four checkpoint modes.
- Turso's concurrency model allows exactly one writer and multiple readers simultaneously.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
tursodatabase/turso/transaction-correctness · repository language: Rust
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
File tree — 1 file
.claude/skills/transaction-correctness/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Understand how WAL mechanics and checkpointing work in Turso”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This skill documents Turso's experimental Multi-Version Concurrency Control system, which allows readers and writers to operate simultaneously without blocking through row-level snapshot isolation. It covers enabling MVCC via pragma, the versioning model tracking begin/end timestamps, and the architecture built on lock-free data structures. The guide also details checkpointing behavior, current limitations like garbage collection and recovery gaps, and testing patterns for MVCC-enabled code.
This guide breaks down how SQLite organizes data on disk, from the 100-byte header through page types, B-tree layouts, and cell formats. It covers record encoding with serial types, overflow page chains for large payloads, and freelist structures for space reuse. Includes Turso implementation details and debugging commands.
This guide walks through Turso's debugging toolkit for tracking down database problems. Compare bytecode between SQLite and Turso to pinpoint code generation bugs versus VM issues, enable trace logging for core components, run stress tests with ThreadSanitizer to catch threading problems, and use deterministic simulation with seeds to reproduce elusive bugs. Corruption debugging tools help diagnose WAL and integrity failures.
code-quality establishes standards for writing reliable database code in Rust, prioritizing data integrity over silent failures. It covers error handling discipline, exhaustive pattern matching, and invariant checking to prevent corruption. The guide emphasizes crashing on invalid state rather than continuing in undefined conditions, and avoiding premature abstractions or workarounds.
yield-injections provides test-only infrastructure for injecting cooperative yields and synthetic failures into resumable state machines. Use it to test state-machine re-entry safety, interleaving behavior, and abandonment cleanup by marking yield points and controlling when they fire. Includes fixed injectors for unit tests and simulator support for randomized deterministic coverage.
memory-benchmark measures heap allocations and process memory for SQL workloads under different journal modes. It includes dhat-based allocation tracking, stack-usage analysis via the stack-report binary, and six built-in workload profiles (insert-heavy, read-heavy, mixed, scan-heavy, series-blob, update-churn) for regression detection and performance tuning.
More skills turso-db (MIT) · cdc (MIT)