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

> Documentação sobre USER

# ALTER USER

Altera contas de usuário no ClickHouse.

Sintaxe:

```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' [,...] ]
```

Para usar `ALTER USER`, é necessário ter o privilégio [ALTER USER](/pt-BR/reference/statements/grant#access-management).

`SET variable = value` é um alias para `MODIFY SETTING variable = value`: ele altera uma única configuração diretamente, mantendo as demais. Prefira-o (ou `MODIFY SETTING`) em vez da cláusula `SETTINGS` sem modificador, que substitui toda a lista de configurações e também remove todos os perfis herdados (pais).

<div id="grantees-clause">
  ## Cláusula GRANTEES
</div>

Especifica os usuários ou funções que podem receber [privilégios](/pt-BR/reference/statements/grant#privileges) deste usuário, desde que ele também tenha todas as permissões necessárias concedidas com [GRANT OPTION](/pt-BR/reference/statements/grant#granting-privilege-syntax). Opções da cláusula `GRANTEES`:

* `user` — Especifica um usuário ao qual este usuário pode conceder privilégios.
* `role` — Especifica uma função à qual este usuário pode conceder privilégios.
* `ANY` — Este usuário pode conceder privilégios a qualquer usuário ou função. É a configuração padrão.
* `NONE` — Este usuário não pode conceder privilégios a nenhum usuário ou função.

Você pode excluir qualquer usuário ou função usando a expressão `EXCEPT`. Por exemplo, `ALTER USER user1 GRANTEES ANY EXCEPT user2`. Isso significa que, se `user1` tiver privilégios concedidos com `GRANT OPTION`, ele poderá concedê-los a qualquer usuário ou função, exceto `user2`.

<div id="examples">
  ## Exemplos
</div>

Defina as funções atribuídas como padrão:

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

Se nenhuma função tiver sido atribuída previamente a um usuário, o ClickHouse lança uma exceção.

Defina como padrão todas as funções atribuídas:

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

Se uma função for atribuída a um usuário no futuro, ela se tornará padrão automaticamente.

Defina como padrão todas as funções atribuídas, exceto `role1` e `role2`:

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

Permite que o usuário da conta `john` conceda seus privilégios ao usuário da conta `jack`:

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

Adiciona novos métodos de autenticação ao usuário, mantendo os métodos existentes:

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

Observações:

1. Versões mais antigas do ClickHouse podem não oferecer suporte à sintaxe de vários métodos de autenticação. Portanto, se o servidor ClickHouse contiver esses usuários e passar por downgrade para uma versão que não ofereça esse suporte, esses usuários se tornarão inutilizáveis, e algumas operações relacionadas a usuários deixarão de funcionar. Para fazer o downgrade corretamente, é necessário configurar todos os usuários para que tenham um único método de autenticação antes do downgrade. Como alternativa, se o servidor tiver passado por downgrade sem o procedimento adequado, os usuários com problema deverão ser removidos.
2. `no_password` não pode coexistir com outros métodos de autenticação por motivos de segurança.
   Por isso, não é possível `ADD` um método de autenticação `no_password`. A consulta abaixo gerará um erro:

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

Se você quiser remover os métodos de autenticação de um usuário e usar `no_password`, deverá especificar isso na forma de substituição abaixo.

Redefine os métodos de autenticação e adiciona os especificados na consulta (efeito de um IDENTIFIED inicial sem a palavra-chave ADD):

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

Redefina os métodos de autenticação e mantenha o mais recentemente adicionado:

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

<div id="valid-until-clause">
  ## Cláusula VALID UNTIL
</div>

Permite especificar a data de expiração e, opcionalmente, a hora de um método de autenticação. Aceita uma string como parâmetro. Recomenda-se usar o formato `YYYY-MM-DD [hh:mm:ss] [timezone]` para datetime. Por padrão, esse parâmetro é igual a `'infinity'`. O intervalo de prazos aceito vai de `1900-01-01 00:00:00 UTC` a `9999-12-31 09:59:59 UTC` — o último instante que permanece dentro do ano 9999 em todos os fusos horários, garantindo que o instante armazenado nunca seja limitado durante a exibição. Um prazo no passado significa que as credenciais já expiraram. Prazos anteriores a `1970-01-01 00:00:01 UTC` são aceitos apenas como marcador de "já expirado": são normalizados para o menor instante expirado, um segundo após a epoch Unix (`1970-01-01 00:00:01 UTC`), de modo que `SHOW CREATE USER` informe esse instante em vez do prazo informado. Prazos a partir desse instante são armazenados exatamente como especificados.

Um prazo é armazenado como um instante absoluto, mas `SHOW CREATE USER` e [`system.users`](/pt-BR/reference/system-tables/users) o exibem no fuso horário do servidor ou da sessão. Portanto, o mesmo instante armazenado aparece como horários locais diferentes em servidores configurados de modo distinto: por exemplo, o instante expirado normalizado acima é exibido como `1970-01-01 00:00:01` em um servidor com `UTC` e como `1970-01-01 14:00:01` em um servidor com `Pacific/Kiritimati`. A validação sempre usa o instante armazenado, não sua exibição.

A posição da cláusula determina a quais métodos de autenticação ela se aplica:

* Antes da cláusula `IDENTIFIED` (ou quando a consulta não especifica nenhum método de autenticação): o prazo é definido no nível do usuário e se aplica a todos os métodos de autenticação desse usuário.
* Após um método de autenticação: o prazo se aplica apenas a esse método. Portanto, uma cláusula escrita após toda a lista `IDENTIFIED` vincula-se apenas ao último método, deixando os métodos anteriores sem expiração.

Exemplos:

* `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'` — o prazo definido no nível do usuário se aplica a ambos os métodos.
* `ALTER USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID UNTIL '2025-01-01'` — o prazo se aplica apenas ao método `bcrypt_password`; `plaintext_password` nunca expira.

<div id="valid-for-clause">
  ## Cláusula VALID FOR
</div>

A cláusula `VALID FOR` é uma forma abreviada conveniente de `VALID UNTIL`. Em vez de uma data e hora absolutas, ela aceita um [intervalo](/pt-BR/reference/data-types/special-data-types/interval), e o prazo de expiração é calculado como a hora atual acrescida desse intervalo no momento em que a consulta é executada. O resultado é armazenado no formato `VALID UNTIL`, portanto `SHOW CREATE USER` sempre exibe o prazo absoluto resolvido. Ela segue as mesmas regras de posicionamento de `VALID UNTIL`: antes de `IDENTIFIED` (ou sem um método de autenticação), representa um prazo no nível do usuário que se aplica a todos os métodos; após um método de autenticação, aplica-se somente a esse método. O prazo é armazenado e aplicado com precisão de segundos, portanto intervalos inferiores a um segundo (`NANOSECOND`, `MICROSECOND`, `MILLISECOND`) são rejeitados; a menor unidade aceita é `SECOND`. Um intervalo negativo é aceito como forma de marcar as credenciais como já expiradas; se o prazo resultante for anterior a `1970-01-01 00:00:01 UTC`, ele será normalizado para esse menor instante expirado, que é o que `SHOW CREATE USER` informa — exibido no fuso horário do servidor ou da sessão, conforme descrito para [`VALID UNTIL`](#valid-until-clause).

Exemplos:

* `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'` — o prazo no nível do usuário se aplica a ambos os métodos.
* `ALTER USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID FOR INTERVAL 30 DAY` — o prazo se aplica somente ao método `bcrypt_password`; `plaintext_password` nunca expira.

<div id="grants-clause">
  ## Cláusula GRANTS
</div>

Permite limitar os direitos de acesso disponíveis em uma sessão autenticada por um método de autenticação específico. Consulte a [cláusula GRANTS de CREATE USER](/pt-BR/reference/statements/create/user#grants-clause) para mais detalhes.

Em conjunto com `ADD IDENTIFIED`, fornece uma forma prática de criar tokens para aplicações: uma credencial adicional com data de expiração e um conjunto limitado de privilégios.

Exemplo:

* `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)`