Menu
Overview of Experimental MVCC feature - snapshot isolation, versioning, limitations
| name | mvcc |
| description | Overview of Experimental MVCC feature - snapshot isolation, versioning, limitations |
Multi-Version Concurrency Control. Work in progress, not production-ready.
CRITICAL: Ignore MVCC when debugging unless the bug is MVCC-specific.
PRAGMA journal_mode = 'mvcc';
Runtime configuration, not a compile-time feature flag. Per-database setting.
Standard WAL: single version per page, readers see snapshot at read mark time.
MVCC: multiple row versions, snapshot isolation. Each transaction sees consistent snapshot at begin time.
| Aspect | WAL | MVCC |
|---|---|---|
| Write granularity | Every commit writes full pages | Affected rows only |
| Readers/Writers | Don't block each other | Don't block each other |
| Persistence | .db-wal | .db-log (logical log) |
| Isolation | Snapshot (page-level) | Snapshot (row-level) |
Each row version tracks:
begin - timestamp when visibleend - timestamp when deleted/replacedbtree_resident - existed before MVCC enabledDatabase
โโ mv_store: MvStore
โโ rows: SkipMap<RowID, Vec<RowVersion>>
โโ txs: SkipMap<TxID, Transaction>
โโ Storage (.db-log file)
โโ CheckpointStateMachine
Per-connection: mv_tx tracks current MVCC transaction.
Shared: MvStore with lock-free crossbeam_skiplist structures.
core/mvcc/mod.rs - Module overviewcore/mvcc/database/mod.rs - Main implementation (~3000 lines)core/mvcc/cursor.rs - Merged MVCC + B-tree cursorcore/mvcc/persistent_storage/logical_log.rs - Disk formatcore/mvcc/database/checkpoint_state_machine.rs - Checkpoint logicFlushes row versions to B-tree periodically.
PRAGMA mvcc_checkpoint_threshold = <pages>;
Process: acquire lock โ begin pager txn โ write rows โ commit โ truncate log โ fsync โ release.
Not implemented:
Known issues:
# Run MVCC-specific tests
cargo test mvcc
# TCL tests with MVCC
make test-mvcc
Use #[turso_macros::test(mvcc)] attribute for MVCC-enabled tests.
#[turso_macros::test(mvcc)]
fn test_something() {
// runs with MVCC enabled
}
core/mvcc/mod.rs documents data anomalies (dirty reads, lost updates, etc.)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
Change Data Capture - architecture, entrypoints, bytecode emission, sync engine integration, tests