Skip to content

docs: update masking policy privileges #2973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 19, 2025
Merged

docs: update masking policy privileges #2973

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions docs/cn/guides/56-security/access-control/01-privileges.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,15 +108,17 @@ Databend 提供多种权限，实现对数据库对象的细粒度控制，可
### 所有权限

| 权限 | 对象类型 | 描述 |
|:------------------|:------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|
| ALL | 所有 | 授予指定对象类型的全部权限。 |
| ALTER | Global, Database, Table, View | 修改数据库、表、用户或 UDF。 |
| CREATE | Global, Table | 创建表或 UDF。 |
| CREATE DATABASE | Global | 创建数据库或 UDF。 |
| CREATE WAREHOUSE | Global | 创建 Warehouse。 |
| CREATE CONNECTION | Global | 创建 Connection。 |
| CREATE SEQUENCE | Global | 创建 Sequence。 |
| CREATE PROCEDURE | PROCEDURE | 创建 Procedure。 |
|:------------------|:------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------|
| ALL | 所有 | 授予指定对象类型的全部权限。 |
| APPLY MASKING POLICY | Global, Masking Policy | 附加/解除、描述或删除脱敏策略。授予 `*.*` 时，可在整个账号范围管理所有脱敏策略。 |
| ALTER | Global, Database, Table, View | 修改数据库、表、用户或 UDF。 |
| CREATE | Global, Table | 创建表或 UDF。 |
| CREATE DATABASE | Global | 创建数据库或 UDF。 |
| CREATE WAREHOUSE | Global | 创建 Warehouse。 |
| CREATE CONNECTION | Global | 创建 Connection。 |
| CREATE SEQUENCE | Global | 创建 Sequence。 |
| CREATE PROCEDURE | PROCEDURE | 创建 Procedure。 |
| CREATE MASKING POLICY | Global | 创建脱敏策略。 |
| DELETE | Table | 删除或截断表中的行。 |
| DROP | Global, Database, Table, View | 删除数据库、表、View 或 UDF；恢复已删除的表。 |
| INSERT | Table | 向表插入行。 |
Expand Down Expand Up @@ -256,4 +258,13 @@ Databend 提供多种权限，实现对数据库对象的细粒度控制，可
|:-----------------|:--------------------------------------------------------------------------------------|
| Access Procedure | 可访问 Procedure（如 Drop、Call、Desc）。 |
| ALL | 授予指定对象类型的 Access Procedure 权限。 |
| OWNERSHIP | 授予对 Procedure 的完全控制权；在特定对象上一次只能有一个角色持有此权限。 |
| OWNERSHIP | 授予对 Procedure 的完全控制权；在特定对象上一次只能有一个角色持有此权限。 |

### 脱敏策略权限

除 `CREATE MASKING POLICY` 与 `APPLY MASKING POLICY` 全局权限外，还可以针对单个脱敏策略授予权限：

| 权限 | 描述 |
|:------|:--------------------------------------------------------------------------------------------------------|
| APPLY | 将脱敏策略绑定/解绑到列，同时允许执行 DESC/DROP 操作。 |
| OWNERSHIP | 授予对脱敏策略的完全控制权。Databend 会在策略创建时自动将 OWNERSHIP 授予当前角色，并在策略被删除时自动回收。 |
6 changes: 6 additions & 0 deletions docs/cn/guides/56-security/masking-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,12 @@ SELECT * FROM user_info;
- 确保用户已分配适当角色
- 角色管理请参考 [User & Role](/sql/sql-commands/ddl/user/)

### 所需权限

- 需要将 `CREATE MASKING POLICY`（通常授予 `*.*`）赋予负责创建或替换脱敏策略的角色。Databend 会在策略创建完成后自动将该策略的 OWNERSHIP 授予当前角色。
- 需要将全局 `APPLY MASKING POLICY` 权限，或使用 `GRANT APPLY ON MASKING POLICY <policy_name>` 为角色授予特定策略的控制权，才能在 `ALTER TABLE` 中设置/解除策略；拥有该策略的 OWNERSHIP 也可执行这些操作。
- 通过 `SHOW GRANTS ON MASKING POLICY <policy_name>` 可以审计哪些角色拥有 APPLY 或 OWNERSHIP 权限。

## 策略管理

有关创建、修改和管理动态脱敏策略（Masking Policy）的详细命令，请查阅：
Expand Down
3 changes: 2 additions & 1 deletion docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/90-alter-table.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ slug: /sql-commands/ddl/table/alter-table

import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="引入或更新于：v1.2.821"/>
<FunctionDescription description="引入或更新于：v1.2.845"/>

import EEFeature from '@site/src/components/EEFeature';

Expand Down Expand Up @@ -75,6 +75,7 @@ DROP [ COLUMN ] <column_name>
- 当声明了 `USING (...)` 时，必须至少提供被脱敏的列以及策略所需的其他列，并确保 `USING` 中的第一个标识符与正在修改的列一致。
- 只有常规表支持绑定脱敏策略；视图、流表以及临时表均无法执行 `SET MASKING POLICY`。
- 单个列最多只能附加一个安全策略（无论是列脱敏还是行级策略）。在重新绑定之前，请先移除原有策略。
- 设置或取消设置脱敏策略需要拥有全局 `APPLY MASKING POLICY` 权限，或针对目标策略具有 APPLY/OWNERSHIP 权限，否则 `ALTER TABLE` 会被拒绝。
:::

:::caution
Expand Down
37 changes: 36 additions & 1 deletion docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 9

import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="Introduced or updated: v1.2.275"/>
<FunctionDescription description="Introduced or updated: v1.2.845"/>

为特定的数据库对象授予权限、角色和所有权。包括：

Expand Down Expand Up @@ -52,6 +52,9 @@ schemaObjectPrivileges ::=

-- For UDF
{ USAGE }

-- For MASKING POLICY
{ CREATE MASKING POLICY | APPLY MASKING POLICY }
```

```sql
Expand All @@ -61,8 +64,24 @@ privileges_level ::=
| db_name.tbl_name
| STAGE <stage_name>
| UDF <udf_name>
| MASKING POLICY <policy_name>
```

### 授予脱敏策略权限

要针对某个脱敏策略授予权限，可使用以下语句：

```sql
GRANT APPLY ON MASKING POLICY <policy_name> TO [ ROLE ] <grantee>
GRANT ALL [ PRIVILEGES ] ON MASKING POLICY <policy_name> TO [ ROLE ] <grantee>
GRANT OWNERSHIP ON MASKING POLICY <policy_name> TO ROLE '<role_name>'
```

- `CREATE MASKING POLICY` 允许创建策略。
- `APPLY MASKING POLICY`（全局）允许在任意表上设置/解除、描述或删除任何脱敏策略。
- `GRANT APPLY ON MASKING POLICY ...` 可针对单个策略授权，避免授予全局访问。
- OWNERSHIP 赋予对策略的完全控制权。创建脱敏策略后，Databend 会自动将 OWNERSHIP 授予当前角色，并在策略删除时回收。

### Granting Role

要了解什么是角色以及它是如何工作的，请参见 [Roles](/guides/security/access-control/roles)。
Expand Down Expand Up @@ -251,3 +270,19 @@ GRANT OWNERSHIP ON STAGE ingestion_stage TO ROLE 'data_owner';
-- Grant ownership of the user-defined function 'calculate_profit' to the role 'data_owner'
GRANT OWNERSHIP ON UDF calculate_profit TO ROLE 'data_owner';
```

### Example 5: Granting Masking Policy Privileges

```sql
-- 授权角色创建脱敏策略
GRANT CREATE MASKING POLICY ON *.* TO ROLE security_admin;

-- 在 security_admin 角色下创建策略
CREATE MASKING POLICY email_mask AS (val STRING) RETURNS STRING -> '***';

-- 仅允许 pii_readers 角色在表列上应用该策略
GRANT APPLY ON MASKING POLICY email_mask TO ROLE pii_readers;

-- 查看策略的授权情况
SHOW GRANTS ON MASKING POLICY email_mask;
```
28 changes: 26 additions & 2 deletions docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/11-revoke.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_position: 11
---
import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="Introduced or updated: v1.2.275"/>
<FunctionDescription description="Introduced or updated: v1.2.845"/>

撤销特定数据库对象的权限、角色和所有权。 这包括：

Expand Down Expand Up @@ -48,6 +48,9 @@ schemaObjectPrivileges ::=

-- For UDF
{ USAGE }

-- For MASKING POLICY
{ CREATE MASKING POLICY | APPLY MASKING POLICY }
```

```sql
Expand All @@ -57,8 +60,19 @@ privileges_level ::=
| db_name.tbl_name
| STAGE <stage_name>
| UDF <udf_name>
| MASKING POLICY <policy_name>
```

### 撤销脱敏策略权限

```sql
REVOKE APPLY ON MASKING POLICY <policy_name> FROM [ ROLE ] <grantee>
REVOKE ALL [ PRIVILEGES ] ON MASKING POLICY <policy_name> FROM [ ROLE ] <grantee>
REVOKE OWNERSHIP ON MASKING POLICY <policy_name> FROM ROLE '<role_name>'
```

以上语句用于撤销针对特定脱敏策略的 APPLY 或 OWNERSHIP 权限。若需撤销全局 `CREATE MASKING POLICY` 或 `APPLY MASKING POLICY`，可结合 `ON *.*` 使用标准语法。

### 撤销角色

```sql
Expand Down Expand Up @@ -159,4 +173,14 @@ SHOW GRANTS FOR user1;
| GRANT ALL ON 'default'.* TO 'user1'@'%' |
| GRANT ALL ON *.* TO 'user1'@'%' |
+-----------------------------------------+
```
```

### 示例 4：撤销脱敏策略权限

```sql
-- 撤销针对单个脱敏策略的 APPLY 权限
REVOKE APPLY ON MASKING POLICY email_mask FROM ROLE pii_readers;

-- 撤销角色在整个账号范围创建脱敏策略的权限
REVOKE CREATE MASKING POLICY ON *.* FROM ROLE security_admin;
```
9 changes: 6 additions & 3 deletions docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/22-show-grants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_position: 10
---
import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="Introduced or updated: v1.2.487"/>
<FunctionDescription description="Introduced or updated: v1.2.845"/>

列出明确授予用户、角色或特定对象的权限。

Expand All @@ -24,7 +24,7 @@ SHOW GRANTS FOR <user_name> [ LIKE '<pattern>' | WHERE <expr> | LIMIT <limit> ]
SHOW GRANTS FOR ROLE <role_name> [ LIKE '<pattern>' | WHERE <expr> | LIMIT <limit> ]

-- 列出授予对象的权限
SHOW GRANTS ON { STAGE | TABLE | DATABASE | UDF } <object_name> [ LIKE '<pattern>' | WHERE <expr> | LIMIT <limit> ]
SHOW GRANTS ON { STAGE | TABLE | DATABASE | UDF | MASKING POLICY } <object_name> [ LIKE '<pattern>' | WHERE <expr> | LIMIT <limit> ]

-- 列出所有已直接授予 role_name 的用户和角色。
SHOW GRANTS OF ROLE <role_name>
Expand Down Expand Up @@ -89,4 +89,7 @@ SHOW GRANTS OF ROLE analyst
│ analyst │ USER │ user1 │
╰─────────────────────────────────────╯

```

-- 查看脱敏策略的授权
SHOW GRANTS ON MASKING POLICY email_mask;
```
10 changes: 9 additions & 1 deletion docs/cn/sql-reference/10-sql-commands/00-ddl/12-mask-policy/create-mask-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 1

import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="引入或更新于: v1.2.341"/>
<FunctionDescription description="引入或更新于: v1.2.845"/>

import EEFeature from '@site/src/components/EEFeature';

Expand Down Expand Up @@ -36,6 +36,14 @@ CREATE [ OR REPLACE ] MASKING POLICY [ IF NOT EXISTS ] <policy_name> AS
确保 *arg_type_to_mask* 与将应用脱敏策略的列的数据类型匹配。当策略包含多个参数时，必须在 `ALTER TABLE ... SET MASKING POLICY` 的 `USING` 子句中按相同顺序列出对应列。
:::

## 访问控制要求

| 权限 | 描述 |
|:-----|:-----|
| CREATE MASKING POLICY | 创建或替换脱敏策略时所需的权限（通常授予 `*.*`）。 |

策略创建成功后，Databend 会自动将该策略的 OWNERSHIP 授予当前角色，方便与其他角色协同管理该策略。

## 示例

此示例演示了如何结合 `USING` 子句引用额外列，根据用户角色或其他列的值选择性地显示或脱敏敏感数据。
Expand Down
12 changes: 10 additions & 2 deletions docs/cn/sql-reference/10-sql-commands/00-ddl/12-mask-policy/desc-mask-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 2

import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="Introduced or updated: v1.2.45"/>
<FunctionDescription description="引入或更新于: v1.2.845"/>

import EEFeature from '@site/src/components/EEFeature';

Expand All @@ -19,6 +19,14 @@ import EEFeature from '@site/src/components/EEFeature';
DESC MASKING POLICY <policy_name>
```

## 访问控制要求

| 权限 | 描述 |
|:-----|:-----|
| APPLY MASKING POLICY | 描述脱敏策略时需要具备的权限；拥有该策略的 OWNERSHIP 亦可满足要求。 |

只要具备全局 `APPLY MASKING POLICY` 权限，或对指定策略拥有 APPLY/OWNERSHIP，即可查看策略定义。

## 示例

```sql
Expand All @@ -44,4 +52,4 @@ Signature |(val STRING)
Return Type|STRING |
Body |CASE WHEN current_role() IN('MANAGERS') THEN VAL ELSE '*********' END|
Comment |hide_email |
```
```
12 changes: 10 additions & 2 deletions docs/cn/sql-reference/10-sql-commands/00-ddl/12-mask-policy/drop-mask-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_position: 3

import FunctionDescription from '@site/src/components/FunctionDescription';

<FunctionDescription description="Introduced or updated: v1.2.45"/>
<FunctionDescription description="引入或更新于: v1.2.845"/>

import EEFeature from '@site/src/components/EEFeature';

Expand All @@ -19,6 +19,14 @@ import EEFeature from '@site/src/components/EEFeature';
DROP MASKING POLICY [ IF EXISTS ] <policy_name>
```

## 访问控制要求

| 权限 | 描述 |
|:-----|:-----|
| APPLY MASKING POLICY | 删除脱敏策略时需要具备的权限；如果拥有该策略的 OWNERSHIP 也可以删除。 |

需要全局 `APPLY MASKING POLICY` 权限，或对目标策略拥有 APPLY/OWNERSHIP。策略删除后，Databend 会自动回收之前授予的 OWNERSHIP。

## 示例

```sql
Expand All @@ -35,4 +43,4 @@ AS
COMMENT = 'hide_email';

DROP MASKING POLICY email_mask;
```
```
Loading
Loading