transaction-correctness_skill

Overview

This skill explains transaction correctness in Turso by detailing WAL mechanics, checkpointing, concurrency rules, and recovery behavior. It focuses on how Turso implements SQLite-compatible WAL semantics in an in-process, single-process environment and what invariants guarantee durable, atomic, and isolated transactions.

How this skill works

WAL writes append page frames to a .db-wal file; a COMMIT is encoded as a frame with a non-zero db_size marking transaction end. Readers take a read mark (mxFrame) and consult the WAL up to that frame before falling back to the main .db file, producing consistent snapshots. Checkpointing transfers WAL pages back into the main DB using PASSIVE, FULL, RESTART, or TRUNCATE strategies, while Turso replaces the disk shm index with an in-memory frame cache and atomic read marks.

When to use it

• When designing or debugging transaction behavior for embedded Turso databases.
• When you need to understand how readers observe consistent snapshots while writers append to WAL.
• When tuning checkpoint behavior and choosing PASSIVE vs FULL vs RESTART vs TRUNCATE.
• When verifying crash recovery and ensuring committed transactions are durable.
• When implementing concurrency controls or integrating Turso into single-process environments.

Best practices

• Ensure COMMITs are fsynced before reporting success to clients to preserve durability.
• Limit long-running readers to avoid blocking checkpoint progress; use PASSIVE checkpoints where possible.
• Keep write transactions short to reduce contention on the single-writer lock.
• Monitor WAL growth and checkpoint frequency (default trigger ~1000 pages) to avoid large WAL files.
• Rely on Turso’s in-memory WAL-index semantics only for single-process use; do not assume multi-process shared-memory behavior.

Example use cases

• A local desktop app using Turso wants consistent reads while background writes append to WAL.
• A WebAssembly host embeds Turso and needs deterministic recovery semantics after process restart.
• A developer investigates why checkpointing stalls due to an active long-lived reader and adjusts reader lifetime.
• A system validates that commits persisted across crashes by inspecting WAL replay on exclusive lock acquisition.