> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> USER 参考文档

# ALTER USER

更改 ClickHouse 用户账户。

语法：

```sql theme={null}
ALTER USER [IF EXISTS] name1 [RENAME TO new_name |, name2 [,...]]
    [ON CLUSTER cluster_name]
    [{VALID UNTIL datetime | VALID FOR interval}]
    [NOT IDENTIFIED | RESET AUTHENTICATION METHODS TO NEW | {IDENTIFIED | ADD IDENTIFIED} {[WITH {plaintext_password | sha256_password | sha256_hash | double_sha1_password | double_sha1_hash}] BY {'password' | 'hash'}} | WITH NO_PASSWORD | {WITH ldap SERVER 'server_name'} | {WITH kerberos [REALM 'realm']} | {WITH ssl_certificate CN 'common_name' | SAN 'TYPE:subject_alt_name'} | {WITH ssh_key BY KEY 'public_key' TYPE 'ssh-rsa|...'} | {WITH http SERVER 'server_name' [SCHEME 'Basic']} [{VALID UNTIL datetime | VALID FOR interval}] [GRANTS (privilege ON object [,...])]
    [, {[{plaintext_password | sha256_password | sha256_hash | ...}] BY {'password' | 'hash'}} | {ldap SERVER 'server_name'} | {...} | ... [,...]]]
    [[ADD | DROP] HOST {LOCAL | NAME 'name' | REGEXP 'name_regexp' | IP 'address' | LIKE 'pattern'} [,...] | ANY | NONE]
    [IN access_storage_type]
    [DEFAULT ROLE role [,...] | ALL | ALL EXCEPT role [,...] ]
    [GRANTEES {user | role | ANY | NONE} [,...] [EXCEPT {user | role} [,...]]]
    [DROP ALL PROFILES]
    [DROP ALL SETTINGS]
    [DROP SETTINGS variable [,...] ]
    [DROP PROFILES 'profile_name' [,...] ]
    [ADD|MODIFY SETTINGS variable [=value] [MIN [=] min_value] [MAX [=] max_value] [READONLY|WRITABLE|CONST|CHANGEABLE_IN_READONLY] [,...] ]
    [SET variable [=value] [MIN [=] min_value] [MAX [=] max_value] [READONLY|WRITABLE|CONST|CHANGEABLE_IN_READONLY] [,...] ]
    [ADD PROFILES 'profile_name' [,...] ]
```

要使用 `ALTER USER`，您必须具有 [ALTER USER](/zh/reference/statements/grant#access-management) 特权。

`SET variable = value` 是 `MODIFY SETTING variable = value` 的别名：它会原地修改单个设置，同时保留其余设置。相比裸 `SETTINGS` 子句 (它会替换整个 settings 列表，并移除所有继承的 (父) profile) ，请优先使用它 (或 `MODIFY SETTING`) 。

<div id="grantees-clause">
  ## GRANTEES 子句
</div>

指定哪些用户或角色可以从该用户处接收[权限](/zh/reference/statements/grant#privileges)，前提是该用户也已通过 [GRANT OPTION](/zh/reference/statements/grant#granting-privilege-syntax) 获得所有必需的访问权限。`GRANTEES` 子句的选项包括：

* `user` — 指定该用户可以向其授予权限的用户。
* `role` — 指定该用户可以向其授予权限的角色。
* `ANY` — 该用户可以向任何人授予权限。这是默认设置。
* `NONE` — 该用户不能向任何人授予权限。

你可以使用 `EXCEPT` 表达式排除任意用户或角色。例如，`ALTER USER user1 GRANTEES ANY EXCEPT user2`。这表示，如果 `user1` 拥有一些通过 `GRANT OPTION` 授予的权限，它就能够将这些权限授予除 `user2` 之外的任何人。

<div id="examples">
  ## 示例
</div>

将已分配的角色设置为默认角色：

```sql theme={null}
ALTER USER user DEFAULT ROLE role1, role2
```

如果此前未向用户分配任何角色，ClickHouse 会抛出异常。

将所有已分配的角色设为默认角色：

```sql theme={null}
ALTER USER user DEFAULT ROLE ALL
```

如果今后为用户分配了某个角色，它会自动成为默认角色。

将除 `role1` 和 `role2` 之外的所有已分配角色都设为默认角色：

```sql theme={null}
ALTER USER user DEFAULT ROLE ALL EXCEPT role1, role2
```

允许 `john` 账户对应的用户将其权限授予 `jack` 账户对应的用户：

```sql theme={null}
ALTER USER john GRANTEES jack;
```

在保留用户现有身份验证方法的同时，新增身份验证方法：

```sql theme={null}
ALTER USER user1 ADD IDENTIFIED WITH plaintext_password by '1', bcrypt_password by '2', plaintext_password by '3'
```

注意：

1. 较旧版本的 ClickHouse 可能不支持多种身份验证方法的语法。因此，如果 ClickHouse 服务器中存在此类用户，并且被降级到不支持该语法的版本，这些用户将无法再使用，某些与用户相关的操作也会失效。为了平稳降级，必须在降级前将所有用户都设置为只包含一种身份验证方法。或者，如果服务器未按正确流程完成降级，则应删除这些有问题的用户。
2. 出于安全原因，`no_password` 不能与其他身份验证方法共存。
   因此，无法 `ADD` 一个 `no_password` 身份验证方法。下面的查询将报错：

```sql theme={null}
ALTER USER user1 ADD IDENTIFIED WITH no_password
```

如果你想移除某个用户现有的身份验证方法并改用 `no_password`，则必须使用下面的替换形式进行指定。

重置身份验证方法，并添加查询中指定的方法 (即使用前导 `IDENTIFIED` 且不带 `ADD` 关键字时的效果) ：

```sql theme={null}
ALTER USER user1 IDENTIFIED WITH plaintext_password by '1', bcrypt_password by '2', plaintext_password by '3'
```

重置身份验证方法，并保留最近添加的一种：

```sql theme={null}
ALTER USER user1 RESET AUTHENTICATION METHODS TO NEW
```

<div id="valid-until-clause">
  ## VALID UNTIL 子句
</div>

用于指定身份验证方法的到期日期，以及可选的到期时间。它接受字符串参数。建议日期时间使用 `YYYY-MM-DD [hh:mm:ss] [timezone]` 格式。默认情况下，该参数为 `'infinity'`。可接受的截止时间范围为 `1900-01-01 00:00:00 UTC` 至 `9999-12-31 09:59:59 UTC`——这是在所有时区中仍处于 9999 年内的最晚时刻，因此存储的时刻在呈现时永远不会被截断。过去的截止时间表示凭据已过期。早于 `1970-01-01 00:00:01 UTC` 的截止时间仅接受作为“已过期”标记：它们会被规范化为最早的已过期时刻，即 Unix 纪元后一秒 (`1970-01-01 00:00:01 UTC`) ，因此 `SHOW CREATE USER` 显示的是该时刻，而非你指定的截止时间。自该时刻起的截止时间会被精确存储。

截止时间以绝对时刻存储，但 `SHOW CREATE USER` 和 [`system.users`](/zh/reference/system-tables/users) 会按服务器或会话时区显示，因此同一个存储时刻在配置不同的服务器上会显示为不同的本地时间文本：例如，上述规范化后的过期时刻在 `UTC` 服务器上显示为 `1970-01-01 00:00:01`，而在 `Pacific/Kiritimati` 服务器上显示为 `1970-01-01 14:00:01`。实际执行时始终使用存储的时刻，而非其显示形式。

子句的位置决定其适用的身份验证方法：

* 位于 `IDENTIFIED` 子句之前 (或查询未指定任何身份验证方法时) ：截止时间为用户级截止时间，适用于该用户的所有身份验证方法。
* 位于某个身份验证方法之后：截止时间仅适用于该方法。因此，写在整个 `IDENTIFIED` 列表之后的子句只会绑定到最后一个方法，之前的方法不会过期。

示例：

* `ALTER USER name1 VALID UNTIL '2025-01-01'`
* `ALTER USER name1 VALID UNTIL '2025-01-01 12:00:00 UTC'`
* `ALTER USER name1 VALID UNTIL 'infinity'`
* `ALTER USER name1 VALID UNTIL '2025-01-01' IDENTIFIED WITH plaintext_password BY 'password_1', bcrypt_password BY 'password_2'` — 用户级截止时间适用于这两种方法。
* `ALTER USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID UNTIL '2025-01-01'` — 截止时间仅适用于 `bcrypt_password` 方法；`plaintext_password` 永不过期。

<div id="valid-for-clause">
  ## VALID FOR 子句
</div>

`VALID FOR` 子句是 `VALID UNTIL` 的便捷写法。它不接受绝对日期和时间，而是接受一个[时间间隔](/zh/reference/data-types/special-data-types/interval)；执行查询时，过期截止时间将按当前时间加上该时间间隔计算。结果以 `VALID UNTIL` 形式存储，因此 `SHOW CREATE USER` 始终显示解析后的绝对截止时间。其位置规则与 `VALID UNTIL` 相同：位于 `IDENTIFIED` 之前 (或未指定身份验证方法) 时，它是适用于所有方法的用户级截止时间；位于某个身份验证方法之后时，则仅适用于该方法。截止时间以秒为精度存储和强制执行，因此不接受亚秒级时间间隔 (`NANOSECOND`、`MICROSECOND`、`MILLISECOND`) ；可接受的最小单位为 `SECOND`。可以使用负时间间隔将凭据标记为已过期；如果计算得出的截止时间早于 `1970-01-01 00:00:01 UTC`，则会将其规范化为该最早的过期时刻，之后 `SHOW CREATE USER` 会显示这一时刻——并按照 [`VALID UNTIL`](#valid-until-clause) 中所述，以服务器或会话时区呈现。

示例：

* `ALTER USER name1 VALID FOR INTERVAL 1 DAY`
* `ALTER USER name1 VALID FOR INTERVAL 3 MONTH`
* `ALTER USER name1 VALID FOR INTERVAL 30 DAY IDENTIFIED WITH plaintext_password BY 'password_1', bcrypt_password BY 'password_2'` — 用户级截止时间适用于两种方法。
* `ALTER USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID FOR INTERVAL 30 DAY` — 截止时间仅适用于 `bcrypt_password` 方法；`plaintext_password` 永不过期。

<div id="grants-clause">
  ## GRANTS 子句
</div>

用于限制采用特定身份验证方法进行身份验证的会话可拥有的访问权限。详见 [CREATE USER 的 GRANTS 子句](/zh/reference/statements/create/user#grants-clause)。

结合 `ADD IDENTIFIED` 使用，可以方便地为应用程序创建标记：一种具有到期日期且仅拥有有限特权的额外凭据。

示例：

* `ALTER USER name1 ADD IDENTIFIED WITH plaintext_password BY 'app_token' VALID UNTIL '2026-12-31' GRANTS (SELECT ON db.table, INSERT ON db.table)`