tikv-configuration-file: update flow-control override behavior for v8.5.5 #21244

hhwyt · 2026-01-07T09:10:14Z

What is changed, added or deleted? (Required)

Update documentation for storage.flow-control.l0-files-threshold and storage.flow-control.soft-pending-compaction-bytes-limit to reflect the behavior change introduced in TiKV PR #18994.

v8.5.4 and earlier: flow-control config unconditionally overrides the corresponding RocksDB config.
From v8.5.5: flow-control config only overrides when it is smaller than the RocksDB config, to avoid weakening RocksDB's compaction acceleration mechanism when increasing flow-control thresholds.

Also update the corresponding RocksDB config items (level0-slowdown-writes-trigger, soft-pending-compaction-bytes-limit) with the same version-specific behavior notes.

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

Related TiKV PR: flow-control: fix compaction slowdown caused by increased flow-control thresholds. (#18710) tikv/tikv#18994

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

….5.5 Update documentation for storage.flow-control.l0-files-threshold and storage.flow-control.soft-pending-compaction-bytes-limit to reflect the behavior change introduced in TiKV PR pingcap#18994. - v8.5.4 and earlier: flow-control config unconditionally overrides the corresponding RocksDB config. - From v8.5.5: flow-control config only overrides when it is smaller than the RocksDB config, to avoid weakening RocksDB's compaction acceleration mechanism when increasing flow-control thresholds. Also update the corresponding RocksDB config items (level0-slowdown-writes-trigger, soft-pending-compaction-bytes-limit) with the same version-specific behavior notes.

ti-chi-bot · 2026-01-07T09:10:24Z

Hi @hhwyt. Thanks for your PR.

I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

hhwyt · 2026-01-07T09:26:33Z

/cc @qiancai @hbisheng PTAL, thx~

qiancai · 2026-01-07T09:28:22Z

/ok-to-test

ti-chi-bot · 2026-01-07T09:47:32Z

@hbisheng: adding LGTM is restricted to approvers and reviewers in OWNERS files.

Details

In response to this:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

qiancai

Rest LGTM

qiancai · 2026-01-09T02:41:04Z

tikv-configuration-file.md

+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`。
+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.l0-files-threshold` 小于 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。


Suggested change

+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`。

+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.l0-files-threshold` 小于 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

+ v8.5.4 及之前版本：当开启流控机制（[`enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置会直接覆盖 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。

+ 从 v8.5.5 和 v9.0.0 起：当开启流控机制（[`enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置仅在其值小于 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger) 时才覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

要考虑另一种描述方式吗，就是直接让用户参考下面那个配置项的描述也可以？这样避免一旦版本逻辑变更，需要改四处地方。

Suggested change

+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`。

+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.l0-files-threshold` 小于 `rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

> **注意**：

>

> 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger` 的值会被该配置项覆盖。详细参考 [`rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger`](/tikv-configuration-file.md#level0-slowdown-writes-trigger)。

qiancai · 2026-01-09T02:45:54Z

tikv-configuration-file.md

+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`。
+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.soft-pending-compaction-bytes-limit` 小于 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。


Suggested change

+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`。

+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.soft-pending-compaction-bytes-limit` 小于 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

+ v8.5.4 及之前版本：当开启流控机制（[`enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置会直接覆盖 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1)。

+ 从 v8.5.5 和 v9.0.0 起：当开启流控机制（[`enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置仅在其值小于 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1) 时才覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

另一种描述方式

Suggested change

+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`。

+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.soft-pending-compaction-bytes-limit` 小于 `rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

> **注意**：

>

> 当满足一定条件时，`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit` 的值会被该配置项覆盖。详细参考 [`rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit-1。

qiancai · 2026-01-09T02:50:19Z

tikv-configuration-file.md

+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.l0-files-threshold` 直接覆盖。
+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.l0-files-threshold`，则本配置项会被 `storage.flow-control.l0-files-threshold` 覆盖；否则保持本配置不变。


Suggested change

+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.l0-files-threshold` 直接覆盖。

+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.l0-files-threshold`，则本配置项会被 `storage.flow-control.l0-files-threshold` 覆盖；否则保持本配置不变。

+ v8.5.4 及之前版本：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项会被 [`storage.flow-control.l0-files-threshold`](/tikv-configuration-file.md#l0-files-threshold) 直接覆盖。

+ 从 v8.5.5 和 v9.0.0 起：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项仅在其值大于 [`storage.flow-control.l0-files-threshold`](/tikv-configuration-file.md#l0-files-threshold 时会被 `storage.flow-control.l0-files-threshold` 覆盖，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

qiancai · 2026-01-09T02:50:35Z

tikv-configuration-file.md

+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 直接覆盖。
+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.soft-pending-compaction-bytes-limit`，则本配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 覆盖；否则保持本配置不变。


Suggested change

+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 直接覆盖。

+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.soft-pending-compaction-bytes-limit`，则本配置项会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 覆盖；否则保持本配置不变。

+ v8.5.4 及之前版本：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项会被 [`storage.flow-control.soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit) 直接覆盖。

+ 从 v8.5.5 和 v9.0.0 起：当开启流控机制（[`storage.flow-control.enable`](/tikv-configuration-file.md#enable) 为 `true`）时，该配置项仅在其值大于 [`storage.flow-control.soft-pending-compaction-bytes-limit`](/tikv-configuration-file.md#soft-pending-compaction-bytes-limit) 时会被 `storage.flow-control.soft-pending-compaction-bytes-limit` 覆盖，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

Use reference-based approach to avoid duplication: - In flow-control config items, use brief note block to reference RocksDB config items - In RocksDB config items, keep detailed version-specific behavior with links This makes future version logic changes easier to maintain (only 2 places instead of 4). Signed-off-by: hhwyt <[email protected]>

hhwyt · 2026-01-09T10:39:58Z

/ok-to-test

hhwyt · 2026-01-09T10:40:19Z

@qiancai PTAL again, thx~

tikv-configuration-file.md

…cf|raftcf)

Synced from: pingcap/docs-cn#21244 Target PR: pingcap#22296 AI Provider: gemini Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

ti-chi-bot · 2026-01-12T07:09:55Z

[LGTM Timeline notifier]

Timeline:

2026-01-09 04:46:40.368246435 +0000 UTC m=+936756.186554867: ☑️ agreed by qiancai.
2026-01-12 07:09:53.226845049 +0000 UTC m=+255037.288709958: ☑️ agreed by Oreoxmt.

qiancai · 2026-01-13T03:33:00Z

/approve

ti-chi-bot · 2026-01-13T03:33:10Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: qiancai

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [qiancai]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ti-chi-bot · 2026-01-13T03:33:17Z

@qiancai: You cannot manually add or delete the cherry pick approval state labels, only I and the tursted members have permission to do so. You can approve it in internal platform.

Details

In response to removing label named approved.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the ti-community-infra/tichi repository.

ti-chi-bot · 2026-01-13T03:42:29Z

In response to a cherrypick label: new pull request created to branch release-8.5: #21270.

Synced from: pingcap/docs-cn#21244 Target PR: pingcap#22296 AI Provider: gemini Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

ti-chi-bot bot added the contribution This PR is from a community contributor. label Jan 7, 2026

ti-chi-bot bot added needs-ok-to-test Indicates a PR created by contributors and need ORG member send '/ok-to-test' to start testing. missing-translation-status This PR does not have translation status info. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jan 7, 2026

qiancai self-assigned this Jan 7, 2026

qiancai added the translation/doing This PR’s assignee is translating this PR. label Jan 7, 2026

ti-chi-bot bot removed the missing-translation-status This PR does not have translation status info. label Jan 7, 2026

ti-chi-bot bot added ok-to-test Indicates a PR is ready to be tested. and removed needs-ok-to-test Indicates a PR created by contributors and need ORG member send '/ok-to-test' to start testing. labels Jan 7, 2026

qiancai added needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3. labels Jan 7, 2026

hbisheng approved these changes Jan 7, 2026

View reviewed changes

qiancai approved these changes Jan 9, 2026

View reviewed changes

ti-chi-bot bot added the needs-1-more-lgtm Indicates a PR needs 1 more LGTM. label Jan 9, 2026

qiancai reviewed Jan 9, 2026

View reviewed changes

tikv-configuration-file.md Outdated Show resolved Hide resolved

qiancai reviewed Jan 9, 2026

View reviewed changes

tikv-configuration-file.md Outdated Show resolved Hide resolved

add empty lines to meet markdown lint requirements

3d7eebd

qiancai reviewed Jan 12, 2026

View reviewed changes

tikv-configuration-file.md Outdated Show resolved Hide resolved

qiancai reviewed Jan 12, 2026

View reviewed changes

tikv-configuration-file.md Outdated Show resolved Hide resolved

Oreoxmt approved these changes Jan 12, 2026

View reviewed changes

ti-chi-bot bot added lgtm and removed needs-1-more-lgtm Indicates a PR needs 1 more LGTM. labels Jan 12, 2026

ti-chi-bot bot added the approved label Jan 13, 2026

qiancai added translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR. and removed translation/doing This PR’s assignee is translating this PR. approved labels Jan 13, 2026

ti-chi-bot bot added the approved label Jan 13, 2026

qiancai added the area/engine Indicates that the Issue or PR belongs to the area of TP storage or Cloud storage. label Jan 13, 2026

ti-chi-bot bot merged commit 5472a3e into pingcap:master Jan 13, 2026
7 checks passed

ti-chi-bot mentioned this pull request Jan 13, 2026

tikv-configuration-file: update flow-control override behavior for v8.5.5 (#21244) #21270

Open

12 tasks

		+ v8.5.4 及之前版本：当 `enable` 的值为 `true` 时，该配置会直接覆盖 `rocksdb.(defaultcf\|writecf\|lockcf).level0-slowdown-writes-trigger`。
		+ 从 v8.5.5 起：当 `enable` 的值为 `true` 时，仅当 `storage.flow-control.l0-files-threshold` 小于 `rocksdb.(defaultcf\|writecf\|lockcf).level0-slowdown-writes-trigger` 时才覆盖该 RocksDB 配置项，以避免在调大流控阈值时削弱 RocksDB 的 compaction 加速机制。

		+ v8.5.4 及之前版本：当 `storage.flow-control.enable` 的值为 `true` 时，该配置项会被 `storage.flow-control.l0-files-threshold` 直接覆盖。
		+ 从 v8.5.5 起：当 `storage.flow-control.enable` 的值为 `true` 时，如果本配置项的值大于 `storage.flow-control.l0-files-threshold`，则本配置项会被 `storage.flow-control.l0-files-threshold` 覆盖；否则保持本配置不变。

tikv-configuration-file: update flow-control override behavior for v8.5.5 #21244

tikv-configuration-file: update flow-control override behavior for v8.5.5 #21244

Conversation

hhwyt commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

Do your changes match any of the following descriptions?

Uh oh!

ti-chi-bot bot commented Jan 7, 2026

Uh oh!

hhwyt commented Jan 7, 2026

Uh oh!

qiancai commented Jan 7, 2026

Uh oh!

ti-chi-bot bot commented Jan 7, 2026

Uh oh!

qiancai left a comment

Choose a reason for hiding this comment

Uh oh!

qiancai Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiancai Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiancai Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiancai Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiancai Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiancai Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hhwyt commented Jan 9, 2026

Uh oh!

hhwyt commented Jan 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ti-chi-bot bot commented Jan 12, 2026

[LGTM Timeline notifier]

Uh oh!

qiancai commented Jan 13, 2026

Uh oh!

ti-chi-bot bot commented Jan 13, 2026

Uh oh!

ti-chi-bot bot commented Jan 13, 2026

Uh oh!

Uh oh!

ti-chi-bot commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hhwyt commented Jan 7, 2026 •

edited

Loading

qiancai Jan 9, 2026 •

edited

Loading

qiancai Jan 9, 2026 •

edited

Loading

qiancai Jan 9, 2026 •

edited

Loading

qiancai Jan 9, 2026 •

edited

Loading

qiancai Jan 9, 2026 •

edited

Loading

qiancai Jan 9, 2026 •

edited

Loading