Skip to content

kvserver: merge undersized ranges into adequately-sized neighbors - #174808

Open
NAVEENKUMARKR777 wants to merge 1 commit into
cockroachdb:masterfrom
NAVEENKUMARKR777:fix/kv-merge-undersized-ranges
Open

kvserver: merge undersized ranges into adequately-sized neighbors#174808
NAVEENKUMARKR777 wants to merge 1 commit into
cockroachdb:masterfrom
NAVEENKUMARKR777:fix/kv-merge-undersized-ranges

Conversation

@NAVEENKUMARKR777

Copy link
Copy Markdown

Summary

The merge queue previously required both the LHS and RHS of a candidate
merge to be individually below the RangeMinBytes threshold before merging
them (see mergeQueue.process in merge_queue.go). This meant a range
wedged between two neighbors that were each at or above the threshold could
never merge with either of them and would persist indefinitely — even if it
held zero or near-zero bytes, e.g. after all of its rows were deleted.

This was discussed at length in #100443 (kvoli, andrewbaptist, erikgrinaker),
including simulations comparing a few different fix strategies, but no fix
ever landed. This PR implements the minimal, backportable fix that the
discussion converged on: merge whenever either side is below the
threshold, as long as the combined range stays below twice the threshold.

This preserves the existing anti-thrashing behavior — an undersized range is
never merged into a neighbor that's already close to its max size, since
shouldSplitRange already guards against producing an over-max-size range,
and the doubled-threshold check avoids producing a range that's likely to
need re-splitting soon — while letting genuinely small ranges merge away
instead of persisting forever.

Test plan

Added two new subtests to TestMergeQueue covering both the newly-allowed
case (RHS above threshold, but combined size stays well under 2x the
threshold) and the still-disallowed case (RHS above threshold, combined size
would not stay comfortably below 2x). Ran the full TestMergeQueue suite
(including all pre-existing subtests) to confirm no regressions.

Resolves: #100443
Epic: none

Release note (bug fix): Fixed a bug where a range could become permanently
unmergeable if its immediate neighbor's size was at or above the configured
minimum range size, even if the range itself was empty or nearly empty. The
range merge queue now merges such ranges as long as the resulting merged
range would stay comfortably below the minimum size threshold.

🤖 Generated with Claude Code

The merge queue previously required both the LHS and RHS of a
candidate merge to be individually below the RangeMinBytes threshold
before merging them. This meant that a range wedged between two
neighbors that were each at or above the threshold could never merge
with either of them and would persist indefinitely, even if it held
zero or near-zero bytes (eg, after all of its rows were deleted).

Change the merge queue to merge whenever either side is below the
threshold, as long as the combined range would stay below twice the
threshold. This preserves the existing anti-thrashing behavior (an
undersized range is never merged into a neighbor that's already close
to its max size, since the split queue already guards against
producing an over-max-size range, and the doubled-threshold check
avoids producing a range that's likely to need re-splitting soon) while
letting genuinely small ranges merge away instead of persisting
forever.

This was discussed at length in the issue below without a fix ever
landing; this commit implements the minimal, backportable version of
the fix that commenters converged on.

Resolves: cockroachdb#100443
Epic: none

Release note (bug fix): Fixed a bug where a range could become
permanently unmergeable if its immediate neighbor's size was at or
above the configured minimum range size, even if the range itself was
empty or nearly empty. The range merge queue now merges such ranges as
long as the resulting merged range would stay comfortably below the
minimum size threshold.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@NAVEENKUMARKR777
NAVEENKUMARKR777 requested a review from a team as a code owner September 7, 2026 08:05
@blathers-crl

blathers-crl Bot commented Sep 7, 2026

Copy link
Copy Markdown

Thank you for contributing to CockroachDB. Please ensure you have followed the guidelines for creating a PR.

My owl senses detect your PR is good for review. Please keep an eye out for any test failures in CI.

🦉 Hoot! I am a Blathers, a bot for CockroachDB. My owner is dev-inf.

@blathers-crl blathers-crl Bot added the O-community Originated from the community label Sep 7, 2026
@cockroachlabs-cla-agent

cockroachlabs-cla-agent Bot commented Sep 7, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

O-community Originated from the community

Projects

None yet

Development

Successfully merging this pull request may close these issues.

kv: lhs range with 0 bytes will never be merged

1 participant