CREATE USER

Crée des comptes utilisateurs. Syntaxe :

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

La clause ON CLUSTER permet de créer des utilisateurs sur un cluster, voir DDL distribué.

Identification

Il existe plusieurs modes d’identification des utilisateurs :

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'

Les exigences de complexité des mots de passe peuvent être modifiées dans config.xml. Vous trouverez ci-dessous un exemple de configuration qui impose des mots de passe d’au moins 12 caractères et contenant 1 chiffre. Chaque règle de complexité des mots de passe nécessite une expression régulière à faire correspondre aux mots de passe, ainsi qu’une description de la règle.

<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>

Dans ClickHouse Cloud, par défaut, les mots de passe doivent respecter les exigences de complexité suivantes :

Comporter au moins 12 caractères
Contenir au moins 1 chiffre
Contenir au moins 1 majuscule
Contenir au moins 1 minuscule
Contenir au moins 1 caractère spécial

Exemples

Le nom d’utilisateur suivant est name1 et ne nécessite pas de mot de passe, ce qui n’offre évidemment guère de sécurité :
CREATE USER name1 NOT IDENTIFIED

Pour spécifier un mot de passe en clair :

CREATE USER name2 IDENTIFIED WITH plaintext_password BY 'my_password'

Le mot de passe est stocké dans un fichier texte SQL dans /var/lib/clickhouse/access. Il n’est donc pas recommandé d’utiliser plaintext_password. Préférez plutôt sha256_password, comme indiqué ci-dessous…

L’option la plus courante consiste à utiliser un mot de passe haché avec SHA-256. ClickHouse hachera le mot de passe pour vous lorsque vous spécifiez IDENTIFIED WITH sha256_password. Par exemple :
CREATE USER name3 IDENTIFIED WITH sha256_password BY 'my_password'
L’utilisateur name3 peut désormais se connecter avec my_password, mais le mot de passe est stocké sous la forme de la valeur de hachage ci-dessus. Le fichier SQL suivant a été créé dans /var/lib/clickhouse/access et est exécuté au démarrage du serveur :
/var/lib/clickhouse/access $ cat 3843f510-6ebd-a52d-72ac-e021686d8a93.sql ATTACH USER name3 IDENTIFIED WITH sha256_hash BY '0C268556C1680BEF0640AAC1E7187566704208398DA31F03D18C74F5C5BE5053' SALT '4FB16307F5E10048196966DD7E6876AE53DE6A1D1F625488482C75F14A5097C7';

Si vous avez déjà créé une valeur de hachage et la valeur de sel correspondante pour un nom d’utilisateur, vous pouvez utiliser IDENTIFIED WITH sha256_hash BY 'hash' ou IDENTIFIED WITH sha256_hash BY 'hash' SALT 'salt'. Pour l’identification avec sha256_hash à l’aide de SALT, le hachage doit être calculé à partir de la concaténation de ‘password’ et de ‘salt’.

double_sha1_password n’est généralement pas nécessaire, mais s’avère pratique lorsque vous travaillez avec des clients qui l’exigent (comme l’interface MySQL) :
CREATE USER name4 IDENTIFIED WITH double_sha1_password BY 'my_password'
ClickHouse génère et exécute la requête suivante :
CREATE USER name4 IDENTIFIED WITH double_sha1_hash BY 'CCD3A959D6A004B9C3807B728BC2E55B67E10518'
bcrypt_password est l’option la plus sûre pour stocker les mots de passe. Il utilise l’algorithme bcrypt, qui résiste aux attaques par force brute même si le hachage du mot de passe est compromis.
CREATE USER name5 IDENTIFIED WITH bcrypt_password BY 'my_password'
La longueur du mot de passe est limitée à 72 caractères avec cette méthode. Le paramètre de facteur de coût de bcrypt, qui définit la quantité de calculs et le temps nécessaires pour calculer le hachage et vérifier le mot de passe, peut être modifié dans la configuration du serveur :
<bcrypt_workfactor>12</bcrypt_workfactor>
Le facteur de coût doit être compris entre 4 et 31, avec une valeur par défaut de 12.

Pour les applications avec une authentification à haute fréquence, envisagez d’autres méthodes d’authentification en raison du coût de calcul de bcrypt avec des facteurs de coût élevés.

Le type de mot de passe peut également être omis :
CREATE USER name6 IDENTIFIED BY 'my_password'
Dans ce cas, ClickHouse utilisera le type de mot de passe par défaut spécifié dans la configuration du serveur :
<default_password_type>sha256_password</default_password_type>
Les types de mot de passe disponibles sont : plaintext_password, sha256_password, double_sha1_password.

Plusieurs méthodes d’authentification peuvent être spécifiées :

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

Remarques :

Les anciennes versions de ClickHouse peuvent ne pas prendre en charge la syntaxe associée à plusieurs méthodes d’authentification. Par conséquent, si le serveur ClickHouse contient de tels utilisateurs et qu’il est rétrogradé vers une version qui ne la prend pas en charge, ces utilisateurs deviendront inutilisables et certaines opérations liées aux utilisateurs ne fonctionneront plus. Pour effectuer une rétrogradation proprement, il faut configurer tous les utilisateurs pour qu’ils n’utilisent qu’une seule méthode d’authentification avant la rétrogradation. Sinon, si le serveur a été rétrogradé sans suivre la procédure appropriée, les utilisateurs défectueux doivent être supprimés.
no_password ne peut pas coexister avec d’autres méthodes d’authentification pour des raisons de sécurité. Par conséquent, vous ne pouvez spécifier no_password que s’il s’agit de la seule méthode d’authentification dans la requête.

Hôte de l’utilisateur

L’hôte de l’utilisateur est l’hôte depuis lequel une connexion au serveur ClickHouse peut être établie. L’hôte peut être spécifié dans la section HOST de la requête des façons suivantes :

HOST IP 'ip_address_or_subnetwork' — L’utilisateur peut se connecter au serveur ClickHouse uniquement depuis l’adresse IP spécifiée ou un sous-réseau. Exemples : HOST IP '192.168.0.0/16', HOST IP '2001:DB8::/32'. Pour une utilisation en production, spécifiez uniquement des éléments HOST IP (adresses IP et leurs masques), car l’utilisation de host et host_regexp peut entraîner une latence supplémentaire.
HOST ANY — L’utilisateur peut se connecter depuis n’importe où. Il s’agit de l’option par défaut.
HOST LOCAL — L’utilisateur peut se connecter uniquement en local.
HOST NAME 'fqdn' — L’hôte de l’utilisateur peut être spécifié sous forme de FQDN. Par exemple, HOST NAME 'mysite.com'.
HOST REGEXP 'regexp' — Vous pouvez utiliser des expressions régulières pcre lorsque vous spécifiez les hôtes des utilisateurs. Par exemple, HOST REGEXP '.*\.mysite\.com'.
HOST LIKE 'template' — Permet d’utiliser l’opérateur LIKE pour filtrer les hôtes des utilisateurs. Par exemple, HOST LIKE '%' est équivalent à HOST ANY, HOST LIKE '%.mysite.com' filtre tous les hôtes du domaine mysite.com.

Une autre façon de spécifier l’hôte consiste à utiliser la syntaxe @ après le nom d’utilisateur. Exemples :

CREATE USER mira@'127.0.0.1' — Équivalent à la syntaxe HOST IP.
CREATE USER mira@'localhost' — Équivalent à la syntaxe HOST LOCAL.
CREATE USER mira@'192.168.%.%' — Équivalent à la syntaxe HOST LIKE.

ClickHouse traite user_name@'address' comme un nom d’utilisateur complet. Ainsi, techniquement, vous pouvez créer plusieurs utilisateurs avec le même user_name et différentes variantes après @. Cependant, nous vous déconseillons de le faire.

Clause VALID UNTIL

Permet de spécifier la date d’expiration et, éventuellement, l’heure d’une méthode d’authentification. Accepte une chaîne de caractères comme paramètre. Il est recommandé d’utiliser le format YYYY-MM-DD [hh:mm:ss] [timezone] pour la date et l’heure, où [timezone] doit être un décalage numérique tel que +09:00 ou l’un des suivants : UTC, GMT, Z, MSK, MSD ; les zones IANA nommées telles que Asia/Tokyo ne sont pas reconnues (voir la remarque ci-dessous). Par défaut, ce paramètre est défini sur 'infinity'. La plage d’échéances acceptée s’étend de 1900-01-01 00:00:00 UTC à 9999-12-31 09:59:59 UTC — le dernier instant restant dans l’année 9999 dans tous les fuseaux horaires, afin que l’instant stocké ne soit jamais tronqué lors de son affichage. Une échéance dans le passé signifie que les identifiants ont déjà expiré. Les échéances antérieures à 1970-01-01 00:00:01 UTC ne sont acceptées que comme marqueur « déjà expiré » : elles sont normalisées au plus ancien instant expiré, soit une seconde après l’époque Unix (1970-01-01 00:00:01 UTC), de sorte que SHOW CREATE USER affiche cet instant plutôt que l’échéance que vous avez indiquée. Les échéances à partir de cet instant sont stockées telles quelles. Une échéance est stockée sous forme d’instant absolu, mais SHOW CREATE USER et system.users l’affichent dans le fuseau horaire du serveur ou de la session. Ainsi, un même instant stocké apparaît sous la forme d’heures locales différentes sur des serveurs configurés différemment : l’instant expiré normalisé ci-dessus, par exemple, s’affiche sous la forme 1970-01-01 00:00:01 sur un serveur en UTC et sous la forme 1970-01-01 14:00:01 sur un serveur en Pacific/Kiritimati. La vérification utilise toujours l’instant stocké, et non son affichage. L’emplacement de la clause détermine les méthodes d’authentification auxquelles elle s’applique :

Avant la clause IDENTIFIED (ou lorsque la requête ne spécifie aucune méthode d’authentification) : l’échéance est définie au niveau de l’utilisateur et s’applique à toutes ses méthodes d’authentification.
Après une méthode d’authentification : l’échéance s’applique uniquement à cette méthode. Une clause écrite après l’ensemble de la liste IDENTIFIED ne s’applique donc qu’à la dernière méthode, les méthodes précédentes n’ayant pas d’expiration.

Exemples :

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' — l’échéance définie au niveau de l’utilisateur s’applique aux deux méthodes.
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID UNTIL '2025-01-01' — l’échéance s’applique uniquement à la méthode bcrypt_password ; plaintext_password n’expire jamais.

La chaîne de date et d’heure est analysée par parseDateTimeBestEffort, qui reconnaît uniquement les jetons de fuseau horaire UTC, GMT, Z, MSK, MSD et les décalages numériques tels que +09:00 ou -05:00. Les fuseaux horaires IANA nommés tels que Asia/Tokyo ou Europe/London ne sont pas pris en charge, et un décalage fixe n’est pas équivalent à une zone IANA pour les régions qui observent l’heure d’été ; vous devez donc calculer le décalage correct pour la date précise que vous encodez.

Clause VALID FOR

La clause VALID FOR est une forme abrégée pratique de VALID UNTIL. Au lieu d’une date et d’une heure absolues, elle accepte un intervalle, et l’échéance d’expiration est calculée en ajoutant cet intervalle à l’heure actuelle au moment de l’exécution de la requête. Le résultat est ensuite stocké au format VALID UNTIL, de sorte que SHOW CREATE USER affiche toujours l’échéance absolue résolue. Elle peut être utilisée partout où VALID UNTIL est autorisé et obéit aux mêmes règles de positionnement : avant IDENTIFIED (ou en l’absence de méthode d’authentification), elle définit une échéance au niveau de l’utilisateur qui s’applique à toutes les méthodes, tandis qu’après une méthode d’authentification, elle ne s’applique qu’à cette méthode. L’échéance est stockée et appliquée avec une précision à la seconde ; les intervalles inférieurs à la seconde (NANOSECOND, MICROSECOND, MILLISECOND) sont donc rejetés, et la plus petite unité acceptée est SECOND. Un intervalle négatif est accepté pour indiquer que les identifiants ont déjà expiré ; si l’échéance obtenue est antérieure à 1970-01-01 00:00:01 UTC, elle est normalisée à cet instant expiré minimal, que SHOW CREATE USER affiche ensuite dans le fuseau horaire du serveur ou de la session, comme décrit pour VALID UNTIL. Exemples :

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' — l’échéance au niveau de l’utilisateur s’applique aux deux méthodes.
CREATE USER name1 IDENTIFIED WITH plaintext_password BY 'no_expiration', bcrypt_password BY 'expiration_set' VALID FOR INTERVAL 30 DAY — l’échéance ne s’applique qu’à la méthode bcrypt_password ; plaintext_password n’expire jamais.

Clause GRANTS

Permet de limiter les droits d’accès disponibles pour une session authentifiée par une méthode d’authentification donnée. Elle accepte, entre parenthèses, une liste de privilèges sous la même forme que l’instruction GRANT. La clause est spécifiée après une méthode d’authentification (après sa clause VALID UNTIL, le cas échéant) et s’applique uniquement à cette méthode. Lorsqu’un utilisateur se connecte avec une telle méthode d’authentification, les droits d’accès de la session correspondent à l’intersection des droits d’accès de l’utilisateur (y compris ceux issus des rôles accordés) et des privilèges répertoriés dans la clause. La clause n’ajoute jamais de droits d’accès : si un privilège répertorié n’est pas accordé à l’utilisateur, la session ne le possède pas. Les sessions authentifiées avec une telle méthode ne peuvent pas non plus accorder de privilèges (l’option GRANT OPTION ne survit jamais à l’intersection) ni administrer des rôles. L’administration des rôles inclut non seulement leur création, modification, suppression, attribution et révocation, mais aussi la modification des rôles activés par défaut pour un utilisateur (SET DEFAULT ROLE et ALTER USER ... DEFAULT ROLE), qui est également refusée. EXECUTE AS change le principal de la session ; une instruction exécutée sous usurpation d’identité est donc limitée par l’intersection des droits d’accès de l’utilisateur cible et des privilèges répertoriés, plutôt que par les droits de l’utilisateur qui s’est connecté. Cette limite n’est jamais levée, et l’usurpation nécessite que IMPERSONATE ON target soit à la fois accordé à l’utilisateur et répertorié dans la clause ; ainsi, des identifiants limités ne peuvent jamais conférer davantage de droits que les identifiants illimités du même utilisateur. Cela offre un moyen pratique de créer des jetons pour les applications : des identifiants supplémentaires, assortis d’une date d’expiration et d’un ensemble limité de privilèges, liés à l’utilisateur — ils apparaissent dans system.query_log et system.processes sous le nom de l’utilisateur, cessent de fonctionner si l’utilisateur est supprimé et perdent leurs droits d’accès lorsque l’utilisateur les perd.

L’application est effectuée uniquement par l’initiateur. La limite GRANTS de la méthode d’authentification et son expiration VALID UNTIL sont appliquées uniquement sur le nœud qui reçoit la requête (l’initiateur). Elles ne sont pas propagées aux autres nœuds d’un cluster ; ne vous fiez donc pas à cette clause pour contraindre l’exécution à l’échelle du cluster. Les nœuds distants conservent leur périmètre habituel de rôles. La clause n’est pas non plus disponible dans users.xml. Le cache de résultats de requêtes est partagé par toutes les méthodes d’authentification d’un utilisateur : il isole les entrées par utilisateur et par rôles, et un résultat trouvé dans le cache n’est pas revérifié par rapport aux GRANTS de la méthode avec laquelle la session s’est connectée.

Exemples :

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)

Notez que la limite est une propriété de la méthode d’authentification, déterminée au moment de la connexion : modifier la clause avec ALTER USER affecte les nouvelles sessions, et non celles déjà établies. Les autorisations sur des sources filtrées telles que READ ON S3('s3://bucket/.*') ne sont pas encore prises en charge dans la clause : l’intersection compare un filtre source comme une chaîne opaque et ne peut pas restreindre un filtre à un autre. Une telle autorisation est donc rejetée plutôt que de n’accorder silencieusement aucun accès. La clause est prise en charge uniquement pour les méthodes d’authentification dont les identifiants sont vérifiés exclusivement localement par le serveur. Pour les méthodes dont la vérification contacte (ou, dans le cas de jwt, peut contacter — par exemple pour récupérer les clés de signature) un système externe (ldap, kerberos, http, jwt), la clause est rejetée : lorsque plusieurs méthodes d’authentification acceptent les mêmes identifiants, la limite est appliquée en revérifiant les identifiants avec les autres méthodes, et une interrogation supplémentaire d’un système externe n’est pas sûre ; une autre méthode acceptant les mêmes identifiants pourrait donc contourner la limite. Lorsque les mêmes identifiants effectifs sont acceptés par plusieurs méthodes d’authentification, la connexion est limitée de manière restrictive par toutes ces méthodes : la session obtient l’intersection des GRANTS de toutes les méthodes correspondantes et expire à la plus proche de leurs dates VALID UNTIL. La date VALID UNTIL la plus proche prévaut même lorsqu’elle est déjà passée — la connexion est rejetée, exactement comme si l’unique méthode correspondante avait expiré ; ainsi, l’expiration d’un jeton ne confère jamais silencieusement aux identifiants partagés les droits ou la durée de vie d’une méthode plus permissive. Cette combinaison n’est vérifiée que parmi les méthodes d’authentification validées localement par le serveur, pour la même raison que la clause elle-même est refusée pour une méthode validée par un système externe : revérifier les identifiants exigerait une interrogation supplémentaire non sûre du système externe. Ainsi, si les mêmes identifiants sont également acceptés par une méthode validée par un système externe (ldap, kerberos, http, jwt) pour le même utilisateur, le VALID UNTIL de cette méthode ne fait pas partie de la combinaison et une expiration antérieure configurée pour celle-ci ne raccourcit pas la session obtenue via la méthode validée localement.

Clause GRANTEES

Spécifie les utilisateurs ou les rôles autorisés à recevoir des privilèges de cet utilisateur, à condition que celui-ci dispose également de tous les droits d’accès requis avec GRANT OPTION. Options de la clause GRANTEES :

user — Spécifie un utilisateur auquel cet utilisateur peut accorder des privilèges.
role — Spécifie un rôle auquel cet utilisateur peut accorder des privilèges.
ANY — Cet utilisateur peut accorder des privilèges à n’importe qui. Il s’agit du paramètre par défaut.
NONE — Cet utilisateur ne peut accorder de privilèges à personne.

Vous pouvez exclure n’importe quel utilisateur ou rôle à l’aide de l’expression EXCEPT. Par exemple, CREATE USER user1 GRANTEES ANY EXCEPT user2. Cela signifie que si user1 s’est vu accorder certains privilèges avec GRANT OPTION, il pourra accorder ces privilèges à n’importe qui, sauf à user2.

Exemples

Créez le compte utilisateur mira, protégé par le mot de passe qwerty :

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

mira doit démarrer l’application cliente sur l’hôte où s’exécute le serveur ClickHouse. Créez le compte utilisateur john et attribuez-lui des rôles :

CREATE USER john ROLE role1, role2;

Créez le compte utilisateur john, attribuez-lui des rôles et définissez-en certains par défaut :

CREATE USER john ROLE role1, role2 DEFAULT ROLE role1;

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

Créez le compte utilisateur john et autorisez-le à accorder ses privilèges à l’utilisateur associé au compte jack :

CREATE USER john GRANTEES jack;

Utilisez un paramètre de requête pour créer le compte utilisateur john :

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

SQL Reference

Data Types

Engines

Functions

Formats

Interfaces

Settings

System Tables

Data Lakes

Identification

Exemples

Hôte de l’utilisateur

Clause VALID UNTIL

Clause VALID FOR

Clause GRANTS

Clause GRANTEES

Exemples

​Identification

​Exemples

​Hôte de l’utilisateur

​Clause VALID UNTIL

​Clause VALID FOR

​Clause GRANTS

​Clause GRANTEES

​Exemples

Identification

Exemples

Hôte de l’utilisateur

Clause VALID UNTIL

Clause VALID FOR

Clause GRANTS

Clause GRANTEES

Exemples