Reduce fsyncs and write to vlog and bplustree during compaction (#359)

Author: arriqaaq

Cargo.lock

@@ -31,7 +31,6 @@ async-trait = "0.1.82"
 chrono = "0.4.43"
 guardian = "1.3.0"
 scopeguard = "1.2.0"
-memmap2 = "0.9.5"
 log = "0.4.28"
 lz4_flex = "0.12"
 crossbeam-skiplist = "0.1.3"

Cargo.toml

@@ -148,6 +148,10 @@ let tree = TreeBuilder::with_options(opts).build()?;
 
 **Note:** Versioning requires VLog to be enabled. When you call `with_versioning(true, retention_ns)`, VLog is automatically enabled and configured appropriately.
 
+**Important:** When versioning is enabled without the B+tree index, timestamps inserted "back in time" (earlier than existing timestamps) will not be read correctly. This is because the LSM tree orders entries by user key ascending and sequence number descending, not by timestamp.
+
+If you need to insert historical data with earlier timestamps, enable the B+tree versioned index with `with_versioned_index(true)`. The B+tree allows in-place updates and correctly handles out-of-order timestamp inserts.
+
 ## Transaction Operations
 
 ### Basic Operations

README.md

@@ -587,6 +587,15 @@ The motivation for the optional B+tree index:
 | Fast point and range queries for history | Insert performance slows during LSM writes |
 | All versions of a key are contiguous | Every LSM write also updates B+tree |
 
+**Timestamp Ordering Limitation:**
+
+When using LSM-only versioning (without B+tree index), timestamps inserted "back in time" will not be read correctly. This occurs because:
+- LSM orders entries by `(user_key ASC, seq_num DESC)`
+- Point-in-time queries (`get_at`) find the first entry with `seq_num <= snapshot_seq` where `timestamp <= query_timestamp`
+- A later-inserted entry with an earlier timestamp will have a higher sequence number, causing it to be returned instead of the correct historical value
+
+To support out-of-order timestamp inserts, enable the B+tree index with `with_versioned_index(true)`. The B+tree stores entries sorted by `(user_key, timestamp)` and supports in-place updates, correctly handling historical data insertion.
+
 **Read-after-Write Consistency:**
 
 Currently, the B+tree index is updated synchronously during LSM writes, providing read-after-write consistency for versioned queries. A recently written version is immediately visible via the `history()` API.

docs/ARCHITECTURE.md

@@ -156,17 +156,6 @@ impl Batch {
 		self.add_record_internal(kind, key, value, None, timestamp)
 	}
 
-	pub(crate) fn add_record_with_valueptr(
-		&mut self,
-		kind: InternalKeyKind,
-		key: Key,
-		value: Option<Value>,
-		valueptr: Option<ValuePointer>,
-		timestamp: u64,
-	) -> Result<()> {
-		self.add_record_internal(kind, key, value, valueptr, timestamp)
-	}
-
 	pub(crate) fn count(&self) -> u32 {
 		self.entries.len() as u32
 	}

src/batch.rs

@@ -3498,7 +3498,7 @@ mod tests {
 	use test_log::test;
 
 	use super::*;
-	use crate::{InternalKey, InternalKeyKind};
+	use crate::{BytewiseComparator, InternalKey, InternalKeyKind, TimestampComparator};
 
 	#[derive(Clone)]
 	struct TestComparator;
@@ -6166,4 +6166,51 @@ mod tests {
 		assert_eq!(iter2.key().user_key(), b"key08");
 		assert_eq!(iter1.key().user_key(), b"key01"); // Unchanged
 	}
+
+	#[test]
+	fn test_full_range_scan_with_timestamp_comparator() {
+		let file = NamedTempFile::new().unwrap();
+		let cmp = Arc::new(TimestampComparator::new(Arc::new(BytewiseComparator::default())));
+		let mut tree = BPlusTree::disk(file.path(), cmp).unwrap();
+
+		// Insert entries out of timestamp order to prove the comparator sorts correctly.
+		// TimestampComparator orders: user_key ASC, timestamp DESC.
+		let entries = [
+			(b"alpha".to_vec(), 300u64),
+			(b"alpha".to_vec(), 100),
+			(b"alpha".to_vec(), 200),
+			(b"beta".to_vec(), 500),
+			(b"beta".to_vec(), 400),
+			(b"gamma".to_vec(), 600),
+		];
+
+		for (user_key, ts) in &entries {
+			let key = InternalKey::new(user_key.clone(), *ts, InternalKeyKind::Set, *ts).encode();
+			tree.insert(key, format!("{}-{}", String::from_utf8_lossy(user_key), ts).into_bytes())
+				.unwrap();
+		}
+
+		// Full range scan using the empty-slice pattern
+		let empty: &[u8] = &[];
+		let iter = tree.range(empty..).unwrap();
+		let results: Vec<(Vec<u8>, u64)> = iter
+			.map(|entry| {
+				let (k, _v) = entry.unwrap();
+				let ikey = InternalKey::decode(&k);
+				(ikey.user_key.clone(), ikey.timestamp)
+			})
+			.collect();
+
+		// Expected: user_key ASC, timestamp DESC within each user_key
+		let expected: Vec<(Vec<u8>, u64)> = vec![
+			(b"alpha".to_vec(), 300),
+			(b"alpha".to_vec(), 200),
+			(b"alpha".to_vec(), 100),
+			(b"beta".to_vec(), 500),
+			(b"beta".to_vec(), 400),
+			(b"gamma".to_vec(), 600),
+		];
+
+		assert_eq!(results, expected);
+	}
 }