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 paging size of 4 MiB for eligible Resource Control configurations (with a non-burstable active resource group).
  • Expanded documentation for tidb_paging_size_bytes, clarifying when the setting applies.
  • Improved support for optimizer hints related to paging size.
• Bug Fixes
  • Fixed SET @@tidb_paging_size_bytes=default so it now returns 4,194,304 instead of 0.
• Tests
  • Updated integration test expectations for the new default paging size.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: a97d74cc-39d6-4f98-9193-a5e82ac33716

📥 Commits

Reviewing files that changed from the base of the PR and between 0eba91e and a71ca6e.

📒 Files selected for processing (5)

• pkg/bindinfo/tests/BUILD.bazel
• pkg/sessionctx/vardef/tidb_vars.go
• pkg/sessionctx/variable/setvar_affect.go
• pkg/sessionctx/variable/sysvar.go
• tests/integrationtest/r/sessionctx/setvar.result

💤 Files with no reviewable changes (1)

• pkg/sessionctx/variable/setvar_affect.go

🚧 Files skipped from review as they are similar to previous changes (4)

• pkg/bindinfo/tests/BUILD.bazel
• tests/integrationtest/r/sessionctx/setvar.result
• pkg/sessionctx/variable/sysvar.go
• pkg/sessionctx/vardef/tidb_vars.go

---

📝 Walkthrough

Walkthrough

The tidb_paging_size_bytes default changes from disabled to 4 MiB. Resource Control conditions are documented, hint verification metadata is updated, integration expectations change, and the bind information test target gains one shard.

Changes

Paging size configuration

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

Test sharding

Layer / File(s)	Summary
Increase test target sharding pkg/bindinfo/tests/BUILD.bazel	The tests_test Bazel target shard count increases from 25 to 26.

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

Possibly related PRs

• pingcap/tidb#68091: Modifies related paging-size system-variable and hint-update wiring.
• pingcap/tidb#69633: Updates runtime handling of tidb_paging_size_bytes.
• pingcap/tidb#69830: Introduces related paging-size system-variable wiring.

Suggested reviewers: yudongusa, cfzjywx, yuhaozhang00

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,
Tests hop to the new value today.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: changing the paging size bytes default to 4 MiB.
Description check	✅ Passed	The description matches the template with issue number, problem summary, change details, tests, side effects, docs, and release note.
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.

✨ 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 73.9508%. Comparing base (66be7a6) to head (a71ca6e).

Additional details and impacted files

@@               Coverage Diff                @@
##             master     #69868        +/-   ##
================================================
- Coverage   76.3193%   73.9508%   -2.3686%     
================================================
  Files          2041       2058        +17     
  Lines        559929     578636     +18707     
================================================
+ Hits         427334     427906       +572     
- Misses       131694     150399     +18705     
+ Partials        901        331       -570     

Flag	Coverage Δ
integration	40.7112% <100.0000%> (+1.0059%)	⬆️

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]

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

[0xPoe]

Thanks!

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: 0xPoe, yudongusa, YuhaoZhang00

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 [0xPoe]
• pkg/bindinfo/OWNERS [0xPoe]
• pkg/sessionctx/vardef/OWNERS [yudongusa]
• pkg/sessionctx/variable/OWNERS [yudongusa]

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]

[LGTM Timeline notifier]

Timeline:

• 2026-07-17 16:18:35.679611998 +0000 UTC m=+989701.715707044: ☑️ agreed by yudongusa.
• 2026-07-18 08:38:59.856481538 +0000 UTC m=+1048525.892576584: ☑️ agreed by 0xPoe.