Skip to content

[WIP] variables: add instance variables #20936

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

[WIP] variables: add instance variables #20936

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
23febbc
variables: add instance variables
xhebox Sep 19, 2025
8f9029a
add
xhebox Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions system-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@ aliases: ['/docs-cn/dev/system-variables/','/docs-cn/dev/reference/configuration

TiDB 系统变量的行为与 MySQL 相似，变量的作用范围可以是会话级别有效 (Session Scope) 或全局范围有效 (Global Scope)。其中：

- 对 `INSTANCE` 作用域变量的更改，设置后**只影响当前实例**。
- 对 `SESSION` 作用域变量的更改，设置后**只影响当前会话**。
- 对 `GLOBAL` 作用域变量的更改，设置后立即生效。如果该变量也有 `SESSION` 作用域，已经连接的所有会话 (包括当前会话) 将继续使用会话当前的 `SESSION` 变量值。
- 对 `GLOBAL` 作用域变量的更改，设置后立即生效。如果该变量也有 `SESSION` 作用域，已经连接的所有会话 (包括当前会话) 将继续使用会话当前的 `SESSION` 变量值。如果改变量也有 `INSTANCE` 作用域，实例将优先使用配置文件中指定的值。
- 要设置变量值，可使用 [`SET` 语句](/sql-statements/sql-statement-set-variable.md)。

```sql
Expand All @@ -20,6 +21,10 @@ SET SESSION tidb_distsql_scan_concurrency = 10;
# 以下两个语句等价地改变一个 Global 变量
SET @@global.tidb_distsql_scan_concurrency = 10;
SET GLOBAL tidb_distsql_scan_concurrency = 10;

# 以下两个语句等价地改变一个 Instance 变量
SET @@instance.tidb_distsql_scan_concurrency = 10;
SET INSTANCE tidb_distsql_scan_concurrency = 10;
```

> **注意：**
Expand Down Expand Up @@ -2215,7 +2220,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1;
>
> Instance Plan Cache 目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 类型：布尔型
Expand Down Expand Up @@ -3371,7 +3376,7 @@ v5.0 后，用户仍可以单独修改以上系统变量（会有废弃警告）

### `tidb_mem_quota_binding_cache` <span class="version-mark">从 v6.0.0 版本开始引入</span>

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 类型：整数型
Expand Down Expand Up @@ -4892,7 +4897,7 @@ EXPLAIN FORMAT='brief' SELECT COUNT(1) FROM t WHERE a = 1 AND b IS NOT NULL;

### `tidb_schema_cache_size` <span class="version-mark">从 v8.0.0 版本开始引入</span>

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 类型：整数型
Expand All @@ -4915,7 +4920,7 @@ EXPLAIN FORMAT='brief' SELECT COUNT(1) FROM t WHERE a = 1 AND b IS NOT NULL;

### `tidb_server_memory_limit` <span class="version-mark">从 v6.4.0 版本开始引入</span>

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 默认值：`80%`
Expand All @@ -4929,7 +4934,7 @@ EXPLAIN FORMAT='brief' SELECT COUNT(1) FROM t WHERE a = 1 AND b IS NOT NULL;

### `tidb_server_memory_limit_gc_trigger` <span class="version-mark">从 v6.4.0 版本开始引入</span>

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 默认值：`70%`
Expand Down Expand Up @@ -5105,7 +5110,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)

### `tidb_stats_cache_mem_quota` <span class="version-mark">从 v6.1.0 版本开始引入</span>

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 类型：整数型
Expand Down Expand Up @@ -5228,7 +5233,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)

### `tidb_stmt_summary_max_stmt_count` <span class="version-mark">从 v4.0 版本开始引入</span>

- 作用域：GLOBAL
- 作用域：GLOBAL | INSTANCE
- 是否持久化到集群：是
- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
- 类型：整数型
Expand Down
49 changes: 49 additions & 0 deletions tidb-configuration-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -978,6 +978,48 @@ TiDB 服务状态相关配置。
+ 可选值：`true`、`false`
+ 该值作为系统变量 [`tidb_enable_stats_owner`](/system-variables.md#tidb_enable_stats_owner-从-v840-版本开始引入) 的初始值。

### `tidb_instance_plan_cache_max_size` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ 指定实例 Plan Cache 的最大内存上限。
+ 该值作为系统变量 [`tidb_instance_plan_cache_max_size`](/system-variables.md#tidb_instance_plan_cache_max_size-从-v840-版本开始引入) 的初始值。
+ 默认值: 125829120 （即 120 MiB）
+ 单位: 字节

### `tidb_mem_quota_binding_cache` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ 这个变量用来设置存放 binding 的缓存的内存使用阈值。
+ 该值作为系统变量 [`tidb_mem_quota_binding_cache`](/system-variables.md#tidb_mem_quota_binding_cache-从-v600-版本开始引入) 的初始值。
+ 默认值：67108864 (64 MiB)
+ 单位：字节

### `tidb_schema_cache_size` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ 这个变量用来控制 TiDB schema 信息缓存的大小。单位为 byte。设置为 0 表示不打开缓存限制功能。如需开启，则需要将该变量的值设置在 [67108864, 9223372036854775807] 范围内，TiDB 将使用该变量的值做为可用的内存上限，并使用 Least Recently Used (LRU) 算法缓存所需的表，有效降低 schema 信息占用的内存。
+ 该值作为系统变量 [`tidb_schema_cache_size`](/system-variables.md#tidb_schema_cache_size-从-v800-版本开始引入) 的初始值。
+ 默认值： 536870912 (512 MiB)
+ 单位：字节

### `tidb_server_memory_limit` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ 该变量指定 TiDB 实例的内存限制。TiDB 会在内存用量达到该限制时，对当前内存用量最高的 SQL 语句进行取消 (Cancel) 操作。在该 SQL 语句被成功 Cancel 掉后，TiDB 会尝试调用 Golang GC 立刻回收内存，以最快速度缓解内存压力。
+ 该值作为系统变量 [`tidb_server_memory_limit`](/system-variables.md#tidb_server_memory_limit-从-v640-版本开始引入) 的初始值。
+ 默认值: 80%

### `tidb_server_memory_limit_gc_trigger` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ TiDB 尝试触发 GC 的阈值。当 TiDB 的内存使用达到 `tidb_server_memory_limit * tidb_server_memory_limit_gc_trigger` 值时，则会主动触发一次 Golang GC。在一分钟之内只会主动触发一次 GC。
+ 该值作为系统变量 [`tidb_server_memory_limit_gc_trigger`](/system-variables.md#tidb_server_memory_limit_gc_trigger-从-v640-版本开始引入) 的初始值。
+ 默认值: 70%
+ 取值范围：`[50%, 99%]`

### `tidb_stats_cache_mem_quota` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ 这个变量用于控制 TiDB 统计信息缓存的内存使用上限。
+ 该值作为系统变量 [`tidb_stats_cache_mem_quota`](/system-variables.md#tidb_stats_cache_mem_quota-从-v640-版本开始引入) 的初始值。
+ 默认值: 0
+ 取值范围: `[0, 1099511627776]`
+ 单位：字节

### `tidb_stmt_summary_enable_persistent` <span class="version-mark">从 v6.6.0 版本开始引入</span>

> **警告：**
Expand Down Expand Up @@ -1019,6 +1061,13 @@ TiDB 服务状态相关配置。
+ 单位：MiB
+ 可结合数据保留时长需求与磁盘空间占用适当调整。

### `tidb_stmt_summary_max_stmt_count` <span class="version-mark">从 v9.0.0 版本开始引入</span>

+ 这个变量用于限制 `statements_summary` 和 `statements_summary_history` 这两张表在内存中可存储的 SQL digest 总数。
+ 该值作为系统变量 [`tidb_stmt_summary_max_stmt_count`](/system-variables.md#tidb_stmt_summary_max_stmt_count-从-v40-版本开始引入) 的初始值。
+ 默认值: 3000
+ 取值范围：`[1, 32767]`

### `tidb_stmt_summary_file_max_backups` <span class="version-mark">从 v6.6.0 版本开始引入</span>

> **警告：**
Expand Down
Loading