release-v1.9.6

ZoneTree v1.9.6: Improves ZoneTree write/read efficiency.

Key Changes

• Reuse the already-computed key hash during bloom filter checks, avoiding duplicate hash computation on lookup paths.
• Make maintainer disposal wait for active merge work automatically, so callers do not need to remember a separate wait step before disposing maintainers.
• Update documentation for the 1.9.5+ behavior and usage guidance.
• Add Windows profile-store reference benchmark results for 100K, 500K, 1M, 2M, 5M, and 10M profiles.

Why It Matters

Bloom filter checks are on hot read paths, so reusing the key hash reduces repeated work without changing public behavior.

Maintainer disposal is now safer and easier: disposing a maintainer also waits for in-flight merges, which makes the common lifecycle pattern less error-prone.

What's Changed

• Reuse key hash for bloom filter checks by @koculu in #165
• Ease maintainer usage by automatically waiting for merges on disposal by @koculu in #166
• Improve documentation for 1.9.5 and later. by @koculu in #167
• Add 100K, 500K, 1M, 2M, 5M, 10M win reference benchmark. by @koculu in #168

Full Changelog: release-v1.9.5...release-v1.9.6

release-v1.9.5

ZoneTree v1.9.5: Concurrent Read Scaling Unlocked

ZoneTree v1.9.5 is a substantial read-path and concurrency release. It removes key sources of contention, accelerates sequential disk access, strengthens iterator lifecycle handling, and introduces a much more rigorous parallel benchmark suite.

The result is significantly stronger throughput under parallel read workloads while preserving ZoneTree’s excellent single-thread performance.

Highlights

Concurrent mutable-segment reads

Mutable segments now use a concurrent Bloom filter to reject definite misses before entering the B+Tree lookup path.

• Avoids B+Tree locking for most negative lookups.
• Uses three probes published with one atomic word update.
• Continues serving frozen mutable segments after the filter becomes ready.
• Skips B+Tree locking entirely when the tree is empty.
• Supports custom key types through the new IKeyHasher<TKey> API.
• Automatically supplies hashers for ZoneTree’s known key types.

Faster disk lookups

Disk-segment reads received several complementary optimizations:

• Sequential TryGet calls are detected and accelerated through configurable search-hint prefetching.
• Materialized entries are reused across iterator reads.
• Cached entries use aligned 16-entry chunks, allowing different iterator prefetch sizes to share data without retaining overlapping batches.
• Single-record reads avoid polluting the materialized-entry cache.
• Sparse-array construction reads keys and values together.
• Circular cache slots are now distributed uniformly for both power-of-two and arbitrary capacities.
• Unused cache statistics and resizing machinery were removed from the hot path.

Scalable lifecycle coordination

Disk-segment lifecycle handling has been redesigned for correctness and parallel scalability.

• CAS-based iterator leases replace the previous shared lock and counter.
• Segment retirement remains nonblocking while iterators are active.
• The final iterator completes a pending drop exactly once.
• Cache-line-padded read-counter stripes reduce contention across processors.
• Multi-part segment retirement and drop behavior is covered by dedicated regression tests.
• Segment disposal, live backup, iterator attachment, and active-read coordination were hardened.

New Configuration

Option	Default	Purpose
ZoneTreeOptions.KeyHasher	Known-type default	Supplies comparer-compatible key hashes
MutableSegmentBloomFilterBitsPerItem	8	Controls Bloom-filter memory and false-positive rate; 0 disables it
MaterializedEntryCacheSize	4096 chunks	Limits aligned materialized chunks per decompressed block; 0 disables it
SearchHintPrefetchSize	16 entries	Controls sequential TryGet prefetching; 0 disables it

Hasher type information and Bloom-filter configuration are now recorded in ZoneTree metadata for observability.

Benchmarking

The profile-store benchmark has become a first-class parallel scaling suite.

• Supports single or comma-separated --parallelism levels.
• Synchronizes worker starts before phase timing begins.
• Uses shared ZoneTree and RocksDB handles with engine-appropriate worker isolation.
• Routes duplicate updates consistently to preserve correctness.
• Uses binary Int64 RocksDB keys for fair user-ID comparisons.
• Enables Server GC and documents tiered-compilation behavior accurately.
• Caps profile-fetching queries at 50 results to keep them from dominating runs.
• Produces parallelism-specific reports, charts, checksums, and resource measurements.
• Adds canonical Linux reference runs from 100K through 100M profiles.

Upgrade Notes

Custom key types must now provide an IKeyHasher<TKey>. Keys considered equal by the configured comparer must produce identical hash codes. ZoneTree validates the common case of case-insensitive string comparers paired with incompatible hashers.

Several low-level implementation-facing APIs were simplified:

• CircularCache<T>.SetCacheSize, CacheStats, and ResetCacheStats were removed.
• SingleBlockPin now accepts its block-cache contribution flag through the constructor.

Validation

This release adds extensive focused coverage for Bloom filtering, key hashing, materialized entry caching, search hints, circular-cache distribution, disk read counters, iterator leases, multi-part retirement, disposal, metadata persistence, option validation, and live backup behavior.

What's Changed

• Update benchmark references and memory notes by @koculu in #154
• Add 50M and 100M benchmark reference. by @koculu in #155
• Update updater delegate docs and comments. by @koculu in #156
• Fix the flaky test provider in LiveBackupTests. by @koculu in #157
• Improve rocksdb bench to use int64 binary serialization by @koculu in #158
• Avoid lock contention if B+Tree is empty. by @koculu in #159
• Performance Feature: Add bounded materialized entry cache. by @koculu in #160
• Performance Feature: Add search hint prefetch option to improve sequential lookup speed. by @koculu in #161
• Performance: Scale disk reads and iterator lifecycle under concurrent workloads by @koculu in #162
• Performance Feature: Unlock concurrent read scaling with mutable-segment Bloom filtering by @koculu in #163
• Add parallel scaling to the profile-store benchmark by @koculu in #164

Full Changelog: release-v1.9.4...release-v1.9.5

release-v1.9.4

What's Changed

This release adds optional disk-segment iterator prefetching for scan-heavy workloads.

ZoneTree now supports runtime iterator options, letting callers choose whether a specific iterator should prefetch sequential disk-segment records. Existing iterator behavior remains unchanged by default.

• Add disk iterator prefetch support by @koculu in #152
• Add profile store benchmark suite by @koculu in #153

Full Changelog: release-v1.9.3...release-v1.9.4

release-v1.9.3

What's Changed

• Metadata json should reflect runtime options. by @koculu in #148
• Adds centralized option validation for ZoneTree configuration. by @koculu in #149
• Clarifies WAL mode tradeoffs in docs and comments. by @koculu in #150

Full Changelog: release-v1.9.0...release-v1.9.3

release-v1.9.0

What's Changed

• Moved to github org. by @koculu in #139
• Improve live backup & docs by @koculu in #140
• Improve docs by @koculu in #141
• drop redundant docs by @koculu in #142
• Update NuGet Packages and Add Docs Navigation Config by @koculu in #144
• Reworks InMemoryFileStreamProvider into a fast RAM-backed storage provider by @koculu in #145
• Set the default ZoneTree compression from LZ4 to Zstd fastest by @koculu in #146

Full Changelog: release-v1.8.8...release-v1.9.0

release-v1.8.8

Highlights

This release introduces ZoneTree live backup support, a major documentation refresh, and a broad modernization of the codebase for newer .NET versions.

Breaking Changes

• ZoneTree now targets net10.0 and net9.0 only.
• Older .NET target frameworks have been removed to simplify maintenance and enable newer runtime and C# features.

New Features

Live Backup and Restore

Added a new ZoneTree.Backup subsystem for creating and restoring live backups.

using var backup = zoneTree.CreateLiveBackup(new LiveBackupOptions
{
    Store = new LocalLiveBackupProvider("backup/app"),
    Schedule = LiveBackupSchedule.Daily(
        new TimeOnly(2, 0),
        new TimeOnly(14, 0))
});

backup.Start();

See backup docs for more: https://github.com/koculu/ZoneTree/blob/main/docs/durability/backups.md

This includes:

• CreateLiveBackup(...) extension methods for local-directory and custom backup stores
• LiveBackupOptions
• LiveBackupSchedule
• LocalLiveBackupProvider
• LiveBackupRestore
• record-batch backup support for in-memory records
• scheduled backup generations
• configurable backup record compression
• configurable concurrent file transfers

Live backups can include disk segments, bottom segments, and in-memory records, with support for both live and snapshot-style in-memory collection.

Expanded Documentation

Added a new documentation structure under docs/, covering:

• getting started
• reads and writes
• iteration and range scans
• transactions
• maintenance
• WAL modes
• recovery
• backups
• compression
• disk segment tuning
• production checklist
• troubleshooting
• API overview
• building systems on ZoneTree

Improvements

• Improved operation-index documentation and clarified its role as a per-key freshness token.
• Added iterator options for including deleted records and controlling whether iterator reads contribute to the block cache.
• Replaced weak-identity locking patterns with explicit Lock instances throughout the core, WAL, transaction, backup, logger, and file-provider paths.
• Improved analyzer compliance by replacing broad suppressions with targeted suppressions.
• Modernized argument validation with newer .NET guard APIs.
• Improved metadata serialization by relying on source-generated JSON serialization.
• Improved in-memory file stream provider synchronization and path handling.
• Improved backup-related disk segment collection and restore metadata generation.

Fixes and Reliability

• Added regression coverage for WAL maximum operation index handling.
• Added tests for stale metadata checkpoint recovery.
• Added tests for compressed WAL stream tail and incomplete-block behavior.
• Added tests for transaction rollback and incremental history behavior.
• Added tests for live backup generation and restore behavior.
• Added disk segment factory tests.
• Strengthened iterator, replication, count, transaction, and BTree concurrency test coverage.

Documentation and Cleanup

• Reworked the README and moved detailed guides into the new docs/ tree.
• Removed older DocFX-style documentation files.
• Normalized formatting, indentation, BOM usage, and final newlines across source, playground, and test projects.
• Cleaned up benchmark and playground code formatting.

Upgrade Notes

Projects targeting older frameworks must move to net9.0 or newer before upgrading to this release.

Users who rely on backup or replication scenarios should review the new operation-index and backup documentation, especially around live backup generation, restore behavior, and per-key freshness semantics.

Pull Requests

• Rewrite docs by @koculu in #136
• Add live backup and restore support. by @koculu in #137
• Drop older .NET version support - improve code quality by @koculu in #138

Full Changelog: release-v1.8.7...release-v1.8.8

release-v1.8.7

What's Changed

• Fix Discord badge in README by @koculu in #134
• Rebrand ZoneTree and harden WAL, merge, opIndex, and transaction recovery by @koculu in #135

Full Changelog: release-v1.8.6...release-v1.8.7

ZoneTree vNext

This release introduces the new ZoneTree namespace and includes important reliability improvements for WAL recovery, merge operations, and optimistic transactions.

Migration

The package has been rebranded from Tenray.ZoneTree to ZoneTree.

Update your imports:

using Tenray.ZoneTree;

to:

using ZoneTree;

Existing databases created with the previous namespace metadata remain supported through the built-in legacy metadata migration.

Improvements

• Updated the project to target .NET 10.
• Improved compressed WAL recovery when files end with incomplete tail data.
• Improved incremental backup reliability for compressed and sync WAL modes.
• Hardened bottom segment and multipart merge behavior.
• Improved opIndex recovery semantics for WAL replay and replication scenarios.
• Improved optimistic transaction history tracking.
• Added regression tests for rare recovery, merge, and transaction edge cases.

Fixes

• Fixed partial reads in file stream recovery paths.
• Fixed compressed WAL skip behavior across tail blocks.
• Fixed persisted sparse-array metadata loading.
• Fixed cancelled multipart merge cleanup.
• Fixed transaction history stamp tracking for auto-commit writes.
• Fixed repeated writes to the same key inside one transaction.
• Fixed atomic add/update result reporting.
• Fixed a disk-segment cache release issue.

release-v1.8.6

What's Changed

• Add in-memory FileStreamProvider by @koculu in #126
• Fix cloned DiskSegmentOptions by @koculu in #127
• Bump version to 1.8.6 by @koculu in #128
• Fix KeyCacheRecord lifetime default by @koculu in #129
• Fix TTLValue equality comparison by @koculu in #130
• Fix infinite loop bug in array conversion methods by @koculu in #131
• Fix IsDroppping typo by @koculu in #132

Full Changelog: release-v1.8.5...release-v1.8.6

release-v1.8.5

What's Changed

• Expose default values. by @koculu in #122
• Expose the copy of the options. by @koculu in #124

Full Changelog: release-v1.8.4...release-v1.8.5

release-v1.8.4

What's Changed

• Upgrade to the net 9.0. by @koculu in #104

Full Changelog: release-v1.8.3...release-v1.8.4