update doc for max_user_connections. (#19898)

Author: joccau

mysql-schema/mysql-schema-user.md

@@ -63,8 +63,9 @@ DESC mysql.user;
 | Password_expired       | enum('N','Y')     | NO   |      | N                 |       |
 | Password_last_changed  | timestamp         | YES  |      | CURRENT_TIMESTAMP |       |
 | Password_lifetime      | smallint unsigned | YES  |      | NULL              |       |
+| max_user_connections   | int unsigned      | NO   |      | 0                 |       |
 +------------------------+-------------------+------+------+-------------------+-------+
-44 rows in set (0.00 sec)
+45 rows in set (0.00 sec)
 ```
 
 `mysql.user` 表包含多个字段，可分为三组：

security-compatibility-with-mysql.md

@@ -11,7 +11,7 @@ TiDB 支持与 MySQL 5.7 类似的安全特性，同时 TiDB 还支持 MySQL 8.0
 ## 不支持的安全功能特性
 
 - 不支持列级别权限设置。
-- 不支持权限属性 `max_questions`，`max_updated` 以及 `max_user_connections`。
+- 不支持权限属性 `max_questions`、`max_updated`。
 - 不支持密码修改验证策略，修改密码时需要验证当前密码。
 - 不支持双密码策略。
 - 不支持随机密码生成策略。

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

@@ -32,6 +32,9 @@ Username ::=
 AuthOption ::=
     ( 'IDENTIFIED' ( 'BY' ( AuthString | 'PASSWORD' HashString ) | 'WITH' StringName ( 'BY' AuthString | 'AS' HashString )? ) )?
 
+ConnectionOptions ::=
+    ( 'WITH' 'MAX_USER_CONNECTIONS' N )?
+
 PasswordOption ::= ( 'PASSWORD' 'EXPIRE' ( 'DEFAULT' | 'NEVER' | 'INTERVAL' N 'DAY' )? | 'PASSWORD' 'HISTORY' ( 'DEFAULT' | N ) | 'PASSWORD' 'REUSE' 'INTERVAL' ( 'DEFAULT' | N 'DAY' ) | 'FAILED_LOGIN_ATTEMPTS' N | 'PASSWORD_LOCK_TIME' ( N | 'UNBOUNDED' ) )*
 
 LockOption ::= ( 'ACCOUNT' 'LOCK' | 'ACCOUNT' 'UNLOCK' )?
@@ -177,6 +180,22 @@ ALTER USER 'newuser' PASSWORD REUSE INTERVAL 90 DAY;
 Query OK, 0 rows affected (0.02 sec)
 ```
 
+通过 `ALTER USER ... WITH MAX_USER_CONNECTIONS N` 修改用户 `newuser` 允许登录的最大连接数：
+
+```sql
+ALTER USER 'newuser' WITH MAX_USER_CONNECTIONS 3;
+SELECT User, Host, max_user_connections FROM mysql.user WHERE User='newuser';
+```
+
+```
++---------+------+----------------------+
+| User    | Host | max_user_connections |
++---------+------+----------------------+
+| newuser | %    |                    3 |
++---------+------+----------------------+
+1 row in set (0.01 sec)
+```
+
 ### 修改用户绑定的资源组
 
 通过 `ALTER USER ... RESOURCE GROUP` 修改用户 `newuser` 的资源组到 `rg1`：

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

@@ -36,6 +36,9 @@ StringName ::=
     stringLit
 |   Identifier
 
+ConnectionOptions ::=
+    ( 'WITH' 'MAX_USER_CONNECTIONS' N )?
+
 PasswordOption ::= ( 'PASSWORD' 'EXPIRE' ( 'DEFAULT' | 'NEVER' | 'INTERVAL' N 'DAY' )?
 | 'PASSWORD' 'HISTORY' ( 'DEFAULT' | N )
 | 'PASSWORD' 'REUSE' 'INTERVAL' ( 'DEFAULT' | N 'DAY' )
@@ -168,18 +171,34 @@ CREATE USER 'newuser9'@'%' PASSWORD EXPIRE;
 Query OK, 1 row affected (0.02 sec)
 ```
 
+创建一个限制最大连接数为 3 的用户。
+
+```sql
+CREATE USER 'newuser10'@'%' WITH MAX_USER_CONNECTIONS 3;
+SELECT User, Host, max_user_connections FROM mysql.user WHERE User='newuser10';
+```
+
+```
++-----------+------+----------------------+
+| user      | host | max_user_connections |
++-----------+------+----------------------+
+| newuser10 | %    |                    3 |
++-----------+------+----------------------+
+1 row in set (0.01 sec)
+```
+
 创建一个使用资源组 `rg1` 的用户：
 
 ```sql
-CREATE USER 'newuser7'@'%' RESOURCE GROUP rg1;
-SELECT USER, HOST, USER_ATTRIBUTES FROM MYSQL.USER WHERE USER='newuser7';
+CREATE USER 'newuser11'@'%' RESOURCE GROUP rg1;
+SELECT USER, HOST, USER_ATTRIBUTES FROM MYSQL.USER WHERE USER='newuser11';
 ```
 
 ```sql
 +-----------+------+---------------------------------------------------+
 | USER      | HOST | USER_ATTRIBUTES                                   |
 +-----------+------+---------------------------------------------------+
-| newuser7  | %    | {"resource_group": "rg1"} |
+| newuser11 | %    | {"resource_group": "rg1"}                         |
 +-----------+------+---------------------------------------------------+
 1 rows in set (0.00 sec)
 ```
@@ -191,7 +210,6 @@ TiDB 不支持以下 `CREATE USER` 选项。这些选项可被解析，但会被
 * `PASSWORD REQUIRE CURRENT DEFAULT`
 * `WITH MAX_QUERIES_PER_HOUR`
 * `WITH MAX_UPDATES_PER_HOUR`
-* `WITH MAX_USER_CONNECTIONS`
 
 TiDB 也不支持以下 `CREATE USER` 选项。这些选项无法被语法解析器解析。
 

system-variables.md

@@ -666,6 +666,18 @@ mysql> SHOW GLOBAL VARIABLES LIKE 'max_prepared_stmt_count';
 - 在 `SESSION` 作用域下，该变量为只读变量。
 - 该变量的行为与 MySQL 兼容。
 
+### `max_user_connections` <span class="version-mark">从 v9.0.0 版本开始引入</span>
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
+- 类型：整数型
+- 默认值：`0`
+- 取值范围：`[0, 100000]`
+- 该变量控制 TiDB 中单个用户允许连接至一个 TiDB Server 实例的最大连接数，用于资源控制。
+- 默认值为 `0`，表示不限制用户的连接数。当值大于 `0` 且用户连接数达到此值时，TiDB 服务端将拒绝该用户的连接。
+- 当该变量的取值超过 [`max_connections`](/tidb-configuration-file.md#max_connections) 时，TiDB 会采用 `max_connections` 的值作为单个用户实际可建立的最大连接数。例如，若某用户的 `max_user_connections` 设置为 `2000`，而 `max_connections` 为 `1000`，则该用户实际可连接至一个 TiDB Server 实例的最大连接数为 `1000`。
+
 ### `mpp_exchange_compression_mode` <span class="version-mark">从 v6.6.0 版本开始引入</span>
 
 - 作用域：SESSION | GLOBAL