Skip to content

tidb: global memory arbitrator mechanism#22882

Open
hfxsd wants to merge 6 commits into
pingcap:masterfrom
hfxsd:solotzg-patch-1-20955
Open

tidb: global memory arbitrator mechanism#22882
hfxsd wants to merge 6 commits into
pingcap:masterfrom
hfxsd:solotzg-patch-1-20955

Conversation

@hfxsd
Copy link
Copy Markdown
Collaborator

@hfxsd hfxsd commented May 13, 2026 •
edited
Loading

This PR is translated from: pingcap/docs-cn#20955

First-time contributors' checklist

What is changed, added or deleted? (Required)

Add documentation for the TiDB global memory arbitrator mode, including:

  • Add a Memory arbitrator mode section to configure-memory-usage.md, describing the working principles, configuration methods, monitoring metrics, and best practices for the standard and priority modes.
  • Add descriptions for the following system variables to system-variables.md:
    • tidb_mem_arbitrator_mode: sets the global memory management mode for a TiDB instance.
    • tidb_mem_arbitrator_query_reserved: sets the amount of memory reserved in advance for a SQL statement before execution.
    • tidb_mem_arbitrator_soft_limit: sets the upper limit of memory allocation for a TiDB instance.
    • tidb_mem_arbitrator_wait_averse: controls the behavior of SQL statements when waiting for memory resources, including the meanings of the values 0 (default, disabled), 1, and nolimit.

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

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions (in Chinese).

  • master (the latest development version)
  • v9.0 (TiDB 9.0 versions)
  • v8.5 (TiDB 8.5 versions)
  • v8.1 (TiDB 8.1 versions)
  • v7.5 (TiDB 7.5 versions)
  • v7.1 (TiDB 7.1 versions)
  • v6.5 (TiDB 6.5 versions)
  • v6.1 (TiDB 6.1 versions)
  • v5.4 (TiDB 5.4 versions)

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

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

@hfxsd hfxsd added translation/from-docs-cn This PR is translated from a PR in pingcap/docs-cn. type/compatibility-or-feature-change This PR involves compatibility changes or feature behavior changes. v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3. labels May 13, 2026
@gemini-code-assist
Copy link
Copy Markdown
Contributor

gemini-code-assist Bot commented May 13, 2026

Note

Gemini is unable to generate a review for this pull request due to the file types involved not being currently supported.

@hfxsd hfxsd self-assigned this May 13, 2026
@ti-chi-bot ti-chi-bot Bot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label May 13, 2026
@github-actions
Auto-sync: Update English docs from Chinese PR
4260fed 
Synced from: pingcap/docs-cn#20955
Target PR: pingcap#22882
AI Provider: azure

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 13, 2026

Auto-sync completed successfully

Source PR: pingcap/docs-cn#20955
Target PR: #22882

English documentation has been updated based on Chinese documentation changes.

@ti-chi-bot ti-chi-bot Bot removed the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label May 13, 2026
@ti-chi-bot
Copy link
Copy Markdown

ti-chi-bot Bot commented May 13, 2026

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from hfxsd. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

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

Details Needs approval from an approver in each of these files:

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 ti-chi-bot Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 13, 2026
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread system-variables.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread system-variables.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread system-variables.md Outdated
hfxsd
hfxsd commented May 14, 2026
View reviewed changes
Comment thread system-variables.md Outdated
solotzg
solotzg approved these changes May 14, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@solotzg solotzg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@ti-chi-bot
Copy link
Copy Markdown

ti-chi-bot Bot commented May 14, 2026

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

Details

In response to this:

lgtm

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.

@hfxsd
Fix memory arbitrator links and wording
9394643 
Update documentation references to use the new "memory arbitrator" naming and corrected anchor targets. Changed cross-doc links in configure-memory-usage.md and system-variables.md (e.g. tidb_mem_arbitrator_mode anchor, memory-arbitrator-mode anchor, and the high-memory alarm anchor) so they point to the renamed headings introduced for v9.0.0 and ensure consistent phrasing across the docs.
hfxsd
hfxsd commented May 21, 2026
View reviewed changes
Comment thread system-variables.md Outdated
hfxsd
hfxsd commented May 21, 2026
View reviewed changes
Comment thread system-variables.md Outdated
hfxsd
hfxsd commented May 21, 2026
View reviewed changes
Comment thread configure-memory-usage.md Outdated
@hfxsd hfxsd requested a review from qiancai May 21, 2026 06:06
qiancai
qiancai approved these changes May 21, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator

@qiancai qiancai left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rest LGTM

Comment thread configure-memory-usage.md

- When the memory usage of a TiDB instance exceeds the limit, TiDB might randomly terminate running SQL statements.
- Memory resources follow a "use-then-report" mechanism, and memory usage is isolated across different SQL statements. As a result, TiDB cannot centrally schedule or control memory resources at the instance level.
- Under high memory pressure, the overhead of Go garbage collection (Garbage Collection, GC) increases significantly, and in severe cases might cause out of memory (OOM) issues.
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Under high memory pressure, the overhead of Go garbage collection (Garbage Collection, GC) increases significantly, and in severe cases might cause out of memory (OOM) issues.
- Under high memory pressure, the overhead of Go garbage collection (GC) increases significantly, and in severe cases might cause out of memory (OOM) issues.

Comment thread configure-memory-usage.md
- [`tidb_mem_quota_query`](/system-variables.md#tidb_mem_quota_query)
- [`max_execution_time`](/system-variables.md#max_execution_time)

When memory resources are insufficient or there is an OOM risk, the arbitrator can reclaim memory resources by terminating SQL, but it does not terminate `DDL`, `DCL`, or `TCL` SQL types. Terminated SQL returns error code `8180` to the client. The error format is: `Query execution was stopped by the global memory arbitrator [reason=?, path=?] [conn=?]`. The related fields are explained as follows:
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When memory resources are insufficient or there is an OOM risk, the arbitrator can reclaim memory resources by terminating SQL, but it does not terminate `DDL`, `DCL`, or `TCL` SQL types. Terminated SQL returns error code `8180` to the client. The error format is: `Query execution was stopped by the global memory arbitrator [reason=?, path=?] [conn=?]`. The related fields are explained as follows:
When memory resources are insufficient or there is an OOM risk, the arbitrator can reclaim memory resources by terminating SQL statements, but it does not terminate `DDL`, `DCL`, or `TCL` SQL statements. Terminated SQL returns error code `8180` to the client. The error format is: `Query execution was stopped by the global memory arbitrator [reason=?, path=?] [conn=?]`. The related fields are explained as follows:

Comment thread configure-memory-usage.md
Before TiDB v9.0.0, the [memory control mechanism](#configure-the-memory-usage-threshold-of-a-tidb-server-instance) has the following issues:

- When the memory usage of a TiDB instance exceeds the limit, TiDB might randomly terminate running SQL statements.
- Memory resources follow a "use-then-report" mechanism, and memory usage is isolated across different SQL statements. As a result, TiDB cannot centrally schedule or control memory resources at the instance level.
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Memory resources follow a "use-then-report" mechanism, and memory usage is isolated across different SQL statements. As a result, TiDB cannot centrally schedule or control memory resources at the instance level.
- Memory resources follow a "use first and report later" mechanism, and memory usage is isolated across different SQL statements. As a result, TiDB cannot centrally schedule or control memory resources at the instance level.

Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

reason: to be consistent with the description of tidb_mem_arbitrator_mode

Comment thread system-variables.md
- Unit: Threads
- This variable is used to set the maximum concurrency for TiFlash to execute a request. The default value is `-1`, indicating that this system variable is invalid and the maximum concurrency depends on the setting of the TiFlash configuration `profiles.default.max_threads`. When the value is `0`, the maximum number of threads is automatically configured by TiFlash.

### `tidb_mem_arbitrator_mode` <span class="version-mark">New in v9.0.0</span>
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### `tidb_mem_arbitrator_mode` <span class="version-mark">New in v9.0.0</span>
### tidb_mem_arbitrator_mode <span class="version-mark">New in v9.0.0</span>

Comment thread system-variables.md
- `standard`: Enables standard memory arbitrator mode. When SQL needs to use memory resources, it first subscribes to the memory arbitrator and allocates memory resources only after the subscription succeeds. If the subscription fails, the SQL execution is terminated.
- `priority`: Enables priority-based memory arbitrator mode. When SQL needs to use memory resources, it first subscribes to the memory arbitrator and allocates memory resources only after the subscription succeeds. TiDB handles memory resource subscription requests according to the SQL [resource group priority](/information-schema/information-schema-resource-groups.md).

### `tidb_mem_arbitrator_query_reserved` <span class="version-mark">New in v9.0.0</span>
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### `tidb_mem_arbitrator_query_reserved` <span class="version-mark">New in v9.0.0</span>
### tidb_mem_arbitrator_query_reserved <span class="version-mark">New in v9.0.0</span>

Comment thread system-variables.md
- Range: `[0, 9223372036854775807]`
- When [memory arbitrator mode](/configure-memory-usage.md#memory-arbitrator-mode) is enabled, this variable controls the amount of memory resources that SQL pre-subscribes to from the memory arbitrator before execution. For more information, see [TiDB memory control](/configure-memory-usage.md#manually-ensuring-memory-safety).

### `tidb_mem_arbitrator_soft_limit` <span class="version-mark">New in v9.0.0</span>
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### `tidb_mem_arbitrator_soft_limit` <span class="version-mark">New in v9.0.0</span>
### tidb_mem_arbitrator_soft_limit <span class="version-mark">New in v9.0.0</span>

Comment thread system-variables.md
- Floating-point number `(0, 1]`: Specifies the upper limit of memory resources as a ratio relative to [`tidb_server_memory_limit`](/system-variables.md#tidb_server_memory_limit-new-in-v640). For example, `0.8` means the upper limit of memory resources is `tidb_server_memory_limit * 0.8`.
- Integer `(1, 9223372036854775807]`: Specifies the number of bytes.

### `tidb_mem_arbitrator_wait_averse` <span class="version-mark">New in v9.0.0</span>
Copy link
Copy Markdown
Collaborator

@qiancai qiancai May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### `tidb_mem_arbitrator_wait_averse` <span class="version-mark">New in v9.0.0</span>
### tidb_mem_arbitrator_wait_averse <span class="version-mark">New in v9.0.0</span>

@ti-chi-bot ti-chi-bot Bot added the needs-1-more-lgtm Indicates a PR needs 1 more LGTM. label May 21, 2026
@ti-chi-bot
Copy link
Copy Markdown

ti-chi-bot Bot commented May 21, 2026

[LGTM Timeline notifier]

Timeline:

  • 2026-05-21 08:36:08.887872794 +0000 UTC m=+26099.528729607: ☑️ agreed by qiancai.

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

Reviewers

@solotzg solotzg solotzg approved these changes

@qiancai qiancai qiancai approved these changes

Assignees

@hfxsd hfxsd

Labels

needs-1-more-lgtm Indicates a PR needs 1 more LGTM. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. translation/from-docs-cn This PR is translated from a PR in pingcap/docs-cn. type/compatibility-or-feature-change This PR involves compatibility changes or feature behavior changes. v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@hfxsd @solotzg @qiancai