resource_control: updates some changes about resource group in 7.0 (#…

…13310)

TOC.md

@@ -698,6 +698,7 @@
       - [`BACKUP`](/sql-statements/sql-statement-backup.md)
       - [`BATCH`](/sql-statements/sql-statement-batch.md)
       - [`BEGIN`](/sql-statements/sql-statement-begin.md)
+      - [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md)
       - [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md)
       - [`CHANGE DRAINER`](/sql-statements/sql-statement-change-drainer.md)
       - [`CHANGE PUMP`](/sql-statements/sql-statement-change-pump.md)
@@ -763,6 +764,7 @@
       - [`SET DEFAULT ROLE`](/sql-statements/sql-statement-set-default-role.md)
       - [`SET [NAMES|CHARACTER SET]`](/sql-statements/sql-statement-set-names.md)
       - [`SET PASSWORD`](/sql-statements/sql-statement-set-password.md)
+      - [`SET RESOURCE GROUP`](/sql-statements/sql-statement-set-resource-group.md)
       - [`SET ROLE`](/sql-statements/sql-statement-set-role.md)
       - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md)
       - [`SET [GLOBAL|SESSION] <variable>`](/sql-statements/sql-statement-set-variable.md)

functions-and-operators/information-functions.md

@@ -13,6 +13,7 @@ TiDB 支持使用 MySQL 5.7 中提供的大部分[信息函数](https://dev.mysq
 | ------ | ---------------------------------------- |
 | [`BENCHMARK()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_benchmark) | 循环执行一个表达式 |
 | [`CONNECTION_ID()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_connection-id) | 返回当前连接的连接 ID (线程 ID)                     |
+| `CURRENT_RESOURCE_GROUP()` | 返回当前连接的资源组名 |
 | [`CURRENT_USER()`, `CURRENT_USER`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_current-user) | 返回当前用户的用户名和主机名                           |
 | [`DATABASE()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_database) | 返回默认(当前)的数据库名                            |
 | [`FOUND_ROWS()`](https://dev.mysql.com/doc/refman/5.7/en/information-functions.html#function_found-rows) | 该函数返回对于一个包含 LIMIT 的 SELECT 查询语句，在不包含 LIMIT 的情况下回返回的记录数 |

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

@@ -22,6 +22,7 @@ DESC resource_groups;
 +------------+-------------+------+------+---------+-------+
 | 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)
@@ -33,23 +34,24 @@ DESC resource_groups;
 mysql> CREATE RESOURCE GROUP rg1 RU_PER_SEC=1000; -- 创建资源组 rg1
 Query OK, 0 rows affected (0.34 sec)
 mysql> SHOW CREATE RESOURCE GROUP rg1; -- 显示 rg1 资源组的定义
-+----------------+---------------------------------------------+
-| Resource_Group | Create Resource Group                       |
-+----------------+---------------------------------------------+
-| rg1            | CREATE RESOURCE GROUP `rg1` RU_PER_SEC=1000 |
-+----------------+---------------------------------------------+
++----------------+---------------------------------------------------------------+
+| Resource_Group | Create Resource Group                                         |
++----------------+---------------------------------------------------------------+
+| rg1            | CREATE RESOURCE GROUP `rg1` RU_PER_SEC=1000 PRIORITY="MEDIUM" |
++----------------+---------------------------------------------------------------+
 1 row in set (0.00 sec)
 mysql> SELECT * FROM information_schema.resource_groups WHERE NAME = 'rg1';
-+------+------------+-----------+
-| NAME | RU_PER_SEC | BURSTABLE |
-+------+------------+-----------+
-| rg1  |       1000 | NO        |
-+------+------------+-----------+
++------+------------+----------+-----------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
++------+------------+----------+-----------+
+| rg1  |       1000 | MEDIUM   | NO        |
++------+------------+----------+-----------+
 1 row in set (0.00 sec)
 ```
 
 `RESOURCE_GROUPS` 表中列的含义如下：
 
 * `NAME`：资源组名称。
 * `RU_PER_SEC`：资源组的回填速度，单位为每秒回填的 [Request Unit (RU)](/tidb-resource-control.md#什么是-request-unit-ru) 数量。
+* `PRIORITY`：任务在 TiKV 上处理的绝对优先级。不同的资源按照 `PRIORITY` 的设置进行调度，`PRIORITY` 高的任务会被优先调度。如果资源组的 `PRIORITY` 相同，则会根据 `RU_PER_SEC` 的配置按比例调度。如果不指定 `PRIORITY`，资源组的默认优先级为 `MEDIUM`。
 * `BURSTABLE`：是否允许此资源组超额使用剩余的系统资源。

optimizer-hints.md

@@ -804,3 +804,13 @@ SELECT /*+ NTH_PLAN(3) */ count(*) from t where a > 5;
 > **注意：**
 >
 > `NTH_PLAN(N)` 主要用于测试用途，并且在未来不保证其兼容性，请谨慎使用。
+
+### RESOURCE_GROUP(resource_group_name)
+
+`RESOURCE_GROUP(resource_group_name)` 用于[使用资源管控 (Resource Control) 实现资源隔离](/tidb-resource-control.md)。此 Hint 将临时使用指定的资源组执行当前的语句。如果指定的资源组不存在，则该 Hint 将被忽略。
+
+示例：
+
+```sql
+SELECT /*+ RESOURCE_GROUP(rg1) */ * FROM t limit 10;
+```

pd-configuration-file.md

@@ -447,3 +447,49 @@ PD 中内置的 [TiDB Dashboard](/dashboard/dashboard-intro.md) 相关配置项
 + 是否启用 TiDB Dashboard 遥测功能。
 + 默认值：false
 + 参阅[遥测](/telemetry.md)了解该功能详情。
+
+## `replication-mode`
+
+Region 同步模式相关的配置项。更多详情，请参阅[启用自适应同步模式](/two-data-centers-in-one-city-deployment.md#启用自适应同步模式)。
+
+## Controllor
+
+PD 中内置的 [Resource Control](/tidb-resource-control.md) 相关的配置项。
+
+### `degraded-mode-wait-duration`
+
++ 触发降级模式需要等待的时间。降级模式是指在 Local Token Bucket (LTB) 和 Global Token Bucket (GTB) 失联的情况下，LTB 将回退到默认的资源组配置，不再有 GTB 授权 token，从而保证在网络隔离或者异常情况下，服务不受影响。
++ 默认值: 0s
++ 默认为不开启降级模式
+
+### `request-unit`
+
+下面是 [Request Unit (RU)](/tidb-resource-control.md#什么是-request-unit-ru) 相关的配置项。
+
+#### `read-base-cost`
+
++ 每次读请求转换成 RU 的基准系数
++ 默认值: 0.25
+
+#### `write-base-cost`
+
++ 每次写请求转换成 RU 的基准系数
++ 默认值: 1
+
+#### `read-cost-per-byte`
+
++ 读流量转换成 RU 的基准系数
++ 默认值: 1/(64 * 1024)
++ 1 RU = 64 KiB 读取字节
+
+#### `write-cost-per-byte`
+
++ 写流量转换成 RU 的基准系数
++ 默认值: 1/1024
++ 1 RU = 1 KiB 写入字节
+
+#### `read-cpu-ms-cost`
+
++ CPU 转换成 RU 的基准系数
++ 默认值: 1/3
++ 1 RU = 3 毫秒 CPU 时间

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

@@ -26,17 +26,22 @@ ResourceGroupOptionList:
 
 DirectResourceGroupOption:
     "RU_PER_SEC" EqOpt stringLit
+|   "PRIORITY" EqOpt ResourceGroupPriorityOption
 |   "BURSTABLE"
 
+ResourceGroupPriorityOption:
+    LOW 
+|   MEDIUM
+|   HIGH
 ```
 
 TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-resource-control.md#什么是-request-unit-ru) 是 TiDB 对 CPU、IO 等系统资源统一抽象的单位。
 
 | 参数            | 含义           | 举例                                   |
 |---------------|--------------|--------------------------------------|
-| `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU |
-
-如果设置了 `BURSTABLE` 属性，TiDB 允许对应的资源组超出配额后使用空余的系统资源。
+| `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU。 |
+| `PRIORITY`    | 任务在 TiKV 上处理的绝对优先级  | `PRIORITY = HIGH` 表示优先级高。若未指定则默认为 `MEDIUM`。 |
+| `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 |
 
 > **注意：**
 > 
@@ -47,28 +52,56 @@ TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-
 创建一个名为 `rg1` 的资源组，并修改它的属性。
 
 ```sql
-mysql> DROP RESOURCE GROUP IF EXISTS rg1;
+DROP RESOURCE GROUP IF EXISTS rg1;
+```
+
+```sql
 Query OK, 0 rows affected (0.22 sec)
-mysql> CREATE RESOURCE GROUP IF NOT EXISTS rg1
-    ->  RU_PER_SEC = 100
-    ->  BURSTABLE;
+```
+
+```sql
+CREATE RESOURCE GROUP IF NOT EXISTS rg1
+  RU_PER_SEC = 100
+  BURSTABLE;
+```
+
+```sql
 Query OK, 0 rows affected (0.08 sec)
-mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
-+------+-------------+-----------+
-| NAME | RU_PER_SEC  | BURSTABLE |
-+------+-------------+-----------+
-| rg1  |         100 | YES       |
-+------+-------------+-----------+
+```
+
+```sql
+SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
+```
+
+```sql
++------+------------+----------+-----------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
++------+------------+----------+-----------+
+| rg1  |       100  | MEDIUM   | YES       |
++------+------------+----------+-----------+
 1 rows in set (1.30 sec)
-mysql> ALTER RESOURCE GROUP rg1
-    ->  RU_PER_SEC = 200;
+```
+
+```sql
+ALTER RESOURCE GROUP rg1
+  RU_PER_SEC = 200
+  PRIORITY = LOW;
+```
+
+```sql
 Query OK, 0 rows affected (0.08 sec)
-mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
-+------+-------------+-----------+
-| NAME | RU_PER_SEC  | BURSTABLE |
-+------+-------------+-----------+
-| rg1  |         200 | NO        |
-+------+-------------+-----------+
+```
+
+```sql
+SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
+```
+
+```sql
++------+------------+----------+-----------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
++------+------------+----------+-----------+
+| rg1  |       200  | LOW      | NO        |
++------+------------+----------+-----------+
 1 rows in set (1.30 sec)
 ```
 

sql-statements/sql-statement-calibrate-resource.md

@@ -0,0 +1,30 @@
+---
+title: CALIBRATE RESOURCE
+summary: TiDB 数据库中 CALIBRATE RESOURCE 的使用概况。
+---
+
+# `CALIBRATE RESOURCE`
+
+`CALIBRATE RESOURCE` 语句用于预估并输出当前集群的 [`Request Unit (RU)`](/tidb-resource-control.md#什么是-request-unit-ru) 的容量。
+
+## 语法图
+
+```ebnf+diagram
+CalibrateResourceStmt ::= 'CALIBRATE' 'RESOURCE'
+``` 
+
+## 示例
+
+```sql
+CALIBRATE RESOURCE;
++-------+
+| QUOTA |
++-------+
+| 68569 |
++-------+
+1 row in set (0.03 sec)
+```
+
+> **注意：**
+>
+> 集群 RU 的容量会随集群的拓扑结构和各个组件软硬件配置的变化而变化，每个集群实际能消耗的 RU 还与实际的负载相关。此预估值仅供参考，可能会与实际的最大值存在偏差。

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

@@ -26,8 +26,13 @@ ResourceGroupOptionList:
 
 DirectResourceGroupOption:
     "RU_PER_SEC" EqOpt stringLit
+|   "PRIORITY" EqOpt ResourceGroupPriorityOption
 |   "BURSTABLE"
 
+ResourceGroupPriorityOption:
+    LOW
+|   MEDIUM
+|   HIGH
 ```
 
 资源组的 `ResourceGroupName` 是全局唯一的，不允许重复。
@@ -36,35 +41,58 @@ TiDB 支持以下 `DirectResourceGroupOption`, 其中 [Request Unit (RU)](/tidb-
 
 | 参数            | 含义           | 举例                                   |
 |---------------|--------------|--------------------------------------|
-| `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU |
-
-如果设置了 `BURSTABLE` 属性，TiDB 允许对应的资源组超出配额后使用空余的系统资源。
+| `RU_PER_SEC`  | 每秒 RU 填充的速度 | `RU_PER_SEC = 500` 表示此资源组每秒回填 500 个 RU。 |
+| `PRIORITY`    | 任务在 TiKV 上处理的绝对优先级  | `PRIORITY = HIGH` 表示优先级高。若未指定，则默认为 `MEDIUM`。 |
+| `BURSTABLE`   | 允许对应的资源组超出配额后使用空余的系统资源。 |
 
 > **注意：**
 >
-> `CREATE RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 参数设置为 `ON` 时才能执行。
+> - `CREATE RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 设置为 `ON` 时才能执行。
+> - TiDB 集群在初始化时会自动创建 `default` 资源组，所有未绑定资源组的请求都将自动绑定至此资源组。
 
 ## 示例
 
 创建 `rg1` 和 `rg2` 两个资源组。
 
 ```sql
-mysql> DROP RESOURCE GROUP IF EXISTS rg1;
+DROP RESOURCE GROUP IF EXISTS rg1;
+```
+
+```sql
 Query OK, 0 rows affected (0.22 sec)
-mysql> CREATE RESOURCE GROUP IF NOT EXISTS rg1
-    ->  RU_PER_SEC = 100
-    ->  BURSTABLE;
+```
+
+```sql
+CREATE RESOURCE GROUP IF NOT EXISTS rg1
+  RU_PER_SEC = 100
+  PRIORITY = HIGH
+  BURSTABLE;
+```
+
+```sql
 Query OK, 0 rows affected (0.08 sec)
-mysql> CREATE RESOURCE GROUP IF NOT EXISTS rg2
-    ->  RU_PER_SEC = 200;
+```
+
+```sql
+CREATE RESOURCE GROUP IF NOT EXISTS rg2
+  RU_PER_SEC = 200;
+```
+
+```sql
 Query OK, 0 rows affected (0.08 sec)
-mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1' or NAME = 'rg2';
-+------+-------------+-----------+
-| NAME | RU_PER_SEC  | BURSTABLE |
-+------+-------------+-----------+
-| rg1  |         100 | YES       |
-| rg2  |         200 | NO        |
-+------+-------------+-----------+
+```
+
+```sql
+SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1' or NAME = 'rg2';
+```
+
+```sql
++------+------------+----------+-----------+
+| NAME | RU_PER_SEC | PRIORITY | BURSTABLE |
++------+------------+----------+-----------+
+| rg1  |        100 | HIGH     | YES       |
+| rg2  |        200 | MEDIUM   | NO        |
++------+------------+----------+-----------+
 2 rows in set (1.30 sec)
 ```