mvcc

Source excerpt starting at line 1.

1---2name: mvcc3description: Overview of Experimental MVCC feature - snapshot isolation, versioning, limitations4---5# MVCC Guide (Experimental)6 7Multi-Version Concurrency Control. **Work in progress, not production-ready.**8 9**CRITICAL**: Ignore MVCC when debugging unless the bug is MVCC-specific.10 11## Enabling MVCC12 13```sql14PRAGMA journal_mode = 'mvcc';15```16 17Runtime configuration, not a compile-time feature flag. Per-database setting.18 19## How It Works20 21Standard WAL: single version per page, readers see snapshot at read mark time.22 23MVCC: multiple row versions, snapshot isolation. Each transaction sees consistent snapshot at begin time.24 25### Key Differences from WAL26 27| Aspect | WAL | MVCC |28|--------|-----|------|29| Write granularity | Every commit writes full pages | Affected rows only30| Readers/Writers | Don't block each other | Don't block each other |31| Persistence | `.db-wal` | `.db-log` (logical log) |32| Isolation | Snapshot (page-level) | Snapshot (row-level) |33 34### Versioning35 36Each row version tracks:37- `begin` - timestamp when visible38- `end` - timestamp when deleted/replaced39- `btree_resident` - existed before MVCC enabled40 41## Architecture42 43```44Database45  └─ mv_store: MvStore46      ├─ rows: SkipMap<RowID, Vec<RowVersion>>47      ├─ txs: SkipMap<TxID, Transaction>48      ├─ Storage (.db-log file)49      └─ CheckpointStateMachine50```51 52**Per-connection**: `mv_tx` tracks current MVCC transaction.53 54**Shared**: `MvStore` with lock-free `crossbeam_skiplist` structures.55 56## Key Files57 58- `core/mvcc/mod.rs` - Module overview59- `core/mvcc/database/mod.rs` - Main implementation (~3000 lines)60- `core/mvcc/cursor.rs` - Merged MVCC + B-tree cursor61- `core/mvcc/persistent_storage/logical_log.rs` - Disk format62- `core/mvcc/database/checkpoint_state_machine.rs` - Checkpoint logic63 64## Checkpointing65 66Flushes row versions to B-tree periodically.67 68```sql69PRAGMA mvcc_checkpoint_threshold = <pages>;70```71 72Process: acquire lock → begin pager txn → write rows → commit → truncate log → fsync → release.73 74## Current Limitations75 76**Not implemented:**77- Garbage collection (old versions accumulate)78- Recovery from logical log on restart79 80**Known issues:**81- Checkpoint blocks other transactions, even reads!82- No spilling to disk; memory use concerns83 84## Testing85 86```bash87# Run MVCC-specific tests88cargo test mvcc89 90# TCL tests with MVCC91make test-mvcc92```93 94Use `#[turso_macros::test(mvcc)]` attribute for MVCC-enabled tests.95 96```rust97#[turso_macros::test(mvcc)]98fn test_something() {99    // runs with MVCC enabled100}101```102 103## References104 105- `core/mvcc/mod.rs` documents data anomalies (dirty reads, lost updates, etc.)106- Snapshot isolation vs serializability: MVCC provides the former, not the latter107