sql-infra: add resource control feature

TOC.md

@@ -159,6 +159,7 @@
       - [Back up and Restore Data Using Dumpling and TiDB Lightning](/backup-and-restore-using-dumpling-lightning.md)
       - [Back Up and Restore RawKV](/br/rawkv-backup-and-restore.md)
       - [Incremental Backup and Restore](/br/br-incremental-guide.md)
+  - [Resource Control](/tidb-resource-control.md)
   - [Configure Time Zone](/configure-time-zone.md)
   - [Daily Checklist](/daily-check.md)
   - [Maintain TiFlash](/tiflash/maintain-tiflash.md)
@@ -645,6 +646,7 @@
       - [`ALTER INDEX`](/sql-statements/sql-statement-alter-index.md)
       - [`ALTER INSTANCE`](/sql-statements/sql-statement-alter-instance.md)
       - [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md)
+      - [`ALTER RESOURCE GROUP`](/sql-statements/sql-statement-alter-resource-group.md)
       - [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md)
       - [`ALTER TABLE COMPACT`](/sql-statements/sql-statement-alter-table-compact.md)
       - [`ALTER USER`](/sql-statements/sql-statement-alter-user.md)
@@ -660,6 +662,7 @@
       - [`CREATE DATABASE`](/sql-statements/sql-statement-create-database.md)
       - [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md)
       - [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md)
+      - [`CREATE RESOURCE GROUP`](/sql-statements/sql-statement-create-resource-group.md)
       - [`CREATE ROLE`](/sql-statements/sql-statement-create-role.md)
       - [`CREATE SEQUENCE`](/sql-statements/sql-statement-create-sequence.md)
       - [`CREATE TABLE LIKE`](/sql-statements/sql-statement-create-table-like.md)
@@ -676,6 +679,7 @@
       - [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md)
       - [`DROP INDEX`](/sql-statements/sql-statement-drop-index.md)
       - [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md)
+      - [`DROP RESOURCE GROUP`](/sql-statements/sql-statement-drop-resource-group.md)
       - [`DROP ROLE`](/sql-statements/sql-statement-drop-role.md)
       - [`DROP SEQUENCE`](/sql-statements/sql-statement-drop-sequence.md)
       - [`DROP STATS`](/sql-statements/sql-statement-drop-stats.md)
@@ -727,6 +731,7 @@
       - [`SHOW CONFIG`](/sql-statements/sql-statement-show-config.md)
       - [`SHOW CREATE DATABASE`](/sql-statements/sql-statement-show-create-database.md)
       - [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md)
+      - [`SHOW CREATE RESOURCE GROUP`](/sql-statements/sql-statement-show-create-resource-group.md)
       - [`SHOW CREATE SEQUENCE`](/sql-statements/sql-statement-show-create-sequence.md)
       - [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md)
       - [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md)
@@ -852,6 +857,7 @@
         - [`PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md)
         - [`PROCESSLIST`](/information-schema/information-schema-processlist.md)
         - [`REFERENTIAL_CONSTRAINTS`](/information-schema/information-schema-referential-constraints.md)
+        - [`RESOURCE_GROUPS`](/information-schema/information-schema-resource-groups.md)
         - [`SCHEMATA`](/information-schema/information-schema-schemata.md)
         - [`SEQUENCES`](/information-schema/information-schema-sequences.md)
         - [`SESSION_VARIABLES`](/information-schema/information-schema-session-variables.md)

information-schema/information-schema-processlist.md

@@ -12,7 +12,8 @@ The `PROCESSLIST` table has additional columns not present in `SHOW PROCESSLIST`
 * A `DIGEST` column to show the digest of the SQL statement.
 * A `MEM` column to show the memory used by the request that is being processed, in bytes.
 * A `DISK` column to show the disk usage in bytes.
-* A `TxnStart` column to show the start time of the transaction
+* A `TxnStart` column to show the start time of the transaction.
+* A `RESOURCE_GROUP_NAME` column to show the resource group name.
 
 {{< copyable "sql" >}}
 
@@ -21,24 +22,25 @@ USE information_schema;
 DESC processlist;
 ```
 
-```
-+----------+---------------------+------+------+---------+-------+
-| Field    | Type                | Null | Key  | Default | Extra |
-+----------+---------------------+------+------+---------+-------+
-| ID       | bigint(21) unsigned | NO   |      | 0       |       |
-| USER     | varchar(16)         | NO   |      |         |       |
-| HOST     | varchar(64)         | NO   |      |         |       |
-| DB       | varchar(64)         | YES  |      | NULL    |       |
-| COMMAND  | varchar(16)         | NO   |      |         |       |
-| TIME     | int(7)              | NO   |      | 0       |       |
-| STATE    | varchar(7)          | YES  |      | NULL    |       |
-| INFO     | longtext            | YES  |      | NULL    |       |
-| DIGEST   | varchar(64)         | YES  |      |         |       |
-| MEM      | bigint(21) unsigned | YES  |      | NULL    |       |
-| DISK     | bigint(21) unsigned | YES  |      | NULL    |       |
-| TxnStart | varchar(64)         | NO   |      |         |       |
-+----------+---------------------+------+------+---------+-------+
-12 rows in set (0.00 sec)
+```sql
++---------------------+---------------------+------+------+---------+-------+
+| Field               | Type                | Null | Key  | Default | Extra |
++---------------------+---------------------+------+------+---------+-------+
+| ID                  | bigint(21) unsigned | NO   |      | 0       |       |
+| USER                | varchar(16)         | NO   |      |         |       |
+| HOST                | varchar(64)         | NO   |      |         |       |
+| DB                  | varchar(64)         | YES  |      | NULL    |       |
+| COMMAND             | varchar(16)         | NO   |      |         |       |
+| TIME                | int(7)              | NO   |      | 0       |       |
+| STATE               | varchar(7)          | YES  |      | NULL    |       |
+| INFO                | longtext            | YES  |      | NULL    |       |
+| DIGEST              | varchar(64)         | YES  |      |         |       |
+| MEM                 | bigint(21) unsigned | YES  |      | NULL    |       |
+| DISK                | bigint(21) unsigned | YES  |      | NULL    |       |
+| TxnStart            | varchar(64)         | NO   |      |         |       |
+| RESOURCE_GROUP_NAME | varchar(32)         | NO   |      |         |       |
++---------------------+---------------------+------+------+---------+-------+
+13 rows in set (0.00 sec)
 ```
 
 {{< copyable "sql" >}}
@@ -47,18 +49,21 @@ DESC processlist;
 SELECT * FROM processlist\G
 ```
 
-```
+```sql
 *************************** 1. row ***************************
-      ID: 16
-    USER: root
-    HOST: 127.0.0.1
-      DB: information_schema
- COMMAND: Query
-    TIME: 0
-   STATE: autocommit
-    INFO: SELECT * FROM processlist
-     MEM: 0
-TxnStart:
+                 ID: 5794501045170209171
+               USER: root
+               HOST: 127.0.0.1:60645
+                 DB: information_schema
+            COMMAND: Query
+               TIME: 0
+              STATE: autocommit
+               INFO: SELECT * FROM processlist
+             DIGEST: dbfaa16980ec628011029f0aaf0d160f4b040885240dfc567bf760d96d374f7e
+                MEM: 0
+               DISK: 0
+           TxnStart:
+RESOURCE_GROUP_NAME: default
 1 row in set (0.00 sec)
 ```
 
@@ -76,6 +81,7 @@ Fields in the `PROCESSLIST` table are described as follows:
 * MEM: The memory used by the request that is being processed, in bytes.
 * DISK: The disk usage in bytes.
 * TxnStart: The start time of the transaction.
+* RESOURCE_GROUP_NAME: The resource group name.
 
 ## CLUSTER_PROCESSLIST
 
@@ -88,13 +94,14 @@ SELECT * FROM information_schema.cluster_processlist;
 ```
 
 ```sql
-+-----------------+-----+------+----------+------+---------+------+------------+------------------------------------------------------+-----+----------------------------------------+
-| INSTANCE        | ID  | USER | HOST     | DB   | COMMAND | TIME | STATE      | INFO                                                 | MEM | TxnStart                               |
-+-----------------+-----+------+----------+------+---------+------+------------+------------------------------------------------------+-----+----------------------------------------+
-| 10.0.1.22:10080 | 150 | u1   | 10.0.1.1 | test | Query   | 0    | autocommit | select count(*) from usertable                       | 372 | 05-28 03:54:21.230(416976223923077223) |
-| 10.0.1.22:10080 | 138 | root | 10.0.1.1 | test | Query   | 0    | autocommit | SELECT * FROM information_schema.cluster_processlist | 0   | 05-28 03:54:21.230(416976223923077220) |
-| 10.0.1.22:10080 | 151 | u1   | 10.0.1.1 | test | Query   | 0    | autocommit | select count(*) from usertable                       | 372 | 05-28 03:54:21.230(416976223923077224) |
-| 10.0.1.21:10080 | 15  | u2   | 10.0.1.1 | test | Query   | 0    | autocommit | select max(field0) from usertable                    | 496 | 05-28 03:54:21.230(416976223923077222) |
-| 10.0.1.21:10080 | 14  | u2   | 10.0.1.1 | test | Query   | 0    | autocommit | select max(field0) from usertable                    | 496 | 05-28 03:54:21.230(416976223923077225) |
-+-----------------+-----+------+----------+------+---------+------+------------+------------------------------------------------------+-----+----------------------------------------+
++-----------------+-----+------+----------+------+---------+------+------------+------------------------------------------------------+-----+----------------------------------------+---------------------+
+| INSTANCE        | ID  | USER | HOST     | DB   | COMMAND | TIME | STATE      | INFO                                                 | MEM | TxnStart                               | RESOURCE_GROUP_NAME | 
++-----------------+-----+------+----------+------+---------+------+------------+------------------------------------------------------+-----+----------------------------------------+---------------------+
+
+| 10.0.1.22:10080 | 150 | u1   | 10.0.1.1 | test | Query   | 0    | autocommit | select count(*) from usertable                       | 372 | 05-28 03:54:21.230(416976223923077223) | default             |
+| 10.0.1.22:10080 | 138 | root | 10.0.1.1 | test | Query   | 0    | autocommit | SELECT * FROM information_schema.cluster_processlist | 0   | 05-28 03:54:21.230(416976223923077220) | rg1                 |
+| 10.0.1.22:10080 | 151 | u1   | 10.0.1.1 | test | Query   | 0    | autocommit | select count(*) from usertable                       | 372 | 05-28 03:54:21.230(416976223923077224) | rg2                 |
+| 10.0.1.21:10080 | 15  | u2   | 10.0.1.1 | test | Query   | 0    | autocommit | select max(field0) from usertable                    | 496 | 05-28 03:54:21.230(416976223923077222) | default             |
+| 10.0.1.21:10080 | 14  | u2   | 10.0.1.1 | test | Query   | 0    | autocommit | select max(field0) from usertable                    | 496 | 05-28 03:54:21.230(416976223923077225) | default             |
++-----------------+-----+------+----------+------+---------+------+------------+------------------------------------------------------+-----+----------------------------------------+---------------------+
 ```

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

@@ -0,0 +1,70 @@
+---
+title: RESOURCE_GROUPS
+summary: Learn the `RESOURCE_GROUPS` information_schema table.
+---
+
+The `RESOURCE_GROUPS` table shows information about all resource groups. See [Resource Conctrol in TiDB](/tidb-resource-control.md).
+
+```sql
+USE information_schema;
+DESC resource_groups;
+```
+
+```sql
++-----------------+-------------+------+------+---------+-------+
+| Field           | Type        | Null | Key  | Default | Extra |
++-----------------+-------------+------+------+---------+-------+
+| NAME            | varchar(32) | NO   |      | NULL    |       |
+| MODE            | varchar(12) | NO   |      | NULL    |       |
+| RRU             | bigint(21)  | YES  |      | NULL    |       |
+| RRU_TOKEN       | bigint(21)  | YES  |      | NULL    |       |
+| WRU             | bigint(21)  | YES  |      | NULL    |       |
+| WRU_TOKEN       | bigint(21)  | YES  |      | NULL    |       |
+| CPU             | bigint(21)  | YES  |      | NULL    |       |
+| READ_BANDWIDTH  | bigint(21)  | YES  |      | NULL    |       |
+| WRITE_BANDWIDTH | bigint(21)  | YES  |      | NULL    |       |
++-----------------+-------------+------+------+---------+-------+
+9 rows in set (0.08 sec)
+```
+
+## Examples
+
+{{< copyable "sql" >}}
+
+```sql
+mysql> CREATE RESOURCE GROUP rg1 RRU_PER_SEC=1000 WRU_PER_SEC=2000 ; -- Use RU_MODE to create the resource group rg1
+Query OK, 0 rows affected (0.34 sec)
+mysql> SHOW CREATE RESOURCE GROUP rg1; -- Displays the definition of the rg1 resource group.
++----------------+------------------------------------------------------------------+
+| Resource_Group | Create Resource Group                                            |
++----------------+------------------------------------------------------------------+
+| rg1         | CREATE RESOURCE GROUP `rg1` RRU_PER_SEC=1000 WRU_PER_SEC=2000 |
++----------------+------------------------------------------------------------------+
+1 row in set (0.00 sec)
+mysql> SELECT * FROM information_schema.placement_policies WHERE NAME = 'rg1'; -- Displays the runtime status of the resource group rg1.
++--------+---------+------+-----------+------+-----------+------+----------------+-----------------+
+| NAME   | MODE    | RRU  | RRU_TOKEN | WRU  | WRU_TOKEN | CPU  | READ_BANDWIDTH | WRITE_BANDWIDTH |
++--------+---------+------+-----------+------+-----------+------+----------------+-----------------+
+| rg1 | RU_MODE | 1000 |    168999 | 2000 |    249999 | NULL |           NULL |            NULL |
++--------+---------+------+-----------+------+-----------+------+----------------+-----------------+
+1 row in set (0.02 sec)
+```
+
+```sql
+mysql> CREATE RESOURCE GROUP rg2 CPU="8" IO_READ_BANDWIDTH="1000Mi" IO_WRITE_BANDWIDTH="1000Mi"; -- Use RAW_MODE to create the resource group rg2
+Query OK, 0 rows affected (0.20 sec)
+mysql> show create resource group rg2; -- Displays the definition of the rg2 resource group.
++----------------+-----------------------------------------------------------------------------------------------+
+| Resource_Group | Create Resource Group                                                                         |
++----------------+-----------------------------------------------------------------------------------------------+
+| rg2         | CREATE RESOURCE GROUP `rg2` CPU="8" IO_READ_BANDWIDTH="1000Mi" IO_WRITE_BANDWIDTH="1000Mi" |
++----------------+-----------------------------------------------------------------------------------------------+
+1 row in set (0.00 sec)
+mysql> SELECT * FROM information_schema.resource_groups WHERE NAME = 'rg2'; -- Displays the runtime status of the resource group rg2.
++--------+----------+------+-----------+------+-----------+------+----------------+-----------------+
+| NAME   | MODE     | RRU  | RRU_TOKEN | WRU  | WRU_TOKEN | CPU  | READ_BANDWIDTH | WRITE_BANDWIDTH |
++--------+----------+------+-----------+------+-----------+------+----------------+-----------------+
+| rg2 | RAW_MODE | NULL |      NULL | NULL |      NULL | 8000 |     1048576000 |      1048576000 |
++--------+----------+------+-----------+------+-----------+------+----------------+-----------------+
+1 row in set (0.00 sec)
+```

privilege-management.md

@@ -364,6 +364,18 @@ Requires `SUPER` privilege.
 
 Requires `SUPER` or `CONNECTION_ADMIN` privilege to kill other user sessions.
 
+### CREATE RESOURCE GROUP
+
+Requires `SUPER` or `RESOURCE_GROUP_ADMIN` privilege.
+
+### ALTER RESOURCE GROUP
+
+Requires `SUPER` or `RESOURCE_GROUP_ADMIN` privilege.
+
+### DROP RESOURCE GROUP
+
+Requires `SUPER` or `RESOURCE_GROUP_ADMIN` privilege.
+
 ## Implementation of the privilege system
 
 ### Privilege table

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

@@ -0,0 +1,92 @@
+---
+title: ALTER RESOURCE GROUP
+summary: Learn the usage of ALTER RESOURCE GROUP in TiDB.
+---
+
+# ALTER RESOURCE GROUP
+
+The `ALTER RESOURCE GROUP` statement is used to modify the resource group in a database.
+
+## Synopsis
+
+```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 supports the following `DirectResourceGroupOption`, where [RU (Resource Unit)](/tidb-RU.md) is TiDB's unified abstraction unit for CPU, IO, and other system resources.
+
+| Parameter     | Description                         | Example                |
+|---------------|-------------------------------------|------------------------|
+|`RRU_PER_SEC`  | Quota of RU read per second         |`RRU_PER_SEC = 500`     |
+|`WRU_PER_SEC`  | Quota of RU write per second        |`WRU_PER_SEC = 300`     |
+
+If the `BURSTABLE` attribute is set, the corresponding resource group allows the system resources to be used exceeding the quota if the system resources are sufficient.
+
+> **Note:**
+> 
+> The `ALTER RESOURCE GROUP` statement can only be executed when the global variable [`tidb_enable_resource_group`](/system-variables.md#tidb_enable_resource_control-new-in-v660) is set to `ON`.
+
+## Examples
+
+Create a resource group named `rg1` and modify its properties.
+
+```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 compatibility
+
+MySQL also supports [ALTER RESOURCE GROUP](https://dev.mysql.com/doc/refman/8.0/en/alter-resource-group.html). However, the accepted parameters are different from TiDB so that they are not compatible.
+
+## See also
+
+* [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)