sql-infra: document for resource control feature

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

@@ -0,0 +1,94 @@
+---
+title: ALTER RESOURCE GROUP
+summary: TiDB 数据库中 ALTER RESOURCE GROUP 的使用概况
+aliases: ['/docs-cn/dev/sql-statements/sql-statement-alter-resource-group/','/docs-cn/dev/reference/sql/statements/alter-resource-group/']
+---
+
+# ALTER RESOURCE GROUP
+
+`ALTER RESOURCE GROUP` 语句用于在当前所选数据库中修改资源组。
+
+## 语法图
+
+```ebnf+diagram
+AlterResourceGroupStmt:
+   "ALTER" "RESOURCE" "GROUP" IfNotExists ResourceGroupName ResourceGroupOptionList BurstableOption
+
+IfNotExists ::=
+    ('IF' 'NOT' 'EXISTS')?
+
+ResourceGroupName:
+   Identifier
+
+ResourceGroupOptionList:
+    DirectResourceGroupOption
+|   ResourceGroupOptionList DirectResourceGroupOption
+|   ResourceGroupOptionList ',' DirectResourceGroupOption
+
+DirectResourceGroupOption:
+    "RRU_PER_SEC" EqOpt stringLit
+|   "WRU_PER_SEC" EqOpt stringLit
+
+BurstableOption ::=
+    ("BURSTABLE")?
+
+```
+
+TiDB 支持以下 `DirectResourceGroupOption`, 其中 [`RU` (Resource Unit)](/tidb-RU.md) 是 TiDB 对 CPU、IO 等系统资源统一抽象的单位。
+
+| 参数           |含义                                 | 举例                    |
+|---------------|-------------------------------------|------------------------|
+
+|`RRU_PER_SEC`|每秒钟读 RU 的配额                       |`RRU_PER_SEC` = 500     |
+|`WRU_PER_SEC`|每秒钟写 RU 的配额                       |`WRU_PER_SEC` = 300     |
+
+如果设置了 `BURSTABLE` 属性，对应的资源组就允许在系统资源充足的情况下，允许超出配额使用系统资源。
+
+> **注意：**
+> 
+> `ALTER RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_group`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 参数设置为 `ON` 的时候才被允许执行。
+
+## 示例
+
+创建一个名为 `rg1` 的资源组，并修改它的属性。
+
+```sql
+mysql> DROP RESOURCE GROUP IF EXISTS rg1;
+Query OK, 0 rows affected (0.22 sec)
+mysql> CREATE RESOURCE GROUP IF NOT EXISTS rg1
+    ->  RRU_PER_SEC = 500
+    ->  WRU_PER_SEC = 300
+    ->  BURSTABLE
+    -> ;
+Query OK, 0 rows affected (0.08 sec)
+mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
++------+--------------+---------------------------------------------------------------+
+| Name | Plan_type    | Directive | 
++------+--------------+---------------------------------------------------------------+
+| rg1  |   tenancy    | {"RRU_PER_SEC": 500, "WRU_PER_SEC": 300, "BURSTABLE": true} |
++------+--------------+---------------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> ALTER RESOURCE GROUP IF NOT EXISTS rg1
+    ->  RRU_PER_SEC = 600
+    ->  WRU_PER_SEC = 400
+    -> ;
+Query OK, 0 rows affected (0.09 sec)
+mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
++------+--------------+---------------------------------------------------------------+
+| Name | Plan_type    | Directive | 
++------+--------------+---------------------------------------------------------------+
+| rg1  |   tenancy    | {"RRU_PER_SEC": 600, "WRU_PER_SEC": 400, "BURSTABLE": false} |
++------+--------------+---------------------------------------------------------------+
+1 row in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+* MySQL 也支持 [ALTER RESOURCE GROUP](https://dev.mysql.com/doc/refman/8.0/en/alter-resource-group.html)，但是接受的参数和 TiDB 不同，两者并不兼容。
+
+## 另请参阅
+
+* [DROP RESOURCE GROUP](/sql-statements/sql-statement-drop-resource-group.md)
+* [CREATE RESOURCE GROUP](/sql-statements/sql-statement-create-resource-group.md)
+* [RU](/tidb-RU.md)

sql-statements/sql-statement-alter-user.md

@@ -12,7 +12,7 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-alter-user/','/docs-cn/dev/
 
 ```ebnf+diagram
 AlterUserStmt ::=
-    'ALTER' 'USER' IfExists (UserSpecList RequireClauseOpt ConnectionOptions PasswordOption LockOption AttributeOption | 'USER' '(' ')' 'IDENTIFIED' 'BY' AuthString)
+    'ALTER' 'USER' IfExists (UserSpecList RequireClauseOpt ConnectionOptions PasswordOption LockOption AttributeOption | 'USER' '(' ')' 'IDENTIFIED' 'BY' AuthString) ResourceGroupNameOption
 
 UserSpecList ::=
     UserSpec ( ',' UserSpec )*
@@ -31,6 +31,8 @@ PasswordOption ::= ( 'PASSWORD' 'EXPIRE' ( 'DEFAULT' | 'NEVER' | 'INTERVAL' N 'D
 LockOption ::= ( 'ACCOUNT' 'LOCK' | 'ACCOUNT' 'UNLOCK' )?
 
 AttributeOption ::= ( 'COMMENT' CommentString | 'ATTRIBUTE' AttributeString )?
+
+ResourceGroupNameOption::= ( 'RESOURCE' 'GROUP' Identifier)?
 ```
 
 ## 示例
@@ -163,6 +165,16 @@ ALTER USER 'newuser' PASSWORD REUSE INTERVAL 90 DAY;
 Query OK, 0 rows affected (0.02 sec)
 ```
 
+通过 `ALTER USER ... RESOURCE GROUP` 修改用户 `newuser` 的资源组到 `rg1`：
+
+```sql
+ALTER USER 'newuser' RESOURCE GROUP rg1;
+```
+
+```
+Query OK, 0 rows affected (0.02 sec)
+```
+
 ## 另请参阅
 
 * [Security Compatibility with MySQL](/security-compatibility-with-mysql.md)

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

@@ -0,0 +1,84 @@
+---
+title: CREATE RESOURCE GROUP
+summary: TiDB 数据库中 CREATE RESOURCE GROUP 的使用概况
+aliases: ['/docs-cn/dev/sql-statements/sql-statement-create-resource-group/','/docs-cn/dev/reference/sql/statements/create-resource-group/']
+---
+
+# CREATE RESOURCE GROUP
+
+`CREATE RESOURCE GROUP` 语句用于在当前所选数据库中创建资源组。
+
+## 语法图
+
+```ebnf+diagram
+CreateResourceGroupStmt:
+   "CREATE" "RESOURCE" "GROUP" IfNotExists ResourceGroupName ResourceGroupOptionList BurstableOption
+
+IfNotExists ::=
+    ('IF' 'NOT' 'EXISTS')?
+
+ResourceGroupName:
+   Identifier
+
+ResourceGroupOptionList:
+    DirectResourceGroupOption
+|   ResourceGroupOptionList DirectResourceGroupOption
+|   ResourceGroupOptionList ',' DirectResourceGroupOption
+
+DirectResourceGroupOption:
+    "RRU_PER_SEC" EqOpt stringLit
+|   "WRU_PER_SEC" EqOpt stringLit
+
+BurstableOption ::=
+    ("BURSTABLE")?
+
+```
+
+资源组的 `ResourceGroupName` 是全局唯一的，不允许重复。
+
+TiDB 支持以下 `DirectResourceGroupOption`, 其中 [`RU` (Resource Unit)](/tidb-RU.md) 是 TiDB 对 CPU、IO 等系统资源统一抽象的单位。
+
+| 参数           |含义                                  |举例                      |
+|----------------|--------------------------------------|----------------------------|
+
+|`RRU_PER_SEC`|每秒钟读 RU 的配额                        |`RRU_PER_SEC` = 500|
+
+|`WRU_PER_SEC`|每秒钟写 RU 的配额                        |`WRU_PER_SEC` = 300|
+
+如果设置了 `BURSTABLE` 属性，对应的资源组就允许在系统资源充足的情况下，可以超出配额占用使用系统资源。
+
+> **注意：**
+>
+> `CREATE RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_group`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 参数设置为 `ON` 的时候才被允许执行。
+
+## 示例
+
+创建一个名字是 rg1 的资源组
+
+```sql
+mysql> DROP RESOURCE GROUP IF EXISTS rg1;
+Query OK, 0 rows affected (0.22 sec)
+mysql> CREATE RESOURCE GROUP IF NOT EXISTS rg1
+    ->  RRU_PER_SEC = 500
+    ->  WRU_PER_SEC = 300
+    ->  BURSTABLE
+    -> ;
+Query OK, 0 rows affected (0.08 sec)
+mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
++------+--------------+---------------------------------------------------------------+
+| Name | Plan_type    | Directive | 
++------+--------------+---------------------------------------------------------------+
+| rg1  |   tenancy    | {"RRU_PER_SEC": 5000, "WRU_PER_SEC": 1000, "BURSTABLE": true} |
++------+--------------+---------------------------------------------------------------+
+1 row in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+MySQL 也支持[CREATE RESOURCE GROUP](https://dev.mysql.com/doc/refman/8.0/en/create-resource-group.html)，但是接受的参数和 TiDB 不同，两者并不兼容。
+
+## 另请参阅
+
+* [DROP RESOURCE GROUP](/sql-statements/sql-statement-drop-resource-group.md)
+* [ALTER RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
+* [RU](/tidb-RU.md)

sql-statements/sql-statement-create-user.md

@@ -12,7 +12,7 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-create-user/','/docs-cn/dev
 
 ```ebnf+diagram
 CreateUserStmt ::=
-    'CREATE' 'USER' IfNotExists UserSpecList RequireClauseOpt ConnectionOptions PasswordOption LockOption AttributeOption
+    'CREATE' 'USER' IfNotExists UserSpecList RequireClauseOpt ConnectionOptions PasswordOption LockOption AttributeOption ResourceGroupNameOption
 
 IfNotExists ::=
     ('IF' 'NOT' 'EXISTS')?
@@ -35,6 +35,8 @@ PasswordOption ::= ( 'PASSWORD' 'EXPIRE' ( 'DEFAULT' | 'NEVER' | 'INTERVAL' N 'D
 LockOption ::= ( 'ACCOUNT' 'LOCK' | 'ACCOUNT' 'UNLOCK' )?
 
 AttributeOption ::= ( 'COMMENT' CommentString | 'ATTRIBUTE' AttributeString )?
+
+ResourceGroupNameOption::= ( 'RESOURCE' 'GROUP' Identifier)?
 ```
 
 ## 示例
@@ -151,6 +153,22 @@ CREATE USER 'newuser9'@'%' PASSWORD EXPIRE;
 Query OK, 1 row affected (0.02 sec)
 ```
 
+创建一个使用资源组 (`rg1`) 的用户。
+
+```sql
+CREATE USER 'newuser7'@'%' RESOURCE GROUP rg1;
+SELECT USER, HOST, USER_ATTRIBUTES FROM MYSQ.USER WHERE USER='newuser7';
+```
+
+```sql
++-----------+------+---------------------------------------------------+
+| USER      | HOST | ATTRIBUTE                                         |
++-----------+------+---------------------------------------------------+
+| newuser7  | %    | {"resource_group": "rg1"} |
++-----------+------+---------------------------------------------------+
+1 rows in set (0.00 sec)
+```
+
 ## MySQL 兼容性
 
 * TiDB 不支持 `WITH MAX_QUERIES_PER_HOUR`、`WITH MAX_UPDATES_PER_HOUR`、`WITH MAX_USER_CONNECTIONS` 等 `CREATE` 选项。

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

@@ -0,0 +1,67 @@
+---
+title: DROP RESOURCE GROUP
+summary: TiDB 数据库中 DROP RESOURCE GROUP 的使用概况
+aliases: ['/docs-cn/dev/sql-statements/sql-statement-drop-resource-group/','/docs-cn/dev/reference/sql/statements/drop-resource-group/']
+---
+
+# DROP RESOURCE GROUP
+
+`DROP RESOURCE GROUP` 语句用于在当前所选数据库中删除资源组。
+
+## 语法图
+
+```ebnf+diagram
+DropResourceGroupStmt:
+    "DROP" "RESOURCE" "GROUP" IfNotExists ResourceGroupName
+
+IfNotExists ::=
+    ('IF' 'NOT' 'EXISTS')?
+
+ResourceGroupName:
+    Identifier
+```
+
+> **注意：**
+>
+> `DROP RESOURCE GROUP` 语句只能在全局变量 [`tidb_enable_resource_group`](/system-variables.md#tidb_enable_resource_control-从-v660-版本开始引入) 参数设置为 `ON` 的时候才被允许执行。
+
+## 示例
+
+删除名字是 `rg1` 的资源组。
+
+```sql
+mysql> DROP RESOURCE GROUP IF EXISTS rg1;
+Query OK, 0 rows affected (0.22 sec)
+mysql> CREATE RESOURCE GROUP IF NOT EXISTS rg1 (
+    ->  RRU_PER_SEC = 500
+    ->  WRU_PER_SEC = 300
+    ->  BURSTABLE
+    -> );
+Query OK, 0 rows affected (0.08 sec)
+mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
++------+--------------+---------------------------------------------------------------+
+| Name | Plan_type    | Directive | 
++------+--------------+---------------------------------------------------------------+
+| rg1  |   tenancy    | {"RRU_PER_SEC": 500, "WRU_PER_SEC": 300, "BURSTABLE": true} |
++------+--------------+---------------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> DROP RESOURCE GROUP IF NOT EXISTS rg1 ;
+Query OK, 1 rows affected (0.09 sec)
+mysql> SELECT * FROM information_schema.resource_groups WHERE NAME ='rg1';
++------+--------------+---------------------------------------------------------------+
+| Name | Plan_type    | Directive | 
++------+--------------+---------------------------------------------------------------+
++------+--------------+---------------------------------------------------------------+
+0 row in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+MySQL 也支持 [DROP RESOURCE GROUP](https://dev.mysql.com/doc/refman/8.0/en/drop-resource-group.html), 但 TiDB 不支持 `FORCE` 参数。
+
+## 另请参阅
+
+* [ALTER RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
+* [CREATE RESOURCE GROUP](/sql-statements/sql-statement-create-resource-group.md)
+* [RU](/tidb-RU.md)

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

@@ -0,0 +1,45 @@
+---
+title: SHOW CREATE RESOURCE GROUP
+summary: TiDB 数据库中 SHOW CREATE RESOURCE GROUP 的使用概况。
+---
+
+# SHOW CREATE RESOURCE GROUP
+
+`SHOW CREATE RESOURCE GROUP` 语句可用于查看资源组当前的定义，并在另一个 TiDB 集群中重新创建该资源组。
+
+## 语法图
+
+```ebnf+diagram
+ShowCreateResourceGroupStmt ::=
+    "SHOW" "CREATE" "RESOURCE" "GROUP" ResourceGroupName
+
+ResourceGroupName ::=
+    Identifier
+```
+
+## 示例
+
+{{< copyable "sql" >}}
+
+```sql
+CREATE RESOURCE GROUP rg1 RRU_PER_SEC=100 WRU_PER_SEC=200;
+Query OK, 0 rows affected (0.10 sec)
+```
+```sql
+SHOW CREATE RESOURCE GROUP rg1;
+***************************[ 1. row ]***************************
+Resource_Group        | rg1
+Create Resource Group | CREATE RESOURCE GROUP `rg1` RRU_PER_SEC=100 WRU_PER_SEC=200
+1 row in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
+## 另请参阅
+
+* [TiDB RESOURCE CONTROL](/tidb-resource-control.md)
+* [CREATE RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
+* [ALTER RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
+* [DROP RESOURCE GROUP](/sql-statements/sql-statement-drop-resource-group.md)

system-variables.md

@@ -1548,6 +1548,18 @@ MPP 是 TiFlash 引擎提供的分布式计算框架，允许节点之间的数
 - 当读数据的算子只剩 1 个线程且当单条 SQL 语句的内存使用继续超过 [`tidb_mem_quota_query`](/system-variables.md#tidb_mem_quota_query) 时，该 SQL 语句会触发其它的内存控制行为，例如[落盘](/system-variables.md#tidb_enable_tmp_storage_on_oom)。
 - 该变量在单条查询仅涉及读数据的情况下，对内存控制效果较好。若还存在额外的计算操作（如连接、聚合等），打开该变量可能会导致内存不受 `tidb_mem_quota_query` 控制，加剧 OOM 风险。
 
+### `tidb_enable_resource_control` <span class="version-mark">从 v6.6.0 版本开始引入</span>
+
+> **警告：**
+>
+> [Resource Control](/tidb-resource-control.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`OFF`
+- 类型：布尔型
+- 该变量是资源管控特性的开关。该变量设置为 `ON` 后，集群支持应用按照资源组做资源隔离。
+
 ### `tidb_enable_reuse_chunk` <span class="version-mark">从 v6.4.0 版本开始引入</span>
 
 - 作用域：SESSION | GLOBAL

tidb-RU.md

@@ -0,0 +1,8 @@
+---
+title: TiDB Resource Unit
+summary: TiDB 数据库中 Resource Unit (RU) 的概念
+aliases: ['/docs-cn/dev/tidb-RU/','/docs-cn/dev/reference/tidb-RU/']
+---
+`RU` (Resource Unit) 是 TiDB 对 CPU、IO 等系统资源的统一抽象的单位, 目前包括 CPU、IOPS 和 IO 带宽三个指标。这三个指标的消耗会按照一定的比例统一到 `RU` 单位上。
+
+一个 `RU` 代表一次 64 bytes 点查请求的资源消耗。