Course Overview
Clickhouse For Data Engineers

Administering Clickhouse Users and Roles

Lesson #4

In this lesson we will:

  • Learn About The Clickhouse Role Based Access Control (RBAC) model;
  • Go through the process of creating users, roles and priviledges.

Role Based Access Control

The Clickhouse security model is based on Role Based Access Control (RBAC). This is a common model for controlling access to data, and is used in both applications and databases including Clickhouse.

It involves giving users one or more roles (such as manager, call handler, CEO or salesperson), and then granting privileges to those roles such as the ability to see or modify certain tables or rows. A user can have many roles, and a role can have many users.

In this lesson we will learn more about this model and demonstrate how to administer it in Clickhouse.

XML vs SQL configuration

Note that there are two models for administering RBAC in Clickhouse.

The legacy route was by changing permissions statically in XML files. The newer, reccomended route is to use SQL commands to administer them via the client.

We will use the latter option in this lesson.

Enabling User Creation Via SQL

There is however one situation where we need to the xml file when bootstrapping our new instance.

Having start Clickhouse, let's try to create a new user with a static password:

create user if not exists benjaminwootton identified with plaintext_password by 'password321';

If you try to execute this command, you will find that the default user is not able to administer users on a new install of Clickhouse using the SQL route. It has to be explicitly enabled.

Code: 497. DB::Exception: Received from localhost:9000. DB::Exception: default: Not enough privileges. To execute this query it's necessary to have grant CREATE USER ON *.*. (ACCESS_DENIED)

The way to enable this is using the Clickhouse users.xml file. Once this has been turned on in the XML file, we can grant the permission to create users to other users in the system via SQL. This is purely a security feature when bootstrapping a new Clickhouse server.

We can edit the users.xml file in the following location:

nano /etc/clickhouse-server/users.xml

And uncomment the line regarding access_management:


Uncommenting and setting this flag to 1 effectively says that the default user has permission to create new users and grant permissions to them.

We can then restart the Clickhouse server, being careful to reference the main configuration file, which in turn will reference the users.xml file we have just edited:

clickhouse-server -C /etc/clickhouse-server/config.xml

If we then attempt to recreate our user from the Clickhouse client:

create user if not exists benjaminwootton identified with plaintext_password by 'password321';

We should see that it has been succesfully created:

CREATE USER IF NOT EXISTS benjaminwootton IDENTIFIED WITH plaintext_password BY 'password321'

Query id: b19e48ab-f7bd-48bf-a313-e0eec6b22a0c


0 rows in set. Elapsed: 0.004 sec.

The new user, in this case benjaminwootton will then be able to login at the client with the credentials specified.

Administering Roles

As discussed above, the Clickhouse access management model is based on roles.

For example, say we have two roles SALESPERSON and SALESMANAGER. These may have a different set of read and write permissions.


  • Can read customers
  • Can write to sales


  • Can write to customers
  • Can write to sales
  • Can read employees

Roles are created through SQL:

create role if not exists salesperson;
create role if not exists salesmanager;

We can then assign permissions to our newly created roles:

grant select on db.customers TO salesperson;
grant insert, select on db.sales TO salesperson;

grant insert on db.customers TO salesmanager;
grant insert on db.sales TO salesmanager;
grant select on db.employees to salesmanager;

Assigning Roles To Users

The next step is to assign the newly created roles to our user:

grant salesmanager to benjaminwootton;

Roles can also be assigned to users at creation time like so:

create user if not exists martinjones 
identified with plaintext_password by 'password321' 
default role salesperson 


The final component of the RBAC model is privileges, describing a permission to execute certain types of queries over certain database objects.

For instance, in the following query, we are stating that any users with the sales manager role, should be able to select the order_id and the pizza_type columns from the pizza_orders table.

grant select(order_id,pizza_type) ON db.pizza_orders 
to salesmanager with grant option

In the example above, we granted permissions to roles. This is best practice, and the most maintinable option. In similar deployments, we may prefer to grant privileges directly to users, which is also supported by Clickhouse:

grant select(order_id,pizza_type) ON db.pizza_orders 
to benjaminwootton with grant option


The WITH GRANT OPTION clauses means that the user we grant the permission to, in turn has access to grant the same permission to other users. In the instance above, we may be comfortable with letting our salesmanager devolve permissions to read data to their employees, but this may not be something we would be comfortable with salespeople being able to do. The specific configuration will depend on your organisational security model.

Restriction By IP Address

It is possible to limit the IP addresses from which users can connect. This can also be specified at user creation time:

create user if not exists benjaminwootton_ip_restricted 
identified with plaintext_password by 'password321' host ip '';

Row Policies

As well as limiting data acess by columns, it is also possible to limit the data which users can see in a more granular way by rows. This can be done with ROW POLICY objects, which accept a SQL query stating which rows given users or roles can access:

create row policy low_value_orders_policy on
mydb.pizza_orders USING pizza_value < 1000 TO salesperson
Next Lesson:

Table Engines

In this lesson we will learn about the Clickhouse table engines which are used behind the scenes to store and manage your data. We will also introduce the main families of table engine.

0h 10m

Continuous Delivery For Data Engineers

This site has been developed by the team behind Timeflow, an Open Source CI/CD platform designed for Data Engineers who use dbt as part of the Modern Data Stack. Our platform helps Data Engineers improve the quality, reliability and speed of their data transformation pipelines.

Join our mailing list for our latest insights on Data Engineering:

Timeflow Academy is the leading online, hands-on platform for learning about Data Engineering using the Modern Data Stack. Bought to you by Timeflow CI

© 2023 Timeflow Academy. All rights reserved