sessionctx: default paging size bytes to 4 MiB

[JmPotato]

What problem does this PR solve?

Issue Number: ref #68085

Problem Summary:

tidb_paging_size_bytes currently defaults to 0, leaving byte-budget paging disabled unless it is explicitly configured.

Regression testing with paging enabled found no material performance regression in the tested cap-bound and under-cap TPC-C, FullScan, and Join workloads. Among the tested 1, 2, 4, 8, and 16 MiB candidates, 4 MiB had the lowest weighted score and the best overall balance across throughput, tail latency, RU stability, RPC overhead, CPU, RU efficiency, and worst-case behavior. It was not the winner of every individual metric; the recommendation is a robust default for the tested workload matrix rather than a claim of a universal optimum.

What changed and how does it work?

• Change the default value of tidb_paging_size_bytes from 0 to 4 MiB.
• Document the workload coverage and selection rationale next to the default constant for future reviewers.
• Declare SET_VAR hint support directly in the system-variable definition instead of only through the centralized support map.
• Update the existing integration-test expectations for the initial and reset-to-default values.

Setting this variable does not enable byte-budget paging for every workload. TiDB forwards the byte budget only when Resource Control is enabled and the active Resource Group is configured as non-burstable (has limited burst). Users can still explicitly set the variable to 0 to disable byte-budget paging.

Check List

Tests

• Unit test
• Integration test
• Manual test (add detailed scripts or steps below)
• No need to test

  • I checked and no code files have been changed.

Validated locally:

• (cd tests/integrationtest && ./run-tests.sh -r sessionctx/setvar) (709 cases passed)
• make lint
• git diff --check upstream/master...HEAD

Side effects

• Performance regression: Consumes more CPU
• Performance regression: Consumes more Memory
• Breaking backward compatibility

Documentation

• Affects user behaviors
• Contains syntax changes
• Contains variable changes
• Contains experimental features
• Changes MySQL compatibility

Release note

Please refer to Release Notes Language Style Guide to write a quality release note.

`tidb_paging_size_bytes` now defaults to 4 MiB, enabling byte-budget paging for resource groups with limited burst. Set it to `0` to disable byte-budget paging explicitly.

Summary by CodeRabbit

• New Features

  • Enabled a default 4 MiB paging size for eligible Resource Control configurations.
  • Added clearer documentation explaining when paging size settings apply.
  • Allowed the paging size setting to be updated through supported optimizer hints.

• Bug Fixes

  • Corrected the reported value when resetting the paging size setting to its default.

[coderabbitai]

📝 Walkthrough

Walkthrough

The tidb_paging_size_bytes default changes from disabled to 4 MiB. Its Resource Control conditions are documented, system-variable hint verification is updated, and integration-test expectations reflect the new default.

Changes

Paging size configuration

Layer / File(s)	Summary
Update default and session expectations pkg/sessionctx/vardef/tidb_vars.go, pkg/sessionctx/variable/sysvar.go, tests/integrationtest/r/sessionctx/setvar.result	DefPagingSizeBytes changes to 4 MiB, Resource Control applicability is documented, hint verification is enabled, and default-value test results change to 4194304.
Configure hint update verification pkg/sessionctx/variable/setvar_affect.go	tidb_paging_size_bytes is removed from the legacy hint-verification map.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• pingcap/tidb#68091: Modifies the same system-variable plumbing and hint-update behavior.
• pingcap/tidb#69633: Concerns the paging-size value and its runtime handling.
• pingcap/tidb#69830: Implements related paging-byte-budget behavior.

Suggested reviewers: yudongusa, qw4990, guo-shaoge

Poem

I’m a rabbit with bytes in my pack,
Four MiB now rides on the track.
Resource groups guide the way,
Hint checks keep settings in play,
And tests hop to the new value today.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly states the main change: default paging size bytes to 4 MiB.
Description check	✅ Passed	The description follows the template and includes the required issue link, summary, tests, side effects, documentation, and release note.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.0034%. Comparing base (f994e8d) to head (cf002db).

Additional details and impacted files

@@               Coverage Diff                @@
##             master     #69868        +/-   ##
================================================
- Coverage   76.3208%   74.0034%   -2.3174%     
================================================
  Files          2041       2056        +15     
  Lines        559977     578246     +18269     
================================================
+ Hits         427379     427922       +543     
- Misses       131697     149999     +18302     
+ Partials        901        325       -576     

Flag	Coverage Δ
integration	40.7326% <100.0000%> (+1.0273%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
dumpling	60.4471% <ø> (ø)
parser	∅ <ø> (∅)
br	47.4060% <ø> (-15.3154%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ti-chi-bot]

@JmPotato: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-integration-realcluster-test-next-gen	cf002db	link	true	/test pull-integration-realcluster-test-next-gen
pull-build-next-gen	cf002db	link	true	/test pull-build-next-gen
idc-jenkins-ci-tidb/build	cf002db	link	true	/test build
idc-jenkins-ci-tidb/unit-test	cf002db	link	true	/test unit-test
pull-unit-test-next-gen	cf002db	link	true	/test pull-unit-test-next-gen
idc-jenkins-ci-tidb/check_dev_2	cf002db	link	true	/test check-dev2

Full PR test history. Your PR dashboard.

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. I understand the commands that are listed here.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: YuhaoZhang00
Once this PR has been reviewed and has the lgtm label, please assign terry1purcell for approval. 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:

• OWNERS
• pkg/sessionctx/vardef/OWNERS
• pkg/sessionctx/variable/OWNERS

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]

@YuhaoZhang00: 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.