Implementation:ClickHouse ClickHouse Clickhouse Client Health Check

Knowledge Sources	ClickHouse
Domains	Deployment
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for verifying ClickHouse server health by executing `clickhouse client -q "SELECT 1"`, which connects to the server, runs a minimal query, and outputs `1` on success.

Description

The `clickhouse client` command is part of the unified ClickHouse multi-tool binary. In `programs/main.cpp`, the dispatch table at line 160 maps the `"client"` subcommand to the `mainEntryClickHouseClient` entry point function. When invoked with the `-q` (or `--query`) flag, the client operates in single-query mode: it establishes a connection to the server, sends the provided SQL, reads the result, prints it to stdout, and exits.

The health check `clickhouse client -q "SELECT 1"` is the canonical way to verify that a ClickHouse server is accepting connections and processing queries. On success, it prints `1` to stdout and exits with code 0. On failure (connection refused, authentication error, server not ready), it prints an error message to stderr and exits with a non-zero code.

The client binary can be invoked in multiple equivalent ways due to the multi-tool dispatch logic:

• `clickhouse-client -q "SELECT 1"` (via symlink)
• `clickhouse client -q "SELECT 1"` (via subcommand)
• `clickhouse --client -q "SELECT 1"` (via `--` prefixed subcommand)

All forms dispatch to the same `mainEntryClickHouseClient` function through the `isClickhouseApp` matching logic in `programs/main.cpp`.

Usage

Use this health check command immediately after starting the ClickHouse server to confirm it is operational. It is suitable for deployment scripts, container health probes, monitoring agents, and manual verification.

Code Reference

Source Location

• Repository: ClickHouse
• File: programs/main.cpp (line 160: client entry in dispatch table as `mainEntryClickHouseClient`)
• Dispatch table: programs/main.cpp lines 157-206 (`clickhouse_applications` array)

Signature

Dispatch table entry:

// programs/main.cpp, line 160
std::pair<std::string_view, MainFunc> clickhouse_applications[] =
{
    {"local", mainEntryClickHouseLocal},
    {"client", mainEntryClickHouseClient},  // <-- client entry point
    // ...
};

Command-line invocation:

clickhouse client -q "SELECT 1"

I/O Contract

Inputs

Name	Type	Required	Description
Running ClickHouse server	Service	Yes	A ClickHouse server must be running and listening on the target host and port. Default: `localhost:9000`.
`-q "SELECT 1"`	Command-line argument	Yes	The `-q` flag specifies a single query to execute in non-interactive mode. `"SELECT 1"` is the minimal valid query for health checking.
`--host`	Command-line argument	No	Target server hostname. Default: `localhost`.
`--port`	Command-line argument	No	Target server native protocol port. Default: `9000`.
`--user`	Command-line argument	No	Authentication username. Default: `default`.
`--password`	Command-line argument	No	Authentication password. Default: empty string.

Outputs

Name	Type	Description
stdout	Text	On success: `1` (the result of `SELECT 1`), followed by a newline.
stderr	Text	On failure: an error message describing the connection or query failure.
Exit code	Integer	`0` on success, non-zero on failure. Can be used directly in shell conditionals.

Usage Examples

Basic health check:

clickhouse client -q "SELECT 1"
# Output: 1

Health check with explicit host and port:

clickhouse client --host 127.0.0.1 --port 9000 -q "SELECT 1"

Scripted health check in a deployment script:

#!/bin/bash
sudo systemctl start clickhouse-server

# Wait for server to become ready (up to 60 seconds)
for i in $(seq 1 60); do
    if clickhouse client -q "SELECT 1" > /dev/null 2>&1; then
        echo "ClickHouse server is ready."
        break
    fi
    echo "Waiting for ClickHouse server... ($i/60)"
    sleep 1
done

Kubernetes readiness probe:

readinessProbe:
  exec:
    command:
      - clickhouse
      - client
      - -q
      - "SELECT 1"
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3

Docker health check:

HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
  CMD clickhouse client -q "SELECT 1" || exit 1

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Server_Health_Verification

Requires Environment

• Environment:ClickHouse_ClickHouse_OpenSSL_Runtime