Installation & Setup

Get ClickHouse running on your machine in under 5 minutes. We'll cover Docker, native install, and the clickhouse-client CLI.

🐳 Method 1: Docker (Recommended)

Docker is the fastest way to get ClickHouse running. One command and you're done.

🧒 ELI5: What is Docker?

Think of Docker like a lunchbox. Instead of bringing all the ingredients and cooking at school, someone packs a ready-made meal in a box. Docker "packs" ClickHouse with everything it needs into a container. You just open the box and eat!

Install Docker

Download Docker Desktop from docker.com. Install it and make sure it's running (you'll see a whale icon in your taskbar).

Pull & Run ClickHouse

# Pull the official ClickHouse image
docker pull clickhouse/clickhouse-server

# Run ClickHouse with persistent storage
docker run -d \
  --name clickhouse-server \
  -p 8123:8123 \
  -p 9000:9000 \
  -v clickhouse-data:/var/lib/clickhouse \
  -v clickhouse-logs:/var/log/clickhouse-server \
  clickhouse/clickhouse-server

Port 8123 = HTTP interface (for web tools) | Port 9000 = Native TCP (for clickhouse-client)

Connect with CLI

# Open the ClickHouse client inside the container
docker exec -it clickhouse-server clickhouse-client

# You should see:
# ClickHouse client version 24.x.x
# Connecting to localhost:9000
# Connected to ClickHouse server
# :)

That smiley face :) is the ClickHouse prompt. You're in!

Test It Works

SELECT 'Hello, ClickHouse!' AS greeting;

-- Output:
-- ┌─greeting───────────┐
-- │ Hello, ClickHouse!  │
-- └────────────────────┘

💻 Method 2: Native Install (Ubuntu/Debian)

# Add ClickHouse repository
sudo apt-get install -y apt-transport-https ca-certificates dirmngr
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754

echo "deb https://packages.clickhouse.com/deb stable main" | \
  sudo tee /etc/apt/sources.list.d/clickhouse.list

# Install ClickHouse
sudo apt-get update
sudo apt-get install -y clickhouse-server clickhouse-client

# Start the server
sudo service clickhouse-server start

# Connect
clickhouse-client

🍎 Method 3: macOS

# Using Homebrew
brew install clickhouse

# Start server
clickhouse server

# In another terminal, connect
clickhouse client

💡 Pro Tip: ClickHouse Cloud

Don't want to install anything? Use ClickHouse Cloud at clickhouse.cloud. Free tier includes 10GB storage and is perfect for learning. Just sign up and start querying!

🖥️ GUI Tools

The CLI is great, but sometimes you want a visual interface. Here are the best options:

1. Built-in Play UI

Open http://localhost:8123/play in your browser. It's a simple SQL editor built into ClickHouse itself!

2. DBeaver

Free, open-source database tool. Supports ClickHouse natively. Download from dbeaver.io.

3. Tabix

Web-based ClickHouse GUI. Visit tabix.io and connect to your local instance.

🌍 Real World

Most ClickHouse teams use a combination: CLI for quick queries, DBeaver for exploration, and Grafana/Metabase for dashboards connected to ClickHouse.

⚙️ Configuration Basics

ClickHouse has two main config files:

# Server config (ports, memory, storage)
/etc/clickhouse-server/config.xml

# User config (authentication, quotas)
/etc/clickhouse-server/users.xml

⚠️ Important Settings for Learning

For now, the defaults are perfect. Don't change anything yet. We'll dive into configuration in the Production lesson.

🎯 Your First Real Query

Let's load some sample data and run a real analytics query:

-- Create a sample table
CREATE TABLE hits (
    timestamp DateTime,
    url String,
    country String,
    browser String,
    response_time UInt32
) ENGINE = MergeTree()
ORDER BY timestamp;

-- Insert 1 million random rows
INSERT INTO hits
SELECT
    now() - toIntervalSecond(rand() % 86400),
    arrayElement(['/home', '/about', '/products', '/cart'], (rand() % 4) + 1),
    arrayElement(['US', 'UK', 'IN', 'DE', 'JP'], (rand() % 5) + 1),
    arrayElement(['Chrome', 'Firefox', 'Safari'], (rand() % 3) + 1),
    rand() % 5000
FROM numbers(1000000);

-- Analytics query: Top countries by avg response time
SELECT
    country,
    count() AS total_hits,
    round(avg(response_time), 2) AS avg_response_ms,
    quantile(0.95)(response_time) AS p95_response_ms
FROM hits
GROUP BY country
ORDER BY total_hits DESC;

⚡ Speed Check

That query just analyzed 1 million rows in under 50 milliseconds. On PostgreSQL, the same query would take 2-5 seconds. That's the ClickHouse difference!

Meet ClickHouse Architecture Deep Dive

October 2026 practice

Checked against the ClickHouse documentation in October 2026. The JSON type has been production-ready since version 25.3. ClickHouse Cloud rewrites a MergeTree create onto the matching SharedMergeTree engine.

A laptop can run clickhouse-server locally. A shared cluster needs replicas, a Keeper ensemble, disks you can back up, and TLS. Do not point a production server at the default user with an empty password. ClickHouse Cloud is a service: you do not install Keeper yourself there.

clickhouse-client --query 'SELECT version()'