tidb: add explanation for the fields in mysql.user

TOC-tidb-cloud.md

@@ -572,7 +572,9 @@
       - [Use the `tidb_snapshot` System Variable](/read-historical-data.md)
     - [Placement Rules in SQL](/placement-rules-in-sql.md)
     - System Tables
-      - [`mysql`](/mysql-schema.md)
+      - `mysql` Schema
+        - [Overview](/mysql-schema/mysql-schema.md)
+        - [`user`](/mysql-schema/mysql-schema-user.md)
       - INFORMATION_SCHEMA
         - [Overview](/information-schema/information-schema.md)
         - [`ANALYZE_STATUS`](/information-schema/information-schema-analyze-status.md)

TOC.md

@@ -947,7 +947,9 @@
       - [GBK](/character-set-gbk.md)
     - [Placement Rules in SQL](/placement-rules-in-sql.md)
     - System Tables
-      - [`mysql`](/mysql-schema.md)
+      - `mysql` Schema
+        - [Overview](/mysql-schema/mysql-schema.md)
+        - [`user`](/mysql-schema/mysql-schema-user.md)
       - INFORMATION_SCHEMA
         - [Overview](/information-schema/information-schema.md)
         - [`ANALYZE_STATUS`](/information-schema/information-schema-analyze-status.md)

faq/manage-cluster-faq.md

@@ -29,7 +29,7 @@ TiKV data is located in the [`--data-dir`](/command-line-flags-for-tikv-configur
 
 ### What are the system tables in TiDB?
 
-Similar to MySQL, TiDB includes system tables as well, used to store the information required by the server when it runs. See [TiDB system table](/mysql-schema.md).
+Similar to MySQL, TiDB includes system tables as well, used to store the information required by the server when it runs. See [TiDB system table](/mysql-schema/mysql-schema.md).
 
 ### Where are the TiDB/PD/TiKV logs?
 

mysql-schema/mysql-schema-user.md

@@ -0,0 +1,110 @@
+---
+title: `mysql.user`
+summary: Learn about the `user` table in the `mysql` schema.
+---
+
+# `mysql.user`
+
+The `mysql.user` table provides information about user accounts and their privileges.
+
+To view the structure of `mysql.user`, use the following SQL statement:
+
+```sql
+DESC mysql.user;
+```
+
+The output is as follows:
+
+```
++------------------------+----------------------+------+------+-------------------+-------+
+| Field                  | Type                 | Null | Key  | Default           | Extra |
++------------------------+----------------------+------+------+-------------------+-------+
+| Host                   | char(255)            | NO   | PRI  | NULL              |       |
+| User                   | char(32)             | NO   | PRI  | NULL              |       |
+| authentication_string  | text                 | YES  |      | NULL              |       |
+| plugin                 | char(64)             | YES  |      | NULL              |       |
+| Select_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| Insert_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| Update_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| Delete_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| Create_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| Drop_priv              | enum('N','Y')        | NO   |      | N                 |       |
+| Process_priv           | enum('N','Y')        | NO   |      | N                 |       |
+| Grant_priv             | enum('N','Y')        | NO   |      | N                 |       |
+| References_priv        | enum('N','Y')        | NO   |      | N                 |       |
+| Alter_priv             | enum('N','Y')        | NO   |      | N                 |       |
+| Show_db_priv           | enum('N','Y')        | NO   |      | N                 |       |
+| Super_priv             | enum('N','Y')        | NO   |      | N                 |       |
+| Create_tmp_table_priv  | enum('N','Y')        | NO   |      | N                 |       |
+| Lock_tables_priv       | enum('N','Y')        | NO   |      | N                 |       |
+| Execute_priv           | enum('N','Y')        | NO   |      | N                 |       |
+| Create_view_priv       | enum('N','Y')        | NO   |      | N                 |       |
+| Show_view_priv         | enum('N','Y')        | NO   |      | N                 |       |
+| Create_routine_priv    | enum('N','Y')        | NO   |      | N                 |       |
+| Alter_routine_priv     | enum('N','Y')        | NO   |      | N                 |       |
+| Index_priv             | enum('N','Y')        | NO   |      | N                 |       |
+| Create_user_priv       | enum('N','Y')        | NO   |      | N                 |       |
+| Event_priv             | enum('N','Y')        | NO   |      | N                 |       |
+| Repl_slave_priv        | enum('N','Y')        | NO   |      | N                 |       |
+| Repl_client_priv       | enum('N','Y')        | NO   |      | N                 |       |
+| Trigger_priv           | enum('N','Y')        | NO   |      | N                 |       |
+| Create_role_priv       | enum('N','Y')        | NO   |      | N                 |       |
+| Drop_role_priv         | enum('N','Y')        | NO   |      | N                 |       |
+| Account_locked         | enum('N','Y')        | NO   |      | N                 |       |
+| Shutdown_priv          | enum('N','Y')        | NO   |      | N                 |       |
+| Reload_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| FILE_priv              | enum('N','Y')        | NO   |      | N                 |       |
+| Config_priv            | enum('N','Y')        | NO   |      | N                 |       |
+| Create_Tablespace_Priv | enum('N','Y')        | NO   |      | N                 |       |
+| Password_reuse_history | smallint(5) unsigned | YES  |      | NULL              |       |
+| Password_reuse_time    | smallint(5) unsigned | YES  |      | NULL              |       |
+| User_attributes        | json                 | YES  |      | NULL              |       |
+| Token_issuer           | varchar(255)         | YES  |      | NULL              |       |
+| Password_expired       | enum('N','Y')        | NO   |      | N                 |       |
+| Password_last_changed  | timestamp            | YES  |      | CURRENT_TIMESTAMP |       |
+| Password_lifetime      | smallint(5) unsigned | YES  |      | NULL              |       |
++------------------------+----------------------+------+------+-------------------+-------+
+44 rows in set (0.00 sec)
+```
+
+The `mysql.user` table contains several fields that can be categorized into three groups:
+
+<CustomContent platform="tidb">
+
+* Scope:
+    * `Host`: specifies the hostname of a TiDB account.
+    * `User`: specifies the username of a TiDB account.
+* Privilege:
+
+    The fields ending with `_priv` or `_Priv` define the permissions granted to a user account. For example, `Select_priv` means that the user has global `Select` privilege. For more information, see [Privileges required for TiDB operations](/privilege-management.md#privileges-required-for-tidb-operations).
+
+* Security:
+    * `authentication_string` and `plugin`: `authentication_string` stores the credentials for the user account. The credentials are interpreted based on the authentication plugin specified in the `plugin` field.
+    * `Account_locked`: indicates whether the user account is locked.
+    * `Password_reuse_history` and `Password_reuse_time`: used for [Password reuse policy](/password-management.md#password-reuse-policy).
+    * `User_attributes`: provides information about user comments and user attributes.
+    * `Token_issuer`: used for the [`tidb_auth_token`](/security-compatibility-with-mysql.md#tidb_auth_token) authentication plugin.
+    * `Password_expired`, `Password_last_changed`, and `Password_lifetime`: used for [Password expiration policy](/password-management.md#password-expiration-policy).
+
+</CustomContent>
+
+<CustomContent platform="tidb-cloud">
+
+* Scope:
+    * `Host`: specifies the hostname of a TiDB account.
+    * `User`: specifies the username of a TiDB account.
+* Privilege:
+
+    The fields ending with `_priv` or `_Priv` define the permissions granted to a user account. For example, `Select_priv` means that the user has global `Select` privilege. For more information, see [Privileges required for TiDB operations](https://docs.pingcap.com/tidb/stable/privilege-management#privileges-required-for-tidb-operations).
+
+* Security:
+    * `authentication_string` and `plugin`: `authentication_string` stores the credentials for the user account. The credentials are interpreted based on the authentication plugin specified in the `plugin` field.
+    * `Account_locked`: indicates whether the user account is locked.
+    * `Password_reuse_history` and `Password_reuse_time`: used for [Password reuse policy](https://docs.pingcap.com/tidb/stable/password-management#password-reuse-policy).
+    * `User_attributes`: provides information about user comments and user attributes.
+    * `Token_issuer`: used for the [`tidb_auth_token`](https://docs.pingcap.com/tidb/stable/security-compatibility-with-mysql#tidb_auth_token) authentication plugin.
+    * `Password_expired`, `Password_last_changed`, and `Password_lifetime`: used for [Password expiration policy](https://docs.pingcap.com/tidb/stable/password-management#password-expiration-policy).
+
+</CustomContent>
+
+Although most of the fields in the TiDB `mysql.user` table also exist in the MySQL `mysql.user` table, the `Token_issuer` field is specific to TiDB.

mysql-schema.md → mysql-schema/mysql-schema.md

@@ -8,11 +8,15 @@ aliases: ['/docs/dev/system-tables/system-table-overview/','/docs/dev/reference/
 
 The `mysql` schema contains TiDB system tables. The design is similar to the `mysql` schema in MySQL, where tables such as `mysql.user` can be edited directly. It also contains a number of tables which are extensions to MySQL.
 
+> **Note:**
+>
+> In most scenarios, it is not recommended to change the content of system tables directly using `INSERT`, `UPDATE`, or `DELETE`. Instead, use statements such as [`CREATE USER`](/sql-statements/sql-statement-create-user.md), [`ALTER USER`](/sql-statements/sql-statement-alter-user.md), [`DROP USER`](/sql-statements/sql-statement-drop-user.md), [`GRANT`](/sql-statements/sql-statement-grant-privileges.md), [`REVOKE`](/sql-statements/sql-statement-revoke-privileges.md), and [`SHOW CREATE USER`](/sql-statements/sql-statement-show-create-user.md) to manage users and privileges. If direct modification of system tables is unavoidable, use [`FLUSH PRIVILEGES`](/sql-statements/sql-statement-flush-privileges.md) to make the changes take effect.
+
 ## Grant system tables
 
 These system tables contain grant information about user accounts and their privileges:
 
-- `user`: user accounts, global privileges, and other non-privilege columns
+- [`user`](/mysql-schema/mysql-schema-user.md): user accounts, global privileges, and other non-privilege columns
 - `db`: database-level privileges
 - `tables_priv`: table-level privileges
 - `columns_priv`: column-level privileges

privilege-management.md

@@ -502,7 +502,7 @@ When the system variable [`tidb_resource_control_strict_mode`](/system-variables
 
 ### Privilege table
 
-The following [`mysql` system tables](/mysql-schema.md) are special because all the privilege-related data is stored in them:
+The following [`mysql` system tables](/mysql-schema/mysql-schema.md) are special because all the privilege-related data is stored in them:
 
 - `mysql.user` (user account, global privilege)
 - `mysql.db` (database-level privilege)

releases/release-7.6.0.md

@@ -222,7 +222,7 @@ Quick access: [Quick start](https://docs.pingcap.com/tidb/v7.6/quick-start-with-
     * [Statement Summary Tables](/statement-summary-tables.md): add the resource group name, RU consumption, and time for waiting for resources.
     * In the system variable [`tidb_last_query_info`](/system-variables.md#tidb_last_query_info-new-in-v4014), add a new entry `ru_consumption` to indicate the consumed [RU](/tidb-resource-control.md#what-is-request-unit-ru) by SQL statements. You can use this variable to get the resource consumption of the last statement in the session.
     * Add database metrics based on resource groups: QPS/TPS, execution time (P999/P99/P95), number of failures, and number of connections.
-    * Add the system table [`request_unit_by_group`](/mysql-schema.md#system-tables-related-to-resource-control) to record the history records of daily consumed RUs of all resource groups.
+    * Add the system table [`request_unit_by_group`](/mysql-schema/mysql-schema.md#system-tables-related-to-resource-control) to record the history records of daily consumed RUs of all resource groups.
 
   For more information, see [Identify Slow Queries](/identify-slow-queries.md), [Statement Summary Tables](/statement-summary-tables.md), and [Key Monitoring Metrics of Resource Control](/grafana-resource-control-dashboard.md).
 

statistics.md

@@ -154,13 +154,13 @@ If a table has many columns, collecting statistics on all the columns can cause
 
         <CustomContent platform="tidb">
 
-        After the setting, TiDB writes the `PREDICATE COLUMNS` information to the [`mysql.column_stats_usage`](/mysql-schema.md#statistics-system-tables) system table every 100 * [`stats-lease`](/tidb-configuration-file.md#stats-lease).
+        After the setting, TiDB writes the `PREDICATE COLUMNS` information to the [`mysql.column_stats_usage`](/mysql-schema/mysql-schema.md#statistics-system-tables) system table every 100 * [`stats-lease`](/tidb-configuration-file.md#stats-lease).
 
         </CustomContent>
 
         <CustomContent platform="tidb-cloud">
 
-        After the setting, TiDB writes the `PREDICATE COLUMNS` information to the [`mysql.column_stats_usage`](/mysql-schema.md#statistics-system-tables) system table every 300 seconds.
+        After the setting, TiDB writes the `PREDICATE COLUMNS` information to the [`mysql.column_stats_usage`](/mysql-schema/mysql-schema.md#statistics-system-tables) system table every 300 seconds.
 
         </CustomContent>
 
@@ -174,7 +174,7 @@ If a table has many columns, collecting statistics on all the columns can cause
 
         > **Note:**
         >
-        > - If the [`mysql.column_stats_usage`](/mysql-schema.md#statistics-system-tables) system table does not contain any `PREDICATE COLUMNS` recorded for that table, the preceding syntax collects statistics on all columns and all indexes in that table.
+        > - If the [`mysql.column_stats_usage`](/mysql-schema/mysql-schema.md#statistics-system-tables) system table does not contain any `PREDICATE COLUMNS` recorded for that table, the preceding syntax collects statistics on all columns and all indexes in that table.
         > - Any columns excluded from collection (either by manually listing columns or using `PREDICATE COLUMNS`) will not have their statistics overwritten. When executing a new type of SQL query, the optimizer will use the old statistics for such columns if it exists or pseudo column statistics if columns never had statistics collected. The next ANALYZE using `PREDICATE COLUMNS` will collect the statistics on those columns.
 
 - To collect statistics on all columns and indexes, use the following syntax:

tidb-resource-control.md

@@ -589,7 +589,7 @@ The system table [`INFORMATION_SCHEMA.statements_summary`](/statement-summary-ta
 
 ### View the RU consumption of resource groups
 
-Starting from v7.6.0, TiDB provides the system table [`mysql.request_unit_by_group`](/mysql-schema.md#system-tables-related-to-resource-control) to store the historical records of the RU consumption of each resource group.
+Starting from v7.6.0, TiDB provides the system table [`mysql.request_unit_by_group`](/mysql-schema/mysql-schema.md#system-tables-related-to-resource-control) to store the historical records of the RU consumption of each resource group.
 
 Example:
 

user-account-management.md

@@ -10,7 +10,7 @@ This document describes how to manage a TiDB user account.
 
 ## User names and passwords
 
-TiDB stores the user accounts in the table of the [`mysql.user`](/mysql-schema.md) system table. Each account is identified by a user name and the client host. Each account may have a password.
+TiDB stores the user accounts in the table of the [`mysql.user`](/mysql-schema/mysql-schema-user.md) system table. Each account is identified by a user name and the client host. Each account may have a password.
 
 You can connect to the TiDB server using the MySQL client, and use the specified account and password to login. For each user name, make sure that it contains no more than 32 characters.
 
@@ -37,7 +37,7 @@ You can also create accounts by using [third party GUI tools](/develop/dev-guide
 CREATE USER [IF NOT EXISTS] user [IDENTIFIED BY 'auth_string'];
 ```
 
-After you assign the password, TiDB hashes and stores the `auth_string` in the [`mysql.user`](/mysql-schema.md) table.
+After you assign the password, TiDB hashes and stores the `auth_string` in the [`mysql.user`](/mysql-schema/mysql-schema-user.md) table.
 
 ```sql
 CREATE USER 'test'@'127.0.0.1' IDENTIFIED BY 'xxx';
@@ -138,7 +138,7 @@ To remove a user account, use the [`DROP USER`](/sql-statements/sql-statement-dr
 DROP USER 'test'@'localhost';
 ```
 
-This operation clears the user's records in the [`mysql.user`](/mysql-schema.md) table and the related records in the privilege table.
+This operation clears the user's records in the [`mysql.user`](/mysql-schema/mysql-schema-user.md) table and the related records in the privilege table.
 
 ## Reserved user accounts
 
@@ -150,7 +150,7 @@ TiDB can limit the resources consumed by users using resource groups. For more i
 
 ## Assign account passwords
 
-TiDB stores passwords in the [`mysql.user`](/mysql-schema.md) system table. Operations that assign or update passwords are permitted only to users with the `CREATE USER` privilege, or, alternatively, privileges for the `mysql` database (`INSERT` privilege to create new accounts, `UPDATE` privilege to update existing accounts).
+TiDB stores passwords in the [`mysql.user`](/mysql-schema/mysql-schema-user.md) system table. Operations that assign or update passwords are permitted only to users with the `CREATE USER` privilege, or, alternatively, privileges for the `mysql` database (`INSERT` privilege to create new accounts, `UPDATE` privilege to update existing accounts).
 
 - To assign a password when you create a new account, use [`CREATE USER`](/sql-statements/sql-statement-create-user.md) and include an `IDENTIFIED BY` clause: