resource control: support more mode for BURSTABLE

information-schema/information-schema-resource-groups.md

@@ -13,15 +13,17 @@ DESC resource_groups;
 ```
 
 ```sql
-+------------+-------------+------+------+---------+-------+
-| Field      | Type        | Null | Key  | Default | Extra |
-+------------+-------------+------+------+---------+-------+
-| NAME       | varchar(32) | NO   |      | NULL    |       |
-| RU_PER_SEC | bigint(21)  | YES  |      | NULL    |       |
-| PRIORITY   | varchar(6)  | YES  |      | NULL    |       |
-| BURSTABLE  | varchar(3)  | YES  |      | NULL    |       |
-+------------+-------------+------+------+---------+-------+
-3 rows in set (0.00 sec)
++-------------+--------------+------+------+---------+-------+
+| Field       | Type         | Null | Key  | Default | Extra |
++-------------+--------------+------+------+---------+-------+
+| NAME        | varchar(32)  | NO   |      | NULL    |       |
+| RU_PER_SEC  | varchar(21)  | YES  |      | NULL    |       |
+| PRIORITY    | varchar(6)   | YES  |      | NULL    |       |
+| BURSTABLE   | varchar(3)   | YES  |      | NULL    |       |
+| QUERY_LIMIT | varchar(256) | YES  |      | NULL    |       |
+| BACKGROUND  | varchar(256) | YES  |      | NULL    |       |
++-------------+--------------+------+------+---------+-------+
+6 rows in set (0.00 sec)
 ```
 
 ## 示例
@@ -31,11 +33,11 @@ SELECT * FROM information_schema.resource_groups; -- 查看资源组，TiDB 默
 ```
 
 ```sql
-+---------+------------+----------+-----------+
-| NAME    | RU_PER_SEC | PRIORITY | BURSTABLE |
-+---------+------------+----------+-----------+
-| default | UNLIMITED  | MEDIUM   | YES       |
-+---------+------------+----------+-----------+
++---------+------------+----------+----------------+-------------+------------+
+| NAME    | RU_PER_SEC | PRIORITY | BURSTABLE      | QUERY_LIMIT | BACKGROUND |
++---------+------------+----------+----------------+-------------+------------+
+| default | UNLIMITED  | MEDIUM   | YES(UNLIMITED) | NULL        | NULL       |
++---------+------------+----------+----------------+-------------+------------+
 ```
 
 ```sql
@@ -64,11 +66,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME = 'rg1'; -- 查看
 ```
 
 ```sql
-+------+------------+----------+-----------+-------------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT |
-+------+------------+----------+-----------+-------------+
-| rg1  | 1000       | MEDIUM   | NO        | NULL        |
-+------+------------+----------+-----------+-------------+
++------+------------+----------+-----------+-------------+------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT | BACKGROUND |
++------+------------+----------+-----------+-------------+------------+
+| rg1  | 1000       | MEDIUM   | NO        | NULL        | NULL       |
++------+------------+----------+-----------+-------------+------------+
 1 row in set (0.00 sec)
 ```
 
@@ -77,8 +79,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME = 'rg1'; -- 查看
 * `NAME`：资源组名称。
 * `RU_PER_SEC`：资源组的回填速度，单位为每秒回填的 [Request Unit (RU)](/tidb-resource-control-ru-groups.md#什么是-request-unit-ru) 数量。
 * `PRIORITY`：任务在 TiKV 上处理的绝对优先级。不同的资源按照 `PRIORITY` 的设置进行调度，`PRIORITY` 高的任务会被优先调度。如果资源组的 `PRIORITY` 相同，则会根据 `RU_PER_SEC` 的配置按比例调度。如果不指定 `PRIORITY`，资源组的默认优先级为 `MEDIUM`。
-* `BURSTABLE`：是否允许此资源组超额使用剩余的系统资源。
+* `BURSTABLE`：是否允许此资源组超额使用剩余的系统资源。支持以下三种模式，如果没有为 `BURSTABLE` 指定目标值，将默认启用 `MODERATED` 模式。
+    - `OFF`：表示不允许此资源组超额使用剩余的系统资源；
+    - `MODERATED`：表示有限度地允许此资源组超额使用剩余的系统资源，优先保证资源组限额内的资源得到分配；
+    - `UNLIMITED`：表示无限度地允许此资源组超额使用剩余的系统资源，与限额内资源同等竞争。
 
 > **注意：**
 >
-> TiDB 集群在初始化时会自动创建 `default` 资源组，其 `RU_PER_SEC` 的默认值为 `UNLIMITED` (等同于 `INT` 类型最大值，即 `2147483647`)，且为 `BURSTABLE` 模式。所有未绑定资源组的请求都将自动绑定至此资源组。在新建配置其他资源组时，建议根据实际情况修改 `default` 资源组的配置。
+> TiDB 集群在初始化时会自动创建 `default` 资源组，其 `RU_PER_SEC` 的默认值为 `UNLIMITED` (等同于 `INT` 类型最大值，即 `2147483647`)，且 `BURSTABLE` 为 `UNLIMITED` 模式。所有未绑定资源组的语句将自动绑定至该资源组。`default` 资源组不支持删除，但支持修改其 RU 配置。

sql-statements/sql-statement-alter-resource-group.md

@@ -29,7 +29,9 @@ DirectResourceGroupOption ::=
     "RU_PER_SEC" EqOpt LengthNum
 |   "PRIORITY" EqOpt ResourceGroupPriorityOption
 |   "BURSTABLE"
-|   "BURSTABLE" EqOpt Boolean
+|   "BURSTABLE" EqOpt "MODERATED"
+|   "BURSTABLE" EqOpt "UNLIMITED"
+|   "BURSTABLE" EqOpt "OFF"
 |   "QUERY_LIMIT" EqOpt '(' ResourceGroupRunawayOptionList ')'
 |   "QUERY_LIMIT" EqOpt '(' ')'
 |   "QUERY_LIMIT" EqOpt "NULL"
@@ -80,7 +82,7 @@ TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-
 |---------------|--------------|--------------------------------------|
 | `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU。 |
 | `PRIORITY`    | 任务在 TiKV 上处理的绝对优先级  | `PRIORITY = HIGH` 表示优先级高。若未指定则默认为 `MEDIUM`。 |
-| `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 |
+| `BURSTABLE`   | 是否允许此资源组超额使用剩余的系统资源 | 分为三种模式：`OFF`，表示不允许此资源组超额使用剩余的系统资源；`MODERATED`，表示有限度地允许此资源组超额使用剩余的系统资源；`UNLIMITED`，表示无限度地允许此资源组超额使用剩余的系统资源。如果没有为 `BURSTABLE` 指定目标值，将默认启用 `MODERATED` 模式。 |
 | `QUERY_LIMIT` | 当查询执行满足该条件时，识别该查询为 Runaway Query 并执行相应的操作 | `QUERY_LIMIT=(EXEC_ELAPSED='60s', ACTION=KILL, WATCH=EXACT DURATION='10m')` 表示当执行时间超过 60 秒后识别为 Runaway Query，对该查询执行终止操作，并在 10 分钟内对同样的 SQL 直接执行终止操作。`QUERY_LIMIT=()` 或 `QUERY_LIMIT=NULL` 则表示不进行 Runaway 控制。具体参数介绍参见[管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control-runaway-queries.md)。 ｜
 | `BACKGROUND`  | 后台任务相关的设置。具体参数介绍参见[管理后台任务](/tidb-resource-control-background-tasks.md) | `BACKGROUND=(TASK_TYPES="br,stats", UTILIZATION_LIMIT=30)` 表示将备份恢复和收集统计信息相关的任务作为后台任务调度，并且后台任务最多可以使用 TiKV 30% 的资源。 |
 
@@ -164,11 +166,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='default';
 ```
 
 ```sql
-+---------+------------+----------+-----------+-------------+-------------------------------------------+
-| NAME    | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT | BACKGROUND                                |
-+---------+------------+----------+-----------+-------------+-------------------------------------------+
-| default | UNLIMITED  | MEDIUM   | YES       | NULL        | TASK_TYPES='br,ddl', UTILIZATION_LIMIT=30 |
-+---------+------------+----------+-----------+-------------+-------------------------------------------+
++---------+------------+----------+----------------+-------------+------------+
+| NAME    | RU_PER_SEC | PRIORITY | BURSTABLE      | QUERY_LIMIT | BACKGROUND |
++---------+------------+----------+----------------+-------------+------------+
+| default | UNLIMITED  | MEDIUM   | YES(UNLIMITED) | NULL        | NULL       |
++---------+------------+----------+----------------+-------------+------------+
 1 rows in set (1.30 sec)
 ```
 

sql-statements/sql-statement-create-resource-group.md

@@ -29,7 +29,9 @@ DirectResourceGroupOption ::=
     "RU_PER_SEC" EqOpt stringLit
 |   "PRIORITY" EqOpt ResourceGroupPriorityOption
 |   "BURSTABLE"
-|   "BURSTABLE" EqOpt Boolean
+|   "BURSTABLE" EqOpt "MODERATED"
+|   "BURSTABLE" EqOpt "UNLIMITED"
+|   "BURSTABLE" EqOpt "OFF"
 |   "QUERY_LIMIT" EqOpt '(' ResourceGroupRunawayOptionList ')'
 |   "QUERY_LIMIT" EqOpt '(' ')'
 |   "QUERY_LIMIT" EqOpt "NULL"
@@ -77,13 +79,13 @@ TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-
 |---------------|--------------|--------------------------------------|
 | `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU。 |
 | `PRIORITY`    | 任务在 TiKV 上处理的绝对优先级  | `PRIORITY = HIGH` 表示优先级高。若未指定，则默认为 `MEDIUM`。 |
-| `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 | 
+| `BURSTABLE`   | 是否允许此资源组超额使用剩余的系统资源 | 分为三种模式：`OFF`，表示不允许此资源组超额使用剩余的系统资源；`MODERATED`，表示有限度地允许此资源组超额使用剩余的系统资源；`UNLIMITED`，表示无限度地允许此资源组超额使用剩余的系统资源。如果没有为 `BURSTABLE` 指定目标值，将默认启用 `MODERATED` 模式。 |
 | `QUERY_LIMIT` | 当查询执行满足该条件时，识别该查询为 Runaway Query 并进行相应的控制 | `QUERY_LIMIT=(EXEC_ELAPSED='60s', ACTION=KILL, WATCH=EXACT DURATION='10m')` 表示当执行时间超过 60 秒后识别为 Runaway Query，对该查询执行终止操作，并在 10 分钟内对同样的 SQL 直接执行终止操作。`QUERY_LIMIT=()` 或 `QUERY_LIMIT=NULL` 则表示不进行 Runaway 控制。具体参数介绍详见[管理资源消耗超出预期的查询 (Runaway Queries)](/tidb-resource-control-runaway-queries.md)。 ｜
 
 > **注意：**
 >
 > - `CREATE RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 设置为 `ON` 时才能执行。
-> - TiDB 集群在初始化时会自动创建 `default` 资源组，其 `RU_PER_SEC` 的默认值为 `UNLIMITED` (等同于 `INT` 类型最大值，即 `2147483647`)，且为 `BURSTABLE` 模式。所有未绑定资源组的请求都将自动绑定至此资源组。在新建配置其他资源组时，建议根据实际情况修改 `default` 资源组的配置。
+> - TiDB 集群在初始化时会自动创建 `default` 资源组，其 `RU_PER_SEC` 的默认值为 `UNLIMITED` (等同于 `INT` 类型最大值，即 `2147483647`)，且 `BURSTABLE` 为 `UNLIMITED` 模式。所有未绑定资源组的语句将自动绑定至该资源组。`default` 资源组不支持删除，但支持修改其 RU 配置。
 > - 目前仅 `default` 资源组支持修改 `BACKGROUND` 相关设置。
 
 ## 示例
@@ -123,12 +125,12 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1' or NAME = 'rg
 ```
 
 ```sql
-+------+------------+----------+-----------+---------------------------------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT                     |
-+------+------------+----------+-----------+---------------------------------+
-| rg1  | 100        | HIGH     | YES       | NULL                            |
-| rg2  | 200        | MEDIUM   | NO        | EXEC_ELAPSED=100ms, ACTION=KILL |
-+------+------------+----------+-----------+---------------------------------+
++------+------------+----------+----------------+-----------------------------------+------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE      | QUERY_LIMIT                       | BACKGROUND |
++------+------------+----------+----------------+-----------------------------------+------------+
+| rg1  | 100        | HIGH     | YES(MODERATED) | NULL                              | NULL       |
+| rg2  | 200        | MEDIUM   | NO             | EXEC_ELAPSED='100ms', ACTION=KILL | NULL       |
++------+------------+----------+----------------+-----------------------------------+------------+
 2 rows in set (1.30 sec)
 ```
 

sql-statements/sql-statement-drop-resource-group.md

@@ -51,11 +51,11 @@ SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
 ```
 
 ```sql
-+------+------------+----------+-----------+-------------+
-| NAME | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT |
-+------+------------+----------+-----------+-------------+
-| rg1  | 500        | MEDIUM   | YES       | NULL        |
-+------+------------+----------+-----------+-------------+
++------+------------+----------+----------------+-------------+------------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE      | QUERY_LIMIT | BACKGROUND |
++------+------------+----------+----------------+-------------+------------+
+| rg1  | 500        | MEDIUM   | YES(MODERATED) | NULL        | NULL       |
++------+------------+----------+----------------+-------------+------------+
 1 row in set (0.01 sec)
 ```
 

tidb-resource-control-background-tasks.md

@@ -61,11 +61,11 @@ summary: 介绍如何通过资源管控 (Resource Control) 控制后台任务。
     输出结果如下：
 
     ```
-    +---------+------------+----------+-----------+-------------+-------------------------------------------+
-    | NAME    | RU_PER_SEC | PRIORITY | BURSTABLE | QUERY_LIMIT | BACKGROUND                                |
-    +---------+------------+----------+-----------+-------------+-------------------------------------------+
-    | default | UNLIMITED  | MEDIUM   | YES       | NULL        | TASK_TYPES='br,ddl', UTILIZATION_LIMIT=30 |
-    +---------+------------+----------+-----------+-------------+-------------------------------------------+
+    +---------+------------+----------+----------------+-------------+------------+
+    | NAME    | RU_PER_SEC | PRIORITY | BURSTABLE      | QUERY_LIMIT | BACKGROUND |
+    +---------+------------+----------+----------------+-------------+------------+
+    | default | UNLIMITED  | MEDIUM   | YES(UNLIMITED) | NULL        | NULL       |
+    +---------+------------+----------+----------------+-------------+------------+
     ```
 
 5. 如果希望将当前会话里的任务显式标记为后台类型，你可以使用 `tidb_request_source_type` 显式指定任务类型，如：

tidb-resource-control-ru-groups.md

@@ -133,7 +133,7 @@ Request Unit (RU) 是 TiDB 对 CPU、IO 等系统资源的统一抽象的计量
 
 下面举例说明如何创建资源组。
 
-1. 创建 `rg1` 资源组，限额是每秒 500 RU，并且允许这个资源组的应用超额占用资源。
+1. 创建 `rg1` 资源组，限额是每秒 500 RU，并且允许这个资源组的应用超额占用资源。如果不特意指定 `BURSTABLE` 模式，则默认启用 `MODERATED` 模式。
 
     ```sql
     CREATE RESOURCE GROUP IF NOT EXISTS rg1 RU_PER_SEC = 500 BURSTABLE;
@@ -151,6 +151,12 @@ Request Unit (RU) 是 TiDB 对 CPU、IO 等系统资源的统一抽象的计量
     CREATE RESOURCE GROUP IF NOT EXISTS rg3 RU_PER_SEC = 100 PRIORITY = HIGH;
     ```
 
+4. 创建 `rg4` 资源组，限额是每秒 500 RU，并且允许这个资源组的应用超额占用资源，其 `BURSTABLE` 模式为 `UNLIMITED`。
+
+    ```sql
+    CREATE RESOURCE GROUP IF NOT EXISTS rg4 RU_PER_SEC = 500 BURSTABLE=UNLIMITED;
+    ```
+
 ### 绑定资源组
 
 TiDB 支持如下三个级别的资源组设置：
@@ -180,7 +186,7 @@ ALTER USER usr2 RESOURCE GROUP rg2;
 > **注意：**
 >
 > - 使用 `CREATE USER` 或者 `ALTER USER` 将用户绑定到资源组后，只会对该用户新建的会话生效，不会对该用户已有的会话生效。
-> - TiDB 集群在初始化时会自动创建 `default` 资源组，其 `RU_PER_SEC` 的默认值为 `UNLIMITED` (等同于 `INT` 类型最大值，即 `2147483647`)，且为 `BURSTABLE` 模式。对于没有绑定资源组的语句会自动绑定至此资源组。此资源组不支持删除，但允许修改其 RU 的配置。
+> - TiDB 集群在初始化时会自动创建 `default` 资源组，其 `RU_PER_SEC` 的默认值为 `UNLIMITED` (等同于 `INT` 类型最大值，即 `2147483647`)，且 `BURSTABLE` 为 `UNLIMITED` 模式。所有未绑定资源组的语句将自动绑定至该资源组。`default` 资源组不支持删除，但支持修改其 RU 配置。
 
 要解除用户与资源组的绑定，只需将其重新绑定到 `default` 资源组即可，如下所示：