From 65eb0e49d365c7a8088e40a7e8b45f7686693a52 Mon Sep 17 00:00:00 2001 From: taichong Date: Wed, 10 Dec 2025 11:30:53 +0800 Subject: [PATCH 1/2] chore: add doc about system flush privilege --- .../00-ddl/02-user/10-grant.md | 2 ++ .../flush-privileges.md | 35 +++++++++++++++++++ .../50-administration-cmds/index.md | 8 ++++- .../00-ddl/02-user/10-grant.md | 2 ++ .../flush-privileges.md | 34 ++++++++++++++++++ .../50-administration-cmds/index.md | 8 ++++- 6 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 docs/cn/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md create mode 100644 docs/en/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md index 774c63de46..7cdf31e3c7 100644 --- a/docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md +++ b/docs/cn/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md @@ -18,6 +18,8 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; - [REVOKE](11-revoke.md) - [SHOW GRANTS](22-show-grants.md) +> 使用 `GRANT` 或 `REVOKE` 变更角色与权限后，执行 [SYSTEM FLUSH PRIVILEGES](../../50-administration-cmds/flush-privileges.md) 可立即让所有查询节点刷新缓存。 + ## Syntax ### Granting Privileges diff --git a/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md b/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md new file mode 100644 index 0000000000..996f549df6 --- /dev/null +++ b/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md @@ -0,0 +1,35 @@ +--- +title: SYSTEM FLUSH PRIVILEGES +--- + +`SYSTEM FLUSH PRIVILEGES` 会向每个查询节点广播刷新请求，使其立即从 Meta 服务重新加载角色与权限缓存。执行 `GRANT` 或 `REVOKE` 之后如果希望变更立刻在整个集群生效，可以使用该命令，而不用等待默认 15 秒的缓存刷新周期。 + +参见： + +- [GRANT](../00-ddl/02-user/10-grant.md) +- [REVOKE](../00-ddl/02-user/11-revoke.md) + +## 语法 + +```sql +SYSTEM FLUSH PRIVILEGES +``` + +## 使用说明 + +- 需要具备能够执行系统管理命令的角色，例如 `ACCOUNT ADMIN`。 +- 该命令仅刷新节点本地缓存，不会修改角色或授权内容本身。 +- 已经在运行的语句会继续沿用启动时解析到的权限，若要使用最新权限，请在刷新之后重新执行语句。 + +## 示例 + +下面的示例为角色授予数据库访问权限，并立即刷新缓存，使所有查询节点都能看到新的权限： + +```sql +GRANT SELECT ON DATABASE marketing TO ROLE analyst; + +SYSTEM FLUSH PRIVILEGES; +``` + + +刷新完成后，继承 `analyst` 角色的新查询无需等待缓存失效即可获得更新后的权限。 diff --git a/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/index.md b/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/index.md index c114a85e9c..8ac7d3cafc 100644 --- a/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/index.md +++ b/docs/cn/sql-reference/10-sql-commands/50-administration-cmds/index.md @@ -13,6 +13,12 @@ title: 管理命令 | **[KILL](01-kill.md)** | 终止正在运行的查询或连接 | | **[RUST BACKTRACE](rust-backtrace.md)** | 调试 Rust 堆栈跟踪 | +## 访问控制 + +| 命令 | 说明 | +|---------|-------------| +| **[FLUSH PRIVILEGES](flush-privileges.md)** | 让每个查询节点立即重新加载角色与权限缓存 | + ## 配置管理 | 命令 | 说明 | @@ -43,4 +49,4 @@ title: 管理命令 | 命令 | 说明 | |---------|-------------| -| **[EXECUTE IMMEDIATE](execute-immediate.md)** | 执行动态构造的 SQL 语句 | \ No newline at end of file +| **[EXECUTE IMMEDIATE](execute-immediate.md)** | 执行动态构造的 SQL 语句 | diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md b/docs/en/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md index 387e37ac3f..6c61d25e06 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/02-user/10-grant.md @@ -17,6 +17,8 @@ See also: - [REVOKE](11-revoke.md) - [SHOW GRANTS](22-show-grants.md) +> After changing privileges or roles with `GRANT`, run [SYSTEM FLUSH PRIVILEGES](../../50-administration-cmds/flush-privileges.md) to broadcast the updates to every query node immediately. + ## Syntax ### Granting Privileges diff --git a/docs/en/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md b/docs/en/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md new file mode 100644 index 0000000000..eae25dbf5f --- /dev/null +++ b/docs/en/sql-reference/10-sql-commands/50-administration-cmds/flush-privileges.md @@ -0,0 +1,34 @@ +--- +title: SYSTEM FLUSH PRIVILEGES +--- + +`SYSTEM FLUSH PRIVILEGES` broadcasts a refresh request to every query node so each node immediately reloads privilege and role metadata from the Meta service. Run the command after `GRANT` or `REVOKE` statements when you need the changes to take effect across the cluster without waiting for the default 15-second role-cache interval. + +See also: + +- [GRANT](../00-ddl/02-user/10-grant.md) +- [REVOKE](../00-ddl/02-user/11-revoke.md) + +## Syntax + +```sql +SYSTEM FLUSH PRIVILEGES +``` + +## Usage Notes + +- Requires a role that is allowed to execute system administration commands, such as `ACCOUNT ADMIN`. +- Refreshes cached privilege metadata only; it does not alter roles or grants by itself. +- Statements that are already running keep using the privileges that were resolved when they started. Re-run the statement after the flush to pick up the changes. + +## Example + +The following sequence grants a role access to a database and immediately flushes the caches so the new privilege is visible from every query node: + +```sql +GRANT SELECT ON DATABASE marketing TO ROLE analyst; + +SYSTEM FLUSH PRIVILEGES; +``` + +After the flush completes, any new query that runs under the `analyst` role receives the updated privilege set without waiting for the cache to expire. diff --git a/docs/en/sql-reference/10-sql-commands/50-administration-cmds/index.md b/docs/en/sql-reference/10-sql-commands/50-administration-cmds/index.md index 49db268804..d108f37384 100644 --- a/docs/en/sql-reference/10-sql-commands/50-administration-cmds/index.md +++ b/docs/en/sql-reference/10-sql-commands/50-administration-cmds/index.md @@ -13,6 +13,12 @@ This page provides reference information for the system administration commands | **[KILL](01-kill.md)** | Terminate running queries or connections | | **[RUST BACKTRACE](rust-backtrace.md)** | Debug Rust stack traces | +## Access Control + +| Command | Description | +|---------|-------------| +| **[FLUSH PRIVILEGES](flush-privileges.md)** | Force every query node to reload role and privilege metadata | + ## Configuration Management | Command | Description | @@ -43,4 +49,4 @@ This page provides reference information for the system administration commands | Command | Description | |---------|-------------| -| **[EXECUTE IMMEDIATE](execute-immediate.md)** | Execute dynamically constructed SQL statements | \ No newline at end of file +| **[EXECUTE IMMEDIATE](execute-immediate.md)** | Execute dynamically constructed SQL statements | From f2201fb51474bbedc1284f05cc6691ca88e1f283 Mon Sep 17 00:00:00 2001 From: BohuTANG Date: Wed, 10 Dec 2025 20:57:38 +0800 Subject: [PATCH 2/2] docs: refine chinese translation for roles and system tables --- .../56-security/access-control/02-roles.md | 34 +++++++++---------- .../31-system-tables/system-query-log.md | 10 +++--- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/cn/guides/56-security/access-control/02-roles.md b/docs/cn/guides/56-security/access-control/02-roles.md index fe9a206a82..13c27bf697 100644 --- a/docs/cn/guides/56-security/access-control/02-roles.md +++ b/docs/cn/guides/56-security/access-control/02-roles.md @@ -2,7 +2,7 @@ title: 角色 --- -Databend 中的角色在简化权限管理方面起着关键作用。当多个用户需要相同的权限集时，单独授予权限可能很麻烦。角色提供了一种解决方案，允许将一组权限分配给一个角色，然后可以轻松地将该角色分配给多个用户。 +角色在 Databend 的权限管理中起着关键作用。当多个用户需要相同的权限时，逐一授权会非常繁琐。通过角色，我们可以将一组权限打包，然后轻松地将其分配给多个用户。 :::note 目前，Databend 默认不对用户定义函数 (UDF) 和 Stage 强制执行基于角色的访问控制 (RBAC) 检查。但是，如果您需要对这些对象执行 RBAC，您可以选择手动设置 `SET GLOBAL enable_experimental_rbac_check=1` 来全局启用它。 @@ -14,9 +14,9 @@ Databend 中的角色在简化权限管理方面起着关键作用。当多个 ## 继承角色 & 建立层级结构 -角色授予使一个角色能够继承另一个角色的权限和职责。这有助于创建灵活的层级结构，类似于组织结构，其中存在两个 [内置角色](#built-in-roles)：最高的是 `account-admin`，最低的是 `public`。 +角色授予允许一个角色继承另一个角色的权限。这有助于构建灵活的层级结构（类似于组织架构）。Databend 主要包含两个[内置角色](#built-in-roles)：最高层级的 `account-admin` 和最低层级的 `public`。 -考虑创建三个角色的场景：_manager_、_engineer_ 和 _intern_。在此示例中，_intern_ 角色被授予给 _engineer_ 角色。因此，_engineer_ 不仅拥有自己的权限集，还继承了与 _intern_ 角色相关的权限。进一步扩展此层级结构，如果将 _engineer_ 角色授予给 _manager_，则 _manager_ 现在获得 _engineer_ 和 _intern_ 角色的固有权限。 +假设我们创建了三个角色：_manager_、_engineer_ 和 _intern_。如果我们把 _intern_ 角色授予 _engineer_，那么 _engineer_ 不仅拥有自己的权限，还会继承 _intern_ 的权限。以此类推，如果把 _engineer_ 角色授予 _manager_，那么 _manager_ 将同时获得 _engineer_ 和 _intern_ 的所有权限。 ![Alt text](/img/guides/access-control-4.png) @@ -26,14 +26,14 @@ Databend 附带以下内置角色： | 内置角色 | 描述 | | ------------- | -------------------------------------------------------------------------- | -| account-admin | 拥有所有权限，充当所有其他角色的父角色，并能够无缝切换到租户中的任何角色。 | -| public | 不继承任何权限，将所有角色视为其父角色，并允许任何角色切换到 public 角色。 | +| account-admin | 拥有所有权限，是所有其他角色的父角色，可以无缝切换为租户内的任何角色。 | +| public | 不继承任何权限，所有其他角色都是它的父角色。任何角色都可以切换为 public 角色。 | -要在 Databend Cloud 中将 `account-admin` 角色分配给用户，请在邀请用户时选择该角色。您也可以在用户加入后将该角色分配给用户。如果您使用的是 Databend Community Edition 或 Enterprise Edition，请首先在部署期间配置 `account-admin` 用户，然后根据需要将该角色分配给其他用户。有关配置管理员用户的更多信息，请参阅 [配置管理员用户](../../10-deploy/04-references/01-admin-users.md)。 +在 Databend Cloud 中，您可以在邀请用户时直接分配 `account-admin` 角色，或者在用户加入后进行分配。如果您使用的是 Databend 社区版或企业版，请在部署时先配置好 `account-admin` 用户，然后再按需分配给其他用户。关于管理员用户的配置详情，请参阅[配置管理员用户](../../10-deploy/04-references/01-admin-users.md)。 ## 设置默认角色 -当用户被授予多个角色时，您可以使用 [CREATE USER](/sql/sql-commands/ddl/user/user-create-user) 或 [ALTER USER](/sql/sql-commands/ddl/user/user-alter-user) 命令为该用户设置默认角色。默认角色确定在会话开始时自动分配给用户的角色： +当用户拥有多个角色时，可以使用 [CREATE USER](/sql/sql-commands/ddl/user/user-create-user) 或 [ALTER USER](/sql/sql-commands/ddl/user/user-alter-user) 命令设置默认角色。默认角色是用户登录会话时自动生效的角色： ```sql title='Example:' -- 显示系统中现有的角色 @@ -57,33 +57,33 @@ GRANT ROLE account_admin TO eric; ALTER USER eric WITH DEFAULT_ROLE = 'account_admin'; ``` -- 用户可以使用 [SET ROLE](/sql/sql-commands/ddl/user/user-set-role) 命令灵活地在会话中切换到其他角色。 -- 用户可以使用 [SHOW ROLES](/sql/sql-commands/ddl/user/user-show-roles) 命令检查其当前角色并查看授予给他们的所有角色。 -- 如果您没有为用户显式设置默认角色，Databend 将默认使用内置角色 `public` 作为默认角色。 +- 用户可以在会话中使用 [SET ROLE](/sql/sql-commands/ddl/user/user-set-role) 命令灵活切换角色。 +- 用户可以使用 [SHOW ROLES](/sql/sql-commands/ddl/user/user-show-roles) 命令查看当前的活跃角色以及所有被授予的角色。 +- 如果未显式设置默认角色，Databend 将默认使用内置角色 `public`。 ## 激活角色 & 辅助角色 -可以向用户授予 Databend 中的多个角色。这些角色分为激活角色和辅助角色： +在 Databend 中，用户可以被授予多个角色。这些角色分为激活角色（Active Role）和辅助角色（Secondary Roles）： -- 激活角色是用户当前会话的激活主角色，可以使用 [SET ROLE](/sql/sql-commands/ddl/user/user-set-role) 命令进行设置。 +- **激活角色**：用户当前会话中正在使用的主角色，可通过 [SET ROLE](/sql/sql-commands/ddl/user/user-set-role) 命令进行切换。 -- 辅助角色是提供额外权限的其他角色，默认情况下处于激活状态。用户可以使用 [SET SECONDARY ROLES](/sql/sql-commands/ddl/user/user-set-2nd-roles) 命令激活或停用辅助角色，以临时调整其权限范围。 +- **辅助角色**：提供额外权限的角色，默认处于激活状态。用户可以使用 [SET SECONDARY ROLES](/sql/sql-commands/ddl/user/user-set-2nd-roles) 命令来启用或禁用这些角色，从而临时调整权限范围。 ## 账单角色 -除了标准的内置角色之外，您还可以在 Databend Cloud 中创建一个名为 `billing` 的自定义角色，专门满足财务人员的需求。角色 `billing` 仅提供对与账单相关的信息的访问权限，确保财务人员可以查看必要的财务数据，而无需访问其他与业务相关的页面。 +除了标准的内置角色，Databend Cloud 还支持创建名为 `billing` 的自定义角色，专为财务人员设计。`billing` 角色仅拥有账单信息的访问权限，确保财务人员在查看财务数据时，无法访问其他业务页面。 -要设置和使用角色 `billing`，您可以使用以下命令创建它： +要设置和使用 `billing` 角色，可以使用以下命令创建： ```sql CREATE ROLE billing; ``` -角色名称不区分大小写，因此 `billing` 和 `Billing` 被认为是相同的。有关设置和分配角色 `billing` 的详细步骤，请参阅 [授予财务人员访问权限](/guides/cloud/manage/costs#granting-access-to-finance-personnel)。 +角色名称不区分大小写，`billing` 和 `Billing` 视为相同。关于该角色的设置和分配步骤，请参阅[授予财务人员访问权限](/guides/cloud/manage/costs#granting-access-to-finance-personnel)。 ## 使用示例 -此示例展示了基于角色的权限管理。最初，创建一个“writer”角色并授予权限。随后，这些权限被分配给用户“eric”，他继承了这些权限。最后，从角色中撤销权限，展示了它们对用户权限的影响。 +此示例展示了基于角色的权限管理。首先创建一个 `writer` 角色并授予权限，然后将这些权限授予用户 `eric`，使其继承这些权限。最后，撤销角色的权限，演示其对用户权限的影响。 ```sql title='Example:' -- 创建一个名为 'writer' 的新角色 diff --git a/docs/cn/sql-reference/00-sql-reference/31-system-tables/system-query-log.md b/docs/cn/sql-reference/00-sql-reference/31-system-tables/system-query-log.md index 35b0cd8fc9..2811e439ac 100644 --- a/docs/cn/sql-reference/00-sql-reference/31-system-tables/system-query-log.md +++ b/docs/cn/sql-reference/00-sql-reference/31-system-tables/system-query-log.md @@ -6,17 +6,17 @@ import FunctionDescription from '@site/src/components/FunctionDescription'; -一个只读的内存表，用于存储所有查询日志。有关查询日志中可用字段的具体信息，请参阅[示例](#examples)部分。 +这是一个只读的内存表，用于存储所有的查询日志。关于查询日志中可用字段的具体信息，请参阅[示例](#examples)部分。 ## 设置会话标签 -可以选择为会话（Session）分配一个标签，便于根据分配的会话标签在日志表中筛选日志。例如，以下命令为当前会话分配标签`eric`： +您可以为会话（Session）设置标签，以便在日志表中通过标签筛选日志。例如，使用以下命令为当前会话分配标签 `eric`： ```sql set session query_tag='eric'; ``` -随后，运行查询（Query）并使用分配的标签从日志表中检索日志： +然后，运行查询（Query）并使用该标签在日志表中检索对应的日志记录： ```sql show users; @@ -24,7 +24,7 @@ show users; select query_tag, query_text from system.query_log where query_tag='eric' limit 1; ``` -返回结果中可找到该查询的记录，标签为'eric'： +结果将显示带有 `eric` 标签的查询记录： ```sql -[ RECORD 1 ]----------------------------------- @@ -34,7 +34,7 @@ select query_tag, query_text from system.query_log where query_tag='eric' limit ## 示例 -`system.query_log`表存储已执行查询的详细日志。以下是日志条目的示例： +`system.query_log` 表存储了已执行查询的详细日志。以下是一个日志条目的示例： ```sql SELECT * FROM system.query_log;