CREATE USER

Cria contas de usuário. Sintaxe:

CREATE USER [IF NOT EXISTS | OR REPLACE] name1 [, name2 [,...]] [ON CLUSTER cluster_name]
    [{VALID UNTIL datetime | VALID FOR interval}]
    [NOT IDENTIFIED | 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'} | {...} | ... [,...]]]
    [HOST {LOCAL | NAME 'name' | REGEXP 'name_regexp' | IP 'address' | LIKE 'pattern'} [,...] | ANY | NONE]
    [IN access_storage_type]
    [ROLE role [,...]]
    [DEFAULT ROLE role [,...]]
    [DEFAULT DATABASE database | NONE]
    [GRANTEES {user | role | ANY | NONE} [,...] [EXCEPT {user | role} [,...]]]
    [SETTINGS variable [= value] [MIN [=] min_value] [MAX [=] max_value] [READONLY | WRITABLE] | PROFILE 'profile_name'] [,...]

A cláusula ON CLUSTER permite criar usuários no cluster; consulte DDL distribuído.

Identificação

Há várias formas de identificação de usuário:

IDENTIFIED WITH no_password
IDENTIFIED WITH plaintext_password BY 'qwerty'
IDENTIFIED WITH sha256_password BY 'qwerty' or IDENTIFIED BY 'password'
IDENTIFIED WITH sha256_hash BY 'hash' or IDENTIFIED WITH sha256_hash BY 'hash' SALT 'salt'
IDENTIFIED WITH double_sha1_password BY 'qwerty'
IDENTIFIED WITH double_sha1_hash BY 'hash'
IDENTIFIED WITH bcrypt_password BY 'qwerty'
IDENTIFIED WITH bcrypt_hash BY 'hash'
IDENTIFIED WITH ldap SERVER 'server_name'
IDENTIFIED WITH kerberos or IDENTIFIED WITH kerberos REALM 'realm'
IDENTIFIED WITH ssl_certificate CN 'mysite.com:user'
IDENTIFIED WITH ssh_key BY KEY 'public_key' TYPE 'ssh-rsa', KEY 'another_public_key' TYPE 'ssh-ed25519'
IDENTIFIED WITH http SERVER 'http_server' or IDENTIFIED WITH http SERVER 'http_server' SCHEME 'basic'
IDENTIFIED BY 'qwerty'

Os requisitos de complexidade de senha podem ser editados em config.xml. Abaixo está um exemplo de configuração que exige que as senhas tenham pelo menos 12 caracteres e contenham 1 número. Cada regra de complexidade de senha exige uma regex para corresponder às senhas e uma descrição da regra.

<clickhouse>
    <password_complexity>
        <rule>
            <pattern>.{12}</pattern>
            <message>be at least 12 characters long</message>
        </rule>
        <rule>
            <pattern>\p{N}</pattern>
            <message>contain at least 1 numeric character</message>
        </rule>
    </password_complexity>
</clickhouse>

No ClickHouse Cloud, por padrão, as senhas devem atender aos seguintes requisitos de complexidade:

Ter no mínimo 12 caracteres
Conter pelo menos 1 caractere numérico
Conter pelo menos 1 letra maiúscula
Conter pelo menos 1 letra minúscula
Conter pelo menos 1 caractere especial

Exemplos

O nome de usuário a seguir é name1 e não exige senha — o que obviamente não oferece muita segurança:
CREATE USER name1 NOT IDENTIFIED

Para especificar uma senha em texto simples:

CREATE USER name2 IDENTIFIED WITH plaintext_password BY 'my_password'

A senha é armazenada em um arquivo de texto SQL em /var/lib/clickhouse/access, portanto não é uma boa ideia usar plaintext_password. Em vez disso, experimente sha256_password, como mostrado a seguir…

A opção mais comum é usar uma senha com hash SHA-256. O ClickHouse calculará o hash da senha para você quando você especificar IDENTIFIED WITH sha256_password. Por exemplo:
CREATE USER name3 IDENTIFIED WITH sha256_password BY 'my_password'
O usuário name3 agora pode fazer login com my_password, mas a senha é armazenada como o valor de hash acima. O arquivo SQL a seguir foi criado em /var/lib/clickhouse/access e é executado na inicialização do servidor:
/var/lib/clickhouse/access $ cat 3843f510-6ebd-a52d-72ac-e021686d8a93.sql ATTACH USER name3 IDENTIFIED WITH sha256_hash BY '0C268556C1680BEF0640AAC1E7187566704208398DA31F03D18C74F5C5BE5053' SALT '4FB16307F5E10048196966DD7E6876AE53DE6A1D1F625488482C75F14A5097C7';

Se você já criou um valor de hash e o valor de salt correspondente para um nome de usuário, pode usar IDENTIFIED WITH sha256_hash BY 'hash' ou IDENTIFIED WITH sha256_hash BY 'hash' SALT 'salt'. Para identificação com sha256_hash usando SALT, o hash deve ser calculado a partir da concatenação de ‘password’ e ‘salt’.

O double_sha1_password normalmente não é necessário, mas é útil ao trabalhar com clientes que o exigem (como a interface MySQL):
CREATE USER name4 IDENTIFIED WITH double_sha1_password BY 'my_password'
O ClickHouse gera e executa a seguinte consulta:
CREATE USER name4 IDENTIFIED WITH double_sha1_hash BY 'CCD3A959D6A004B9C3807B728BC2E55B67E10518'
O bcrypt_password é a opção mais segura para armazenar senhas. Ele usa o algoritmo bcrypt, que é resistente a ataques de força bruta, mesmo se o hash da senha for comprometido.
CREATE USER name5 IDENTIFIED WITH bcrypt_password BY 'my_password'
O comprimento da senha é limitado a 72 caracteres com esse método. O parâmetro de fator de trabalho do bcrypt, que define a quantidade de computação e o tempo necessários para calcular o hash e verificar a senha, pode ser modificado na configuração do servidor:
<bcrypt_workfactor>12</bcrypt_workfactor>
O fator de trabalho deve estar entre 4 e 31, com valor padrão de 12.

Para aplicações com autenticação de alta frequência, considere métodos alternativos de autenticação devido à sobrecarga computacional do bcrypt em fatores de trabalho mais altos.

O tipo de senha também pode ser omitido:
CREATE USER name6 IDENTIFIED BY 'my_password'
Nesse caso, o ClickHouse usará o tipo de senha padrão especificado na configuração do servidor:
<default_password_type>sha256_password</default_password_type>
Os tipos de senha disponíveis são: plaintext_password, sha256_password, double_sha1_password.

É possível especificar vários métodos de autenticação:

CREATE USER user1 IDENTIFIED WITH plaintext_password by '1', bcrypt_password by '2', plaintext_password by '3''

Observações:

Versões mais antigas do ClickHouse talvez não ofereçam suporte à sintaxe de múltiplos métodos de autenticação. Portanto, se o servidor do 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.
no_password não pode coexistir com outros métodos de autenticação por motivos de segurança. Portanto, você só pode especificar no_password se ele for o único método de autenticação na consulta.

Host do usuário

O host do usuário é o host a partir do qual uma conexão com o servidor ClickHouse pode ser estabelecida. O host pode ser especificado na seção HOST da consulta das seguintes formas:

HOST IP 'ip_address_or_subnetwork' — O usuário pode se conectar ao servidor ClickHouse somente a partir do endereço IP especificado ou de uma sub-rede. Exemplos: HOST IP '192.168.0.0/16', HOST IP '2001:DB8::/32'. Para uso em produção, especifique apenas elementos HOST IP (endereços IP e suas máscaras), pois o uso de host e host_regexp pode causar latência adicional.
HOST ANY — O usuário pode se conectar de qualquer lugar. Esta é a opção padrão.
HOST LOCAL — O usuário pode se conectar apenas localmente.
HOST NAME 'fqdn' — O host do usuário pode ser especificado como FQDN. Por exemplo, HOST NAME 'mysite.com'.
HOST REGEXP 'regexp' — Você pode usar expressões regulares pcre ao especificar hosts de usuário. Por exemplo, HOST REGEXP '.*\.mysite\.com'.
HOST LIKE 'template' — Permite usar o operador LIKE para filtrar os hosts do usuário. Por exemplo, HOST LIKE '%' é equivalente a HOST ANY, e HOST LIKE '%.mysite.com' filtra todos os hosts no domínio mysite.com.

Outra forma de especificar o host é usar a sintaxe @ após o nome de usuário. Exemplos:

CREATE USER mira@'127.0.0.1' — Equivalente à sintaxe HOST IP.
CREATE USER mira@'localhost' — Equivalente à sintaxe HOST LOCAL.
CREATE USER mira@'192.168.%.%' — Equivalente à sintaxe HOST LIKE.

O ClickHouse trata user_name@'address' como um nome de usuário completo. Assim, tecnicamente, é possível criar vários usuários com o mesmo user_name e construções diferentes após @. No entanto, não recomendamos fazer isso.

Cláusula VALID UNTIL

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 data e hora, em que [timezone] deve ser um deslocamento numérico, como +09:00, ou um dos seguintes: UTC, GMT, Z, MSK, MSD; zonas IANA nomeadas, como Asia/Tokyo, não são reconhecidas (consulte a observação abaixo). Por padrão, esse parâmetro é igual a 'infinity'. O intervalo aceito para o prazo vai de 1900-01-01 00:00:00 UTC a 9999-12-31 09:59:59 UTC — o instante mais recente que permanece no ano 9999 em todos os fusos horários, garantindo que o instante armazenado nunca seja limitado ao ser exibido. 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 um marcador de “já expirado”: são normalizados para o menor instante expirado canônico, um segundo após a epoch Unix (1970-01-01 00:00:01 UTC), de modo que SHOW CREATE USER informa esse instante em vez do prazo especificado. Prazos a partir desse instante são armazenados exatamente. Um prazo é armazenado como um instante absoluto, mas SHOW CREATE USER e system.users o exibem no fuso horário do servidor ou da sessão. Assim, o mesmo instante armazenado aparece como horários locais diferentes em servidores configurados de forma distinta: o instante expirado normalizado acima, por exemplo, é exibido como 1970-01-01 00:00:01 em um servidor com fuso horário UTC e como 1970-01-01 14:00:01 em um servidor com fuso horário Pacific/Kiritimati. A validação sempre usa o instante armazenado, não sua representação exibida. O posicionamento 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 somente a esse método. Portanto, uma cláusula escrita após toda a lista IDENTIFIED se vincula somente ao último método, deixando os métodos anteriores sem expiração.

Exemplos:

CREATE USER name1 VALID UNTIL '2025-01-01'
CREATE USER name1 VALID UNTIL '2025-01-01 12:00:00 UTC'
CREATE USER name1 VALID UNTIL '2025-01-01 12:00:00 +09:00'
CREATE USER name1 VALID UNTIL 'infinity'
CREATE USER name1 VALID UNTIL '2025-01-01' 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.
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID UNTIL '2025-01-01' — o prazo se aplica somente ao método bcrypt_password; plaintext_password nunca expira.

A string de data e hora é convertida por parseDateTimeBestEffort, que reconhece somente os tokens de fuso horário UTC, GMT, Z, MSK, MSD e deslocamentos numéricos como +09:00 ou -05:00. Fusos horários IANA nomeados, como Asia/Tokyo ou Europe/London, não são suportados, e um deslocamento fixo não é equivalente a uma zona IANA em regiões que adotam horário de verão. Portanto, você deve calcular o deslocamento correto para a data específica que está codificando.

Cláusula VALID FOR

A cláusula VALID FOR é uma abreviação conveniente de VALID UNTIL. Em vez de uma data e hora absolutas, ela aceita um intervalo, e o prazo de expiração é calculado como a hora atual mais esse intervalo no momento da execução da consulta. O resultado é então armazenado no formato VALID UNTIL, portanto SHOW CREATE USER sempre exibe o prazo absoluto resultante. Ela pode ser usada em todos os lugares em que VALID UNTIL pode ser usado e segue as mesmas regras de posicionamento: antes de IDENTIFIED (ou sem método de autenticação), define 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 apenas a esse método. O prazo é armazenado e aplicado com precisão de segundos; portanto, intervalos com frações de segundo (NANOSECOND, MICROSECOND, MILLISECOND) são rejeitados, e a menor unidade aceita é SECOND. Um intervalo negativo é aceito para 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 valor informado por SHOW CREATE USER — exibido no fuso horário do servidor ou da sessão, conforme descrito em VALID UNTIL. Exemplos:

CREATE USER name1 VALID FOR INTERVAL 1 DAY
CREATE USER name1 VALID FOR INTERVAL 3 MONTH
CREATE USER name1 VALID FOR INTERVAL 1 DAY + INTERVAL 12 HOUR
CREATE 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.
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID FOR INTERVAL 30 DAY — o prazo se aplica apenas ao método bcrypt_password; plaintext_password nunca expira.

Cláusula GRANTS

Permite limitar os direitos de acesso disponíveis para uma sessão autenticada por um determinado método de autenticação. Aceita uma lista de privilégios, entre parênteses, no mesmo formato da instrução GRANT. A cláusula é especificada após um método de autenticação (após a respectiva cláusula VALID UNTIL, se houver) e se aplica somente a esse método. Quando um usuário faz login com esse método de autenticação, os direitos de acesso da sessão são a interseção entre os direitos de acesso do usuário (incluindo os direitos provenientes das roles concedidas) e os privilégios listados na cláusula. A cláusula nunca adiciona direitos de acesso: se um privilégio listado não tiver sido concedido ao usuário, a sessão não o terá. Sessões autenticadas com esse método também não podem conceder privilégios (a GRANT OPTION nunca é mantida após a interseção) nem administrar roles. Administrar roles inclui não apenas criar, alterar, excluir, conceder e revogar roles, mas também alterar quais roles são ativadas por padrão para um usuário (SET DEFAULT ROLE e ALTER USER ... DEFAULT ROLE), o que também é rejeitado. EXECUTE AS altera o principal da sessão; portanto, uma instrução executada por impersonation é limitada pela interseção entre os direitos de acesso do usuário target e os privilégios listados, em vez dos direitos do usuário que fez login. O limite em si nunca é removido, e a impersonation exige que IMPERSONATE ON target tenha sido concedido ao usuário e esteja listado na cláusula. Assim, uma credencial limitada nunca pode ir além da credencial ilimitada do mesmo usuário. Isso oferece uma forma conveniente de criar tokens para aplicações: uma credencial adicional, com data de expiração e um conjunto limitado de privilégios, vinculada ao usuário — ela é exibida em system.query_log e system.processes como o usuário, deixa de funcionar se o usuário for excluído e perde direitos de acesso quando o usuário os perde.

A aplicação ocorre somente no initiator. O limite GRANTS do método de autenticação e sua expiração VALID UNTIL são aplicados somente no node que recebe a consulta (o initiator). Eles não são propagados para outros nodes de um cluster; portanto, não use a cláusula para restringir a execução em todo o cluster. Os nodes remotos mantêm seu escopo habitual de roles. A cláusula também não está disponível em users.xml. O query result cache é compartilhado por todos os métodos de autenticação de um usuário: ele isola entradas por usuário e roles, e um acerto no cache não é verificado novamente em relação aos GRANTS do método com o qual a sessão fez login.

Exemplos:

CREATE USER name1 IDENTIFIED BY 'qwerty' GRANTS (SELECT ON db.*)
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)

Observe que o limite é uma propriedade do método de autenticação, registrada no momento do login: alterar a cláusula com ALTER USER afeta novas sessões, não as já estabelecidas. Grants de source filtrada, como READ ON S3('s3://bucket/.*'), ainda não são compatíveis com a cláusula: a interseção compara um Source filter como uma string opaca e não consegue restringir um filtro em relação a outro; por isso, esse grant é rejeitado em vez de silenciosamente não conceder acesso. A cláusula é compatível apenas com métodos de autenticação cujas credenciais são verificadas exclusivamente localmente pelo servidor. Para métodos cuja verificação entra em contato com um sistema externo (ou, no caso de jwt, pode entrar em contato — por exemplo, para buscar as chaves de assinatura) (ldap, kerberos, http, jwt), a cláusula é rejeitada: quando vários métodos de autenticação aceitam a mesma credencial, o limite é aplicado verificando novamente a credencial em relação aos outros métodos, e uma consulta adicional a um sistema externo não é segura; portanto, outro método que aceite a mesma credencial poderia contornar o limite. Quando a mesma credencial efetiva é aceita por mais de um método de autenticação, o login é limitado em modo fail-close por todos eles: a sessão recebe a interseção dos GRANTS de todos os métodos correspondentes e expira no VALID UNTIL mais próximo. O VALID UNTIL mais próximo prevalece mesmo que já tenha passado — o login é rejeitado, exatamente como se o único método correspondente tivesse expirado, de modo que a expiração de um token nunca concede silenciosamente à credencial compartilhada os direitos ou a duração de um método mais abrangente. Essa combinação é verificada apenas entre métodos de autenticação verificados localmente pelo servidor, pelo mesmo motivo pelo qual a própria cláusula é rejeitada para um método verificado externamente: verificar novamente a credencial nesse caso exigiria uma consulta adicional e insegura ao sistema externo. Portanto, se a mesma credencial também for aceita por um método verificado externamente (ldap, kerberos, http, jwt) para o mesmo usuário, o VALID UNTIL desse método não faz parte da combinação, e uma expiração anterior configurada nele não encurta a sessão obtida por meio do método verificado localmente.

Cláusula GRANTEES

Especifica os usuários ou roles que podem receber privilégios deste usuário, desde que ele também tenha todos os acessos necessários concedidos com GRANT OPTION. Opções da cláusula GRANTEES:

user — Especifica um usuário ao qual este usuário pode conceder privilégios.
role — Especifica uma role à qual este usuário pode conceder privilégios.
ANY — Este usuário pode conceder privilégios a qualquer um. Esta é a configuração padrão.
NONE — Este usuário não pode conceder privilégios a ninguém.

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

Exemplos

Crie a conta de usuário mira, protegida pela senha qwerty:

CREATE USER mira HOST IP '127.0.0.1' IDENTIFIED WITH sha256_password BY 'qwerty';

mira deve iniciar o aplicativo cliente no host em que o servidor ClickHouse está em execução. Crie a conta de usuário john e atribua roles:

CREATE USER john ROLE role1, role2;

Crie a conta de usuário john, atribua roles e defina algumas delas como padrão:

CREATE USER john ROLE role1, role2 DEFAULT ROLE role1;

CREATE USER john ROLE role1, role2 DEFAULT ROLE ALL EXCEPT role2;

Crie a conta de usuário john e permita que ele conceda seus privilégios ao usuário da conta jack:

CREATE USER john GRANTEES jack;

Use um parâmetro de consulta para criar a conta de usuário john:

SET param_user=john;
CREATE USER {user:Identifier};

SQL Reference

Data Types

Engines

Functions

Formats

Interfaces

Settings

System Tables

Data Lakes

Identificação

Exemplos

Host do usuário

Cláusula VALID UNTIL

Cláusula VALID FOR

Cláusula GRANTS

Cláusula GRANTEES

Exemplos

​Identificação

​Exemplos

​Host do usuário

​Cláusula VALID UNTIL

​Cláusula VALID FOR

​Cláusula GRANTS

​Cláusula GRANTEES

​Exemplos

Identificação

Exemplos

Host do usuário

Cláusula VALID UNTIL

Cláusula VALID FOR

Cláusula GRANTS

Cláusula GRANTEES

Exemplos