perf(db): cache Pos() result to avoid repeated disk reads (#1192)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: benbjohnson

db.go

@@ -101,6 +101,13 @@ type DB struct {
 		m map[int]*ltx.FileInfo
 	}
 
+	// Cached position from the latest L0 LTX file.
+	// nil means cache is invalid; non-nil is the cached position.
+	pos struct {
+		sync.Mutex
+		value *ltx.Pos
+	}
+
 	fileInfo os.FileInfo // db info cached during init
 	dirInfo  os.FileInfo // parent dir info cached during init
 
@@ -300,6 +307,8 @@ func (db *DB) ResetLocalState(ctx context.Context) error {
 	db.maxLTXFileInfos.m = make(map[int]*ltx.FileInfo)
 	db.maxLTXFileInfos.Unlock()
 
+	db.invalidatePosCache()
+
 	db.Logger.Info("local state reset complete, next sync will create fresh snapshot")
 	return nil
 }
@@ -330,6 +339,9 @@ func (db *DB) deleteLocalLTXFile(level int, minTXID, maxTXID ltx.TXID) error {
 	if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
 		return err
 	}
+	if level == 0 {
+		db.invalidatePosCache()
+	}
 	return nil
 }
 
@@ -364,7 +376,15 @@ func (db *DB) DirInfo() os.FileInfo {
 }
 
 // Pos returns the current replication position of the database.
+// The result is cached and invalidated when L0 LTX files change.
 func (db *DB) Pos() (ltx.Pos, error) {
+	db.pos.Lock()
+	defer db.pos.Unlock()
+
+	if db.pos.value != nil {
+		return *db.pos.value, nil
+	}
+
 	minTXID, maxTXID, err := db.MaxLTX()
 	if err != nil {
 		return ltx.Pos{}, err
@@ -382,7 +402,20 @@ func (db *DB) Pos() (ltx.Pos, error) {
 	if err := dec.Verify(); err != nil {
 		return ltx.Pos{}, fmt.Errorf("ltx verification failed: %w", err)
 	}
-	return dec.PostApplyPos(), nil
+
+	pos := dec.PostApplyPos()
+	db.pos.value = &pos
+
+	return pos, nil
+}
+
+// invalidatePosCache clears the cached position so the next call to Pos()
+// recomputes it from disk. Call this when L0 LTX files are deleted or
+// when the L0 directory is cleared.
+func (db *DB) invalidatePosCache() {
+	db.pos.Lock()
+	db.pos.value = nil
+	db.pos.Unlock()
 }
 
 // Notify returns a channel that closes when the shadow WAL changes.
@@ -1195,6 +1228,7 @@ func (db *DB) checkDatabaseBehindReplica(ctx context.Context) error {
 	if err := os.RemoveAll(l0Dir); err != nil && !os.IsNotExist(err) {
 		return fmt.Errorf("remove L0 directory: %w", err)
 	}
+	db.invalidatePosCache()
 	if err := internal.MkdirAll(l0Dir, db.dirInfo); err != nil {
 		return fmt.Errorf("recreate L0 directory: %w", err)
 	}
@@ -1235,6 +1269,7 @@ func (db *DB) checkDatabaseBehindReplica(ctx context.Context) error {
 	if err := os.Rename(tmpPath, localPath); err != nil {
 		return fmt.Errorf("rename L0 file: %w", err)
 	}
+	db.invalidatePosCache()
 
 	db.Logger.Info("fetched latest L0 file from replica",
 		"min_txid", minTXID,
@@ -1632,6 +1667,7 @@ func (db *DB) sync(ctx context.Context, checkpointing bool, info syncInfo) (sync
 		db.maxLTXFileInfos.Lock()
 		delete(db.maxLTXFileInfos.m, 0) // clear cache if in unknown state
 		db.maxLTXFileInfos.Unlock()
+		db.invalidatePosCache()
 		return false, fmt.Errorf("rename ltx file: %w", err)
 	}
 
@@ -1646,6 +1682,12 @@ func (db *DB) sync(ctx context.Context, checkpointing bool, info syncInfo) (sync
 	}
 	db.maxLTXFileInfos.Unlock()
 
+	// Update cached position from the encoder.
+	encPos := enc.PostApplyPos()
+	db.pos.Lock()
+	db.pos.value = &encPos
+	db.pos.Unlock()
+
 	// Track the logical end of WAL content for checkpoint decisions.
 	// This is the WALOffset + WALSize from the LTX we just created.
 	// Using this instead of file size prevents issue #997 where stale
@@ -2177,6 +2219,9 @@ func (db *DB) EnforceL0RetentionByTime(ctx context.Context) error {
 			db.Logger.Error("failed to remove local l0 file", "path", localPath, "error", err)
 		}
 	}
+	if len(deleted) > 0 {
+		db.invalidatePosCache()
+	}
 
 	db.Logger.Info("l0 retention enforced", "deleted_count", len(deleted), "max_l1_txid", maxL1TXID)
 

db_internal_test.go

@@ -656,6 +656,9 @@ func TestDB_Verify_WALOffsetAtHeader(t *testing.T) {
 		t.Fatal(err)
 	}
 
+	// Invalidate cached position since we wrote an L0 file directly.
+	db.invalidatePosCache()
+
 	// Now call verify - before the fix, this would fail with:
 	// "prev WAL offset is less than the header size: -4088"
 	info, err := db.verify(context.Background())
@@ -776,6 +779,9 @@ func TestDB_Verify_WALOffsetAtHeader_SaltMismatch(t *testing.T) {
 		t.Fatal(err)
 	}
 
+	// Invalidate cached position since we wrote an L0 file directly.
+	db.invalidatePosCache()
+
 	// Call verify - should succeed but indicate snapshotting due to salt mismatch
 	info, err := db.verify(context.Background())
 	if err != nil {