Running ClickHouse with Docker: Part 1

Introduction

ClickHouse has a Client-Server model and running the ClickHouse server using docker should be fairly straightforward. Official docker images from the ClickHouse team are available in the docker hub. This article is intended to be a gentle introduction to running ClickHouse in docker. The next part of this article will have more advanced options and concepts covered.

Pre-requisites

  • Good to have a working knowledge of Docker and Docker compose
  • Basic Linux commands
  • Docker and Docker compose installed

Getting Started with ClickHouse using Docker

We have used Ubuntu 22.04 for this tutorial. Let us get started without further ado. Run the following command in the terminal to fire up the ClickHouse docker container.

sudo docker run -d --name docker_sandbox -d clickhouse/clickhouse-server:latest
  1. -d – runs the container in the detached mode (background)
  2. –name – the name of the container
  3. clickhouse/clickhouse-server – image name in the docker hub
  4. the latest – latest version of the image from the docker hub

To execute bash commands inside a container (since the container is based on Ubuntu or other Linux-based OS), we have to run the container in interactive mode. We can run the container in interactive mode using the running container’s ID. Get the container ID using the following command.

sudo docker container ls

The sample output is below.

CONTAINER ID   IMAGE                                 COMMAND            CREATED          STATUS          PORTS                          NAMES
3c4829b4b56a   clickhouse/clickhouse-server:latest   "/entrypoint.sh"   42 minutes ago   Up 42 minutes   8123/tcp, 9000/tcp, 9009/tcp   docker_sandbox

3c4829b4b56a is the container ID. Use this information in the exec command to run in interactive mode. It is sufficient to use the first three or four alphanumeric characters from the ID.

sudo docker exec -it 3c4 bash

This should open up the container’s shell as the root user.

root@3c4829b4b56a:/#

Now let us run the ClickHouse client inside the container. by typing clickhouse-client in the terminal.

clickhouse-client

The client will display similar information (which could vary with different versions) as below.

ClickHouse client version 22.6.3.35 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 22.6.3 revision 54455.

3c4829b4b56a :) 

Let us play around with some ClickHouse SQL. Use the SQL statement below to list the databases available in ClickHouse.

SHOW DATABASES

Query id: a23c2cb0-873c-462e-86dd-497ca0c98e37

┌─name───────────────┐
│ INFORMATION_SCHEMA │
│ default            │
│ information_schema │
│ system             │
└────────────────────┘

4 rows in set. Elapsed: 0.002 sec.

List the tables in the system database using the following SQL statement.

SHOW TABLES FROM system;

The client will display a long list of tables in a system database.

SHOW TABLES FROM system

Query id: 2f5fcc6c-48f1-4283-b225-b9d0c2cbb7f0

┌─name───────────────────────────┐
│ aggregate_function_combinators │
│ asynchronous_inserts           │
│ asynchronous_metric_log        │
│ asynchronous_metrics           │
│ backups                        │
│ build_options                  │
│ certificates                   │
│ clusters                       │
│ collations                     │
│ columns                        │
│ contributors                   │
│ current_roles                  │
│ data_skipping_indices          │
│ data_type_families             │
│ databases                      │
│ detached_parts                 │
│ dictionaries                   │
│ disks                          │
│ distributed_ddl_queue          │
│ distribution_queue             │
│ enabled_roles                  │
│ errors                         │
│ events                         │
│ filesystem_cache               │
│ formats                        │
│ functions                      │
│ grants                         │
│ graphite_retentions            │
│ licenses                       │
│ macros                         │
│ merge_tree_metadata_cache      │
│ merge_tree_settings            │
│ merges                         │
│ metric_log                     │
│ metrics                        │
│ models                         │
│ mutations                      │
│ numbers                        │
│ numbers_mt                     │
│ one                            │
│ part_moves_between_shards      │
│ parts                          │
│ parts_columns                  │
│ privileges                     │
│ processes                      │
│ projection_parts               │
│ projection_parts_columns       │
│ query_log                      │
│ quota_limits                   │
│ quota_usage                    │
│ quotas                         │
│ quotas_usage                   │
│ remote_data_paths              │
│ replicas                       │
│ replicated_fetches             │
│ replicated_merge_tree_settings │
│ replication_queue              │
│ rocksdb                        │
│ role_grants                    │
│ roles                          │
│ row_policies                   │
│ settings                       │
│ settings_profile_elements      │
│ settings_profiles              │
│ stack_trace                    │
│ storage_policies               │
│ table_engines                  │
│ table_functions                │
│ tables                         │
│ time_zones                     │
│ trace_log                      │
│ user_directories               │
│ users                          │
│ warnings                       │
│ zeros                          │
│ zeros_mt                       │
└────────────────────────────────┘

76 rows in set. Elapsed: 0.003 sec. 

Query the functions table in the system database using the following SQL and list the first 10 rows.

SELECT *
FROM system.functions
LIMIT 10

Query id: 2c3788bf-26c6-45e8-8908-ea1790355b6e

┌─name──────────────┬─is_aggregate─┬─case_insensitive─┬─alias_to─┬─create_query─┬─origin─┐
│ hashid            │            0 │                0 │          │              │ System │
│ logTrace          │            0 │                0 │          │              │ System │
│ showCertificate   │            0 │                0 │          │              │ System │
│ aes_decrypt_mysql │            0 │                0 │          │              │ System │
│ aes_encrypt_mysql │            0 │                0 │          │              │ System │
│ decrypt           │            0 │                0 │          │              │ System │
│ encrypt           │            0 │                0 │          │              │ System │
│ meiliMatch        │            0 │                0 │          │              │ System │
│ toBool            │            0 │                0 │          │              │ System │
│ windowID          │            0 │                0 │          │              │ System │
└───────────────────┴──────────────┴──────────────────┴──────────┴──────────────┴────────┘

10 rows in set. Elapsed: 0.002 sec. Processed 1.25 thousand rows, 55.35 KB (503.47 thousand rows/s., 22.31 MB/s.)

Kudos! We have a working ClickHouse server running a container. We shall look at slightly advanced topics such as opening up the port, mounting the data directory inside the container etc in the next part of the tutorial.

Conclusion

To learn more about how to get started with ClickHouse, read the following articles:

References: