*: document for resource control feature

Signed-off-by: BornChanger <[email protected]>
pingcap · Jan 12, 2023 · 215d994 · 215d994
1 parent 7e8dc1c
commit 215d994
Show file tree

Hide file tree

Showing 7 changed files with 365 additions and 2 deletions.
diff --git a/sql-statements/sql-statement-alter-resource-group.md b/sql-statements/sql-statement-alter-resource-group.md
@@ -0,0 +1,93 @@
+---
+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 对 CPU, IO 等系统资源的统一抽象的单位。
+
+| 参数           |含义                                  |举例                      |
+|----------------|--------------------------------------|----------------------------|
+
+|`RRU_PER_SEC`|每秒钟读 RU 的配额                        |`RRU_PER_SEC` = 500|
+
+|`WRU_PER_SEC`|每秒钟写 RU 的配额                        |`RRU_PER_SEC` = 300|
+
+如果设置了`BURSTABLE`属性，对应的资源组就允许在系统资源充足的情况下，可以超出配额占用使用系统资源。
+
+> **注意：**
+> `ALTER RESOURCE GROUP` 语句只能在全局变量 `tidb_resource_group_enable` 参数设置为 `ON` 的时候才被允许执行
+
+## 示例
+
+创建一个名字是 rg1 的资源组， 并修改它的属性
+
+{{< copyable "sql" >}}
+```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
+    ->  RRU_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
+    ->  RRU_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 也支持创建 [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)
+* [CREATE RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
diff --git a/sql-statements/sql-statement-alter-user.md b/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)

diff --git a/sql-statements/sql-statement-create-resource-group.md b/sql-statements/sql-statement-create-resource-group.md
@@ -0,0 +1,83 @@
+---
+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 对 CPU, IO 等系统资源的统一抽象的单位。
+
+| 参数           |含义                                  |举例                      |
+|----------------|--------------------------------------|----------------------------|
+
+|`RRU_PER_SEC`|每秒钟读 RU 的配额                        |`RRU_PER_SEC` = 500|
+
+|`WRU_PER_SEC`|每秒钟写 RU 的配额                        |`RRU_PER_SEC` = 300|
+
+如果设置了`BURSTABLE`属性，对应的资源组就允许在系统资源充足的情况下，可以超出配额占用使用系统资源。
+
+> **注意：**
+> `CREATE RESOURCE GROUP` 语句只能在全局变量 `tidb_resource_group_enable` 参数设置为 `ON` 的时候才被允许执行
+
+## 示例
+
+创建一个名字是 rg1 的资源组
+
+{{< copyable "sql" >}}
+
+```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
+    ->  RRU_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 也支持创建 [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)
diff --git a/sql-statements/sql-statement-create-user.md b/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 * FROM information_schema.user_attributes;
+```
+
+```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` 选项。

diff --git a/sql-statements/sql-statement-drop-resource-group.md b/sql-statements/sql-statement-drop-resource-group.md
@@ -0,0 +1,66 @@
+---
+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_resource_group_enable` 参数设置为 `ON` 的时候才被允许执行
+
+## 示例
+
+删除名字是 rg1 的资源组
+
+{{< copyable "sql" >}}
+
+```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
+    ->  RRU_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 也支持创建 [Resource Group](https://dev.mysql.com/doc/refman/8.0/en/create-resource-group.html) ，但是接受的参数和 TiDB 不同。
+
+## 另请参阅
+
+* [ALTER RESOURCE GROUP](/sql-statements/sql-statement-alter-resource-group.md)
+* [CREATE RESOURCE GROUP](/sql-statements/sql-statement-create-resource-group.md)
diff --git a/system-variables.md b/system-variables.md
@@ -3690,3 +3690,15 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 是否持久化到集群：是
 - 默认值：`ON`
 - 这个变量用于控制计算窗口函数时是否采用高精度模式。
+
+### `tidb_enable_resource_control` <span class="version-mark">从 v6.6.0 版本开始引入</span>
+
+> **警告：**
+>
+> [Resource Control](/tidb-resource-control.md) 目前为实验性特性，此变量定义可能在之后发生变化或者删除。
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 默认值：`OFF`
+- 类型：布尔型
+- 该变量是资源管控特性的开关。该变量设置为 `ON` 后，集群支持应用按照资源组做资源隔离。