Run ClickHouse locally

The fastest way to learn ClickHouse is to run it on your own machine. Use an official package or the official container image. Don’t build from source, and don’t pull a random image somebody else published.

I use Docker for this. One command starts the server, one opens the client, and when I’m done I delete everything and my laptop is clean again.

Run a disposable server and connect with the native client:

docker run --rm -d --name clickhouse \
  -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-server
docker exec -it clickhouse clickhouse-client

Inside the client, run SELECT version() and create a separate practice database. Stop the container when finished. Do not publish the native or HTTP ports on an internet-facing host without authentication and network controls.

Let’s look at the flags. --rm deletes the container when it stops. -d runs it in the background. The two ports are the two ways to talk to ClickHouse. Port 8123 is the HTTP interface, used by most drivers and by curl. Port 9000 is the native protocol, used by clickhouse-client.

If you installed the native package instead, clickhouse-client is already on your PATH and connects the same way.

Check the server answers

The first query I run on any new server is the version check:

SELECT version();

You get one row with the version number, and the client prints how long the query took. A few milliseconds means the server is up.

Now create a practice database, so nothing lands in default:

CREATE DATABASE lab;
USE lab;

Every table in this course goes into lab. When an experiment goes wrong, DROP DATABASE lab resets everything in one statement.

Know how to remove it

Write down the exact command that removes the environment before you build anything on it. Mine is:

docker stop clickhouse

Because we started with --rm, stopping also deletes the container and everything inside it. If you want data to survive a restart, add a volume with -v clickhouse-data:/var/lib/clickhouse. For a lab, I prefer the disposable version.

One failure you might hit right away is port is already allocated. Something else on your machine is listening on 8123 or 9000. Map different host ports, for example -p 18123:8123 -p 19000:9000. The docker exec client connects inside the container, so it keeps working.

Keep it private

A fresh ClickHouse ships with a default user and, in many setups, no password. That’s fine when only your own terminal can reach it. It’s not fine on a server with a public IP. Keep the first server on the development machine.

When you don’t want to run servers at all, ClickHouse Cloud gives you a managed service. The SQL you learn here works the same way there.