*: add column-level masking policy feature document by tiancaiamao · Pull Request #21454 · pingcap/docs-cn

tiancaiamao · 2026-03-23T09:20:14Z

First-time contributors' checklist

I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions (in Chinese).

What is the related PR or file link(s)?

This PR is translated from:
Other reference link(s): *: add document for column-level masking policy feature docs#22613

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

qiancai · 2026-03-24T10:44:13Z

@tiancaiamao Please involve a tech reviewer for this PR. Thanks.

Frank945946 · 2026-04-01T10:00:41Z

+    END
+  ENABLE;
+
+-- 即使用户看到脱敏数据，过滤仍然有效


Suggested change

-- 即使用户看到脱敏数据，过滤仍然有效

-- 即使用户在 Where 条件输入未脱敏数据，过滤仍然有效

bb7133 · 2026-05-09T02:57:34Z

Please address the comments~

ti-chi-bot · 2026-05-09T07:48:48Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from qiancai. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ti-chi-bot · 2026-05-09T07:51:11Z

@tiancaiamao: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-verify	`004d0fa`	link	true	`/test pull-verify`

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

qiancai · 2026-05-11T09:08:27Z

+---
+title: 列级脱敏策略
+summary: 本文介绍如何使用列级脱敏策略来保护 TiDB 中的敏感数据。
+aliases: ['/docs/dev/column-level-masking-policy/']


Suggested change

aliases: ['/docs/dev/column-level-masking-policy/']

reason: aliases are only needed for docs that replace existing docs

qiancai · 2026-05-11T09:26:25Z

+
+# 列级脱敏策略
+
+列级脱敏策略是一项安全功能，允许你在列级别应用脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会根据定义的规则自动对返回给用户的数据进行脱敏，而原始数据在存储中保持不变。


Suggested change

列级脱敏策略是一项安全功能，允许你在列级别应用脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会根据定义的规则自动对返回给用户的数据进行脱敏，而原始数据在存储中保持不变。

列级脱敏策略是 TiDB 中的一项安全功能，允许你为表中的指定列创建脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会按照定义的规则自动对返回给用户的查询结果数据进行脱敏，而原始数据在存储中保持不变。

qiancai · 2026-05-11T09:29:26Z

+
+列级脱敏策略是一项安全功能，允许你在列级别应用脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会根据定义的规则自动对返回给用户的数据进行脱敏，而原始数据在存储中保持不变。
+
+此功能对于满足 PCI-DSS（支付卡行业数据安全标准）等合规要求以及数据隐私法规（如 GDPR - 通用数据保护条例、CCPA - 加州消费者隐私法案）特别有用，这些法规要求严格控制谁可以查看信用卡号、个人标识符和其他机密信息等敏感信息。


Suggested change

此功能对于满足 PCI-DSS（支付卡行业数据安全标准）等合规要求以及数据隐私法规（如 GDPR - 通用数据保护条例、CCPA - 加州消费者隐私法案）特别有用，这些法规要求严格控制谁可以查看信用卡号、个人标识符和其他机密信息等敏感信息。

列级脱敏策略适用于需要限制敏感数据可见性的场景，例如控制信用卡号、身份证号、电话号码、电子邮件地址、出生日期等敏感信息的访问范围。

qiancai · 2026-05-11T09:31:32Z

+
+## 概述
+
+脱敏策略绑定到表列，并在查询结果时进行评估。策略使用 SQL 表达式根据当前用户身份或角色来确定如何对数据进行脱敏。


Suggested change

脱敏策略绑定到表列，并在查询结果时进行评估。策略使用 SQL 表达式根据当前用户身份或角色来确定如何对数据进行脱敏。

脱敏策略绑定到表中的单个列。每个列最多只能绑定一个脱敏策略。策略表达式通常使用 SQL `CASE WHEN` 表达式，并结合 `CURRENT_USER()` 或 `CURRENT_ROLE()` 判断当前会话是否可以查看原始值。

qiancai · 2026-05-11T09:32:22Z

+- **结果时脱敏**：数据在返回给客户端时进行脱敏，而不是以脱敏形式存储
+- **支持用户/角色**：不同用户可以根据其权限看到不同级别的数据
+- **灵活的表达式**：使用 SQL `CASE WHEN` 表达式定义复杂的脱敏逻辑
+- **内置函数**：用于常见脱敏模式的预定义函数
+- **可选限制**：控制脱敏数据是否可用于某些操作


Suggested change

- **结果时脱敏**：数据在返回给客户端时进行脱敏，而不是以脱敏形式存储

- **支持用户/角色**：不同用户可以根据其权限看到不同级别的数据

- **灵活的表达式**：使用 SQL `CASE WHEN` 表达式定义复杂的脱敏逻辑

- **内置函数**：用于常见脱敏模式的预定义函数

- **可选限制**：控制脱敏数据是否可用于某些操作

- **结果阶段脱敏**：TiDB 在返回查询结果到客户端时应用脱敏逻辑，而不修改原始数据

- **基于用户或角色控制可见性**：不同用户或不同角色可以根据其权限看到不同级别的数据。

- **支持表达式脱敏**：可以使用 SQL `CASE WHEN` 表达式定义灵活的脱敏逻辑。

- **提供内置脱敏函数**：支持完整脱敏、部分脱敏、返回 `NULL`、日期替换等常见脱敏方式。

- **支持操作限制**：可以使用 `RESTRICT ON` 阻止某些语句将脱敏数据复制或写入其他表。

qiancai · 2026-05-11T09:33:08Z

+{{< copyable "sql" >}}
+


Suggested change

{{< copyable "sql" >}}

reason: not needed anymore because the copy button is added automitacally for all code blocks on the docs website.

Please remove all "{{< copyable "sql" >}}" from this doc.

qiancai · 2026-05-11T10:16:33Z

+-- 1. 将脱敏数据复制到另一个表
+INSERT INTO other_table SELECT value FROM sensitive_data;  -- 错误
+
+-- 2. 使用脱敏数据进行更新
+UPDATE some_table SET x = (SELECT value FROM sensitive_data);  -- 错误
+
+-- 3. 使用脱敏数据进行删除
+DELETE FROM some_table WHERE x IN (SELECT value FROM sensitive_data);  -- 错误


Suggested change

-- 1. 将脱敏数据复制到另一个表

INSERT INTO other_table SELECT value FROM sensitive_data; -- 错误

-- 2. 使用脱敏数据进行更新

UPDATE some_table SET x = (SELECT value FROM sensitive_data); -- 错误

-- 3. 使用脱敏数据进行删除

DELETE FROM some_table WHERE x IN (SELECT value FROM sensitive_data); -- 错误

-- 1. 将受保护列的数据复制到另一个表

INSERT INTO other_table SELECT value FROM sensitive_data; -- 错误

-- 2. 使用受保护列的数据更新另一个表

UPDATE some_table SET x = (SELECT value FROM sensitive_data); -- 错误

-- 3. 使用受保护列的数据作为删除条件

DELETE FROM some_table WHERE x IN (SELECT value FROM sensitive_data); -- 错误

qiancai · 2026-05-11T10:17:05Z

+  RESTRICT ON (INSERT_INTO_SELECT, UPDATE_SELECT, DELETE_SELECT)
+  ENABLE;
+
+-- 普通用户在尝试以下操作时会收到错误：


Suggested change

-- 普通用户在尝试以下操作时会收到错误：

-- 普通用户在尝试以下操作时，TiDB 会返回错误：

qiancai · 2026-05-11T10:20:25Z

+
+### 使用 current_user()
+
+你可以在脱敏表达式中使用 `current_user()` 来检查登录用户：


Suggested change

你可以在脱敏表达式中使用 `current_user()` 来检查登录用户：

你可以在脱敏表达式中使用 `CURRENT_USER()` 判断当前会话对应的用户账号。

建议统一写成 CURRENT_USER()，和其他文档一致

qiancai · 2026-05-11T10:24:52Z

+-- 将角色授予授权用户
+GRANT data_viewer TO 'analyst'@'%';
+
+-- 用户必须激活角色才能查看未脱敏的数据


Suggested change

-- 用户必须激活角色才能查看未脱敏的数据

-- 用户需要先激活角色，才能按照角色条件查看未脱敏数据：

qiancai · 2026-05-11T10:27:10Z

+注意：`current_role()` 和 `current_user()` 的数据格式是不一样的，前者类似 '\`data_viewer\`@\`%\`' 而后者类似于 'data_view@%'，区别是有无 \` 包裹。
+这个行为不是 bug，而是 MySQL 就是这样的行为。见 https://github.com/pingcap/tidb/issues/67227


Suggested change

注意：`current_role()` 和 `current_user()` 的数据格式是不一样的，前者类似 '\`data_viewer\`@\`%\`' 而后者类似于 'data_view@%'，区别是有无 \` 包裹。

这个行为不是 bug，而是 MySQL 就是这样的行为。见 https://github.com/pingcap/tidb/issues/67227

> **注意：**

>

> `CURRENT_USER()` 和 `CURRENT_ROLE()` 的返回格式不同。该行为并非 bug，与 MySQL 一致，详见 [#67227](https://github.com/pingcap/tidb/issues/67227)。

>

> - `CURRENT_USER()` 通常返回 `'user_name@host_name'`，例如 `'analyst@%'`。

> - `CURRENT_ROLE()` 返回当前激活的角色，格式通常包含反引号，例如 ``'`data_viewer`@`%`'``。如果没有激活任何角色，返回 `'NONE'`。

>

> 如果一个会话可能同时激活多个角色，建议先确认 `CURRENT_ROLE()` 的实际返回值，再编写精确的匹配条件。

*: add column-level masking policy feature document

f088931

ti-chi-bot Bot added missing-translation-status This PR does not have translation status info. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Mar 23, 2026

tiancaiamao mentioned this pull request Mar 23, 2026

*: add document for column-level masking policy feature pingcap/docs#22613

Open

14 tasks

add file

7d9f34b

ti-chi-bot Bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Mar 23, 2026

hfxsd added translation/doing This PR’s assignee is translating this PR. and removed missing-translation-status This PR does not have translation status info. labels Mar 24, 2026

qiancai added the v9.0-beta.3 This PR/issue applies to TiDB v9.0-beta.3. label Mar 24, 2026

Frank945946 reviewed Apr 1, 2026

View reviewed changes

qiancai self-assigned this Apr 17, 2026

tiancaiamao requested a review from bb7133 May 9, 2026 02:56

tiancaiamao added 2 commits May 9, 2026 15:42

Merge branch 'master' into column-masking-policy

765ead0

address comment

c86aa36

address comment

004d0fa

qiancai reviewed May 11, 2026

View reviewed changes

	-- 即使用户看到脱敏数据，过滤仍然有效
	-- 即使用户在 Where 条件输入未脱敏数据，过滤仍然有效


		# 列级脱敏策略

		列级脱敏策略是一项安全功能，允许你在列级别应用脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会根据定义的规则自动对返回给用户的数据进行脱敏，而原始数据在存储中保持不变。

	列级脱敏策略是一项安全功能，允许你在列级别应用脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会根据定义的规则自动对返回给用户的数据进行脱敏，而原始数据在存储中保持不变。
	列级脱敏策略是 TiDB 中的一项安全功能，允许你为表中的指定列创建脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会按照定义的规则自动对返回给用户的查询结果数据进行脱敏，而原始数据在存储中保持不变。


		列级脱敏策略是一项安全功能，允许你在列级别应用脱敏规则来保护敏感数据。当对列应用脱敏策略时，TiDB 会根据定义的规则自动对返回给用户的数据进行脱敏，而原始数据在存储中保持不变。

		此功能对于满足 PCI-DSS（支付卡行业数据安全标准）等合规要求以及数据隐私法规（如 GDPR - 通用数据保护条例、CCPA - 加州消费者隐私法案）特别有用，这些法规要求严格控制谁可以查看信用卡号、个人标识符和其他机密信息等敏感信息。

	此功能对于满足 PCI-DSS（支付卡行业数据安全标准）等合规要求以及数据隐私法规（如 GDPR - 通用数据保护条例、CCPA - 加州消费者隐私法案）特别有用，这些法规要求严格控制谁可以查看信用卡号、个人标识符和其他机密信息等敏感信息。
	列级脱敏策略适用于需要限制敏感数据可见性的场景，例如控制信用卡号、身份证号、电话号码、电子邮件地址、出生日期等敏感信息的访问范围。


		## 概述

		脱敏策略绑定到表列，并在查询结果时进行评估。策略使用 SQL 表达式根据当前用户身份或角色来确定如何对数据进行脱敏。

	脱敏策略绑定到表列，并在查询结果时进行评估。策略使用 SQL 表达式根据当前用户身份或角色来确定如何对数据进行脱敏。
	脱敏策略绑定到表中的单个列。每个列最多只能绑定一个脱敏策略。策略表达式通常使用 SQL `CASE WHEN` 表达式，并结合 `CURRENT_USER()` 或 `CURRENT_ROLE()` 判断当前会话是否可以查看原始值。

	-- 普通用户在尝试以下操作时会收到错误：
	-- 普通用户在尝试以下操作时，TiDB 会返回错误：


		### 使用 current_user()

		你可以在脱敏表达式中使用 `current_user()` 来检查登录用户：

	你可以在脱敏表达式中使用 `current_user()` 来检查登录用户：
	你可以在脱敏表达式中使用 `CURRENT_USER()` 判断当前会话对应的用户账号。

	-- 用户必须激活角色才能查看未脱敏的数据
	-- 用户需要先激活角色，才能按照角色条件查看未脱敏数据：

		注意：`current_role()` 和 `current_user()` 的数据格式是不一样的，前者类似 '\`data_viewer\`@\`%\`' 而后者类似于 'data_view@%'，区别是有无 \` 包裹。
		这个行为不是 bug，而是 MySQL 就是这样的行为。见 https://github.com/pingcap/tidb/issues/67227

-注意：`current_role()` 和 `current_user()` 的数据格式是不一样的，前者类似 '\`data_viewer\`@\`%\`' 而后者类似于 'data_view@%'，区别是有无 \` 包裹。
-这个行为不是 bug，而是 MySQL 就是这样的行为。见 https://github.com/pingcap/tidb/issues/67227
+> **注意：**
+>
+> `CURRENT_USER()` 和 `CURRENT_ROLE()` 的返回格式不同。该行为并非 bug，与 MySQL 一致，详见 [#67227](https://github.com/pingcap/tidb/issues/67227)。
+>
+> - `CURRENT_USER()` 通常返回 `'user_name@host_name'`，例如 `'analyst@%'`。
+> - `CURRENT_ROLE()` 返回当前激活的角色，格式通常包含反引号，例如 ``'`data_viewer`@`%`'``。如果没有激活任何角色，返回 `'NONE'`。
+>
+> 如果一个会话可能同时激活多个角色，建议先确认 `CURRENT_ROLE()` 的实际返回值，再编写精确的匹配条件。

Conversation

tiancaiamao commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

First-time contributors' checklist

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

Do your changes match any of the following descriptions?

Uh oh!

qiancai commented Mar 24, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bb7133 commented May 9, 2026

Uh oh!

ti-chi-bot Bot commented May 9, 2026

Uh oh!

ti-chi-bot Bot commented May 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tiancaiamao commented Mar 23, 2026 •

edited

Loading