Skip to content

Commit 207b09d

Browse files
github-actions[bot]github-actions[bot]
committed
Auto-sync: Update English docs from Chinese PR
Synced from: pingcap/docs-cn#21437 Target PR: pingcap#22574 AI Provider: gemini Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent f52c22b commit 207b09d

File tree

6 files changed

+174
-3
lines changed

6 files changed

+174
-3
lines changed

‎TOC.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -627,6 +627,7 @@
627627
- Privileges
628628
- [Security Compatibility with MySQL](/security-compatibility-with-mysql.md)
629629
- [Privilege Management](/privilege-management.md)
630+
- [Column Privilege Management](/column-privilege-management.md)
630631
- [User Account Management](/user-account-management.md)
631632
- [TiDB Password Management](/password-management.md)
632633
- [Role-Based Access Control](/role-based-access-control.md)

‎column-privilege-management.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
```markdown
2+
title: Column-Level Privilege Management
3+
summary: TiDB supports a MySQL-compatible column-level privilege management mechanism, allowing you to grant or revoke `SELECT`, `INSERT`, `UPDATE`, and `REFERENCES` privileges on specific columns of a table using `GRANT` or `REVOKE`, thus achieving finer-grained access control.
4+
---
5+
6+
# Column-Level Privilege Management
7+
8+
Starting from version v8.5.6, TiDB supports a MySQL-compatible column-level privilege management mechanism. With column-level privileges, you can grant or revoke `SELECT`, `INSERT`, `UPDATE`, and `REFERENCES` privileges on specific columns of a table, achieving finer-grained data access control.
9+
10+
> **Note:**
11+
>
12+
> Although MySQL syntax allows column-level specification like `REFERENCES(col_name)`, `REFERENCES` itself is a database/table-level privilege used for foreign key-related permission checks. Therefore, column-level `REFERENCES` does not actually take effect in MySQL. TiDB's behavior is consistent with MySQL.
13+
14+
## Syntax
15+
16+
Granting and revoking column-level privileges are similar to table-level privileges, with the following differences:
17+
18+
- The column name list is placed after the **privilege type**, not after the **table name**.
19+
- Multiple column names are separated by commas (`,`).
20+
21+
```sql
22+
GRANT priv_type(col_name [, col_name] ...) [, priv_type(col_name [, col_name] ...)] ...
23+
ON db_name.tbl_name
24+
TO 'user'@'host';
25+
26+
REVOKE priv_type(col_name [, col_name] ...) [, priv_type(col_name [, col_name] ...)] ...
27+
ON db_name.tbl_name
28+
FROM 'user'@'host';
29+
```
30+
31+
Where:
32+
33+
* `priv_type` supports `SELECT`, `INSERT`, `UPDATE`, and `REFERENCES`.
34+
* The `ON` clause requires specifying the specific table, for example, `test.tbl`.
35+
* A single `GRANT` or `REVOKE` statement can include multiple privilege items, and each privilege item can specify its own list of column names.
36+
37+
For example, the following statement grants `SELECT` privileges on `col1` and `col2` and `UPDATE` privilege on `col3` to the user:
38+
39+
```sql
40+
GRANT SELECT(col1, col2), UPDATE(col3) ON test.tbl TO 'user'@'host';
41+
```
42+
43+
## Granting Column-Level Privileges
44+
45+
The following example grants the `SELECT` privilege on `col1` and `col2` of table `test.tbl` to user `newuser`, and grants the `UPDATE` privilege on `col3` to the same user:
46+
47+
```sql
48+
CREATE DATABASE IF NOT EXISTS test;
49+
USE test;
50+
51+
DROP TABLE IF EXISTS tbl;
52+
CREATE TABLE tbl (col1 INT, col2 INT, col3 INT);
53+
54+
DROP USER IF EXISTS 'newuser'@'%';
55+
CREATE USER 'newuser'@'%';
56+
57+
GRANT SELECT(col1, col2), UPDATE(col3) ON test.tbl TO 'newuser'@'%';
58+
SHOW GRANTS FOR 'newuser'@'%';
59+
```
60+
61+
```
62+
+---------------------------------------------------------------------+
63+
| Grants for newuser@% |
64+
+---------------------------------------------------------------------+
65+
| GRANT USAGE ON *.* TO 'newuser'@'%' |
66+
| GRANT SELECT(col1, col2), UPDATE(col3) ON test.tbl TO 'newuser'@'%' |
67+
+---------------------------------------------------------------------+
68+
```
69+
70+
In addition to using `SHOW GRANTS`, you can also view column-level privilege information by querying [`INFORMATION_SCHEMA.COLUMN_PRIVILEGES`](/information-schema/information-schema-columns.md).
71+
72+
## Revoking Column-Level Privileges
73+
74+
The following example revokes the `SELECT` privilege on column `col2` from user `newuser`:
75+
76+
```sql
77+
REVOKE SELECT(col2) ON test.tbl FROM 'newuser'@'%';
78+
SHOW GRANTS FOR 'newuser'@'%';
79+
```
80+
81+
```
82+
+---------------------------------------------------------------+
83+
| Grants for newuser@% |
84+
+---------------------------------------------------------------+
85+
| GRANT USAGE ON *.* TO 'newuser'@'%' |
86+
| GRANT SELECT(col1), UPDATE(col3) ON test.tbl TO 'newuser'@'%' |
87+
+---------------------------------------------------------------+
88+
```
89+
90+
## Column-Level Privilege Access Control Example
91+
92+
After granting or revoking column-level privileges, TiDB performs privilege checks on columns referenced in SQL statements. For example:
93+
94+
* `SELECT` statements: `SELECT` column privileges affect columns referenced in the `SELECT` list as well as `WHERE`, `ORDER BY`, and other clauses.
95+
* `UPDATE` statements: Columns being updated in the `SET` clause require `UPDATE` column privileges. Columns read in expressions or conditions usually also require `SELECT` column privileges.
96+
* `INSERT` statements: Columns being written to require `INSERT` column privileges. `INSERT INTO t VALUES (...)` is equivalent to writing to all columns.
97+
98+
In the following example, user `newuser` can only query `col1` and update `col3`:
99+
100+
```sql
101+
-- Execute as newuser
102+
SELECT col1 FROM tbl;
103+
SELECT * FROM tbl; -- Error (missing SELECT column privilege for col2, col3)
104+
105+
UPDATE tbl SET col3 = 1;
106+
UPDATE tbl SET col1 = 2; -- Error (missing UPDATE column privilege for col1)
107+
108+
UPDATE tbl SET col3 = col1;
109+
UPDATE tbl SET col3 = col3 + 1; -- Error (missing SELECT column privilege for col3)
110+
UPDATE tbl SET col3 = col1 WHERE col1 > 0;
111+
```
112+
113+
## Compatibility Differences with MySQL
114+
115+
TiDB's column-level privileges are generally compatible with MySQL. However, there are differences in the following scenarios:
116+
| Scenario | TiDB | MySQL |
117+
| :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118+
| Revoking column-level privileges not granted to a user | `REVOKE` executes successfully. | `REVOKE` throws an error. |
119+
| Execution order of column pruning and `SELECT` privilege check | `SELECT` column privileges are checked first, then column pruning is performed. For example: executing `SELECT a FROM (SELECT a, b FROM t) s` requires `SELECT` column privileges for both `t.a` and `t.b`. | Column pruning is performed first, then `SELECT` column privileges are checked. For example: executing `SELECT a FROM (SELECT a, b FROM t) s` only requires `SELECT` column privilege for `t.a`. |
120+
121+
### Column Pruning and Privilege Checks in View Scenarios
122+
123+
When performing `SELECT` privilege checks on views, MySQL first prunes columns in the view's internal query and then checks the column privileges of the internal tables, making the checks relatively lenient in some scenarios. TiDB does not perform column pruning before privilege checks, so additional column privileges might be required.
124+
125+
```sql
126+
-- Prepare the environment by logging in as root
127+
DROP USER IF EXISTS 'u'@'%';
128+
CREATE USER 'u'@'%';
129+
130+
DROP TABLE IF EXISTS t;
131+
CREATE TABLE t (a INT, b INT, c INT, d INT);
132+
133+
DROP VIEW IF EXISTS v;
134+
CREATE SQL SECURITY INVOKER VIEW v AS SELECT a, b FROM t WHERE c = 0 ORDER BY d;
135+
136+
GRANT SELECT ON v TO 'u'@'%';
137+
138+
-- Log in as u
139+
SELECT a FROM v;
140+
-- MySQL: Error, missing access privileges for t.a, t.c, t.d
141+
-- TiDB: Error, missing access privileges for t.a, t.b, t.c, t.d
142+
143+
-- Log in as root
144+
GRANT SELECT(a, c, d) ON t TO 'u'@'%';
145+
146+
-- Log in as u
147+
SELECT a FROM v;
148+
-- MySQL: Success (internal query is pruned to `SELECT a FROM t WHERE c = 0 ORDER BY d`)
149+
-- TiDB: Error, missing access privileges for t.b
150+
151+
SELECT * FROM v;
152+
-- MySQL: Error, missing access privileges for t.b
153+
-- TiDB: Error, missing access privileges for t.b
154+
155+
-- Log in as root
156+
GRANT SELECT(b) ON t TO 'u'@'%';
157+
158+
-- Log in as u
159+
SELECT * FROM v;
160+
-- MySQL: Success
161+
-- TiDB: Success
162+
```
163+
164+
## See Also
165+
166+
* [Privilege Management](/privilege-management.md)
167+
* [`GRANT <privileges>`](/sql-statements/sql-statement-grant-privileges.md)
168+
* [`REVOKE <privileges>`](/sql-statements/sql-statement-revoke-privileges.md)
169+
```

‎mysql-compatibility.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,10 @@ You can try out TiDB features on [TiDB Playground](https://play.tidbcloud.com/?u
5151
> Currently, only {{{ .starter }}} and {{{ .essential }}} clusters in certain AWS regions support [`FULLTEXT` syntax and indexes](https://docs.pingcap.com/tidbcloud/vector-search-full-text-search-sql). TiDB Self-Managed and TiDB Cloud Dedicated support parsing the `FULLTEXT` syntax but do not support using the `FULLTEXT` indexes.
5252
5353
+ `SPATIAL` (also known as `GIS`/`GEOMETRY`) functions, data types and indexes [#6347](https://github.com/pingcap/tidb/issues/6347)
54-
+ Character sets other than `ascii`, `latin1`, `binary`, `utf8`, `utf8mb4`, and `gbk`.
54+
+ Character sets other than `ascii`, `latin1`, `binary`, `utf8`, `utf8mb4`, `gbk`, and `gb18030`.
5555
+ Optimizer trace
5656
+ XML Functions
5757
+ X-Protocol [#1109](https://github.com/pingcap/tidb/issues/1109)
58-
+ Column-level privileges [#9766](https://github.com/pingcap/tidb/issues/9766)
5958
+ `XA` syntax (TiDB uses a two-phase commit internally, but this is not exposed via an SQL interface)
6059
+ `CREATE TABLE tblName AS SELECT stmt` syntax [#4754](https://github.com/pingcap/tidb/issues/4754)
6160
+ `CHECK TABLE` syntax [#4673](https://github.com/pingcap/tidb/issues/4673)

‎privilege-management.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Use the following statement to grant the `xxx` user all privileges on all databa
2929
```sql
3030
GRANT ALL PRIVILEGES ON *.* TO 'xxx'@'%';
3131
```
32+
From v8.5.6, TiDB supports the MySQL-compatible column-level privilege management mechanism. You can grant or revoke `SELECT`, `INSERT`, `UPDATE`, and `REFERENCES` privileges for specific columns at the table level. For more information, see [Column Privilege Management](/column-privilege-management.md).
3233

3334
By default, [`GRANT`](/sql-statements/sql-statement-grant-privileges.md) statements will return an error if the user specified does not exist. This behavior depends on if the [SQL mode](/system-variables.md#sql_mode) `NO_AUTO_CREATE_USER` is specified:
3435

‎sql-statements/sql-statement-grant-privileges.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ mysql> SHOW GRANTS FOR 'newuser';
8282
## MySQL compatibility
8383

8484
* Similar to MySQL, the `USAGE` privilege denotes the ability to log into a TiDB server.
85-
* Column level privileges are not currently supported.
85+
* Starting from v8.5.6, TiDB supports a MySQL-compatible column-level privilege management mechanism. You can grant or revoke `SELECT`, `INSERT`, `UPDATE`, and `REFERENCES` privileges on specific columns at the table level. For more information, see [Column-level privilege management](/column-privilege-management.md).
8686
* Similar to MySQL, when the `NO_AUTO_CREATE_USER` sql mode is not present, the `GRANT` statement will automatically create a new user with an empty password when a user does not exist. Removing this sql-mode (it is enabled by default) presents a security risk.
8787
* In TiDB, after the `GRANT <privileges>` statement is executed successfully, the execution result takes effect immediately on the current connection. Whereas [in MySQL, for some privileges, the execution results take effect only on subsequent connections](https://dev.mysql.com/doc/refman/8.0/en/privilege-changes.html). See [TiDB #39356](https://github.com/pingcap/tidb/issues/39356) for details.
8888

‎sql-statements/sql-statement-revoke-privileges.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ summary: An overview of the usage of REVOKE <privileges> for the TiDB database.
66
# `REVOKE <privileges>`
77

88
This statement removes privileges from an existing user. Executing this statement requires the `GRANT OPTION` privilege and all privileges you revoke.
9+
Starting from TiDB v8.5.6 and subsequent 8.5.x versions, TiDB supports the MySQL-compatible column-level privilege management mechanism. You can specify a list of column names in `REVOKE`, for example `REVOKE SELECT(col2) ON test.tbl FROM 'user'@'host';`. For more information, see [Column Privilege Management](/column-privilege-management.md).
910

1011
## Synopsis
1112

0 commit comments

Comments
 (0)