Implementation:ClickHouse ClickHouse Clickhouse Client Interactive

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

Overview

Concrete tool for establishing an interactive SQL session with a running ClickHouse server, featuring line editing via `replxx`, command history, configurable output formats, and automatic dispatch from the multi-tool binary when connection arguments are detected.

Description

The `clickhouse client` command provides an interactive SQL terminal for querying a ClickHouse server. It is part of the unified ClickHouse multi-tool binary, dispatched through the `clickhouse_applications` table in `programs/main.cpp`.

Dispatch mechanism: The dispatch table at line 160 maps `"client"` to `mainEntryClickHouseClient`. Additionally, the auto-dispatch logic at lines 370-382 detects connection arguments (`--host`, `--port`, `-h`) when no explicit subcommand was matched, and automatically routes to the client entry point. This means `clickhouse --host myserver` is treated as `clickhouse client --host myserver`.

The auto-dispatch code:

// programs/main.cpp, lines 370-382
if (main_func == printHelpOnError && argv.size() >= 2)
{
    for (size_t i = 1, num_args = argv.size(); i < num_args; ++i)
    {
        if ((i + 1 < num_args && argv[i] == std::string_view("--host")) || startsWith(argv[i], "--host=")
            || (i + 1 < num_args && argv[i] == std::string_view("--port")) || startsWith(argv[i], "--port=")
            || startsWith(argv[i], "-h"))
        {
            main_func = mainEntryClickHouseClient;
            break;
        }
    }
}

Line editing: The client uses the `replxx` library for interactive terminal editing. The `replxx` dependency is linked via `base/base/CMakeLists.txt` (line 62). It provides multi-line editing, persistent history, syntax highlighting, and tab completion for an enhanced interactive experience.

Connection and authentication: The client connects to the server's native TCP protocol endpoint. Default connection parameters target `localhost:9000` with user `default` and no password. All connection parameters can be overridden via command-line flags.

Output formatting: In interactive mode, the default output format is `PrettyCompact`, which renders results as aligned, bordered tables. In non-interactive mode (piped input or `-q` flag), the default is `TabSeparated`. The `--format` flag overrides the default in either mode.

Usage

Use this tool for interactive query development, data exploration, schema management, health verification, scripted query execution, and any task requiring direct SQL interaction with a ClickHouse server.

Code Reference

Source Location

• Repository: ClickHouse
• File: programs/main.cpp (line 160: dispatch table entry `{"client", mainEntryClickHouseClient}`)
• File: programs/main.cpp (lines 370-382: auto-dispatch to client when `--host`/`--port` detected)
• File: base/base/CMakeLists.txt (line 62: `replxx` library linkage)

Signature

Command-line interface:

clickhouse client [--host HOST] [--port PORT] [--user USER] [--password PASS] [--database DB]
                  [-q QUERY] [--multiquery] [--format FORMAT]

Dispatch table entry (programs/main.cpp):

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

Short name alias:

std::pair<std::string_view, std::string_view> clickhouse_short_names[] =
{
    {"chl", "local"},
    {"chc", "client"},  // "chc" is a short alias for "client"
    // ...
};

I/O Contract

Inputs

Name	Type	Required	Description
Running ClickHouse server	Service	Yes	A ClickHouse server must be running and reachable at the specified host and port.
`--host`	String	No	Server hostname or IP address. Default: `localhost`.
`--port`	Integer	No	Native protocol TCP port. Default: `9000`.
`--user`	String	No	Authentication username. Default: `default`.
`--password`	String	No	Authentication password. Default: empty. If omitted and the server requires one, the client prompts interactively.
`--database`	String	No	Default database for unqualified table references. Default: `default`.
`-q` / `--query`	String	No	Single query to execute in non-interactive mode. If omitted, the client enters interactive REPL mode.
`--multiquery` / `-n`	Flag	No	Enable multi-query mode: multiple semicolon-delimited queries are read from stdin.
`--format`	String	No	Output format for query results. Default: `PrettyCompact` (interactive) or `TabSeparated` (non-interactive). Supports all ClickHouse formats: `JSON`, `CSV`, `TSV`, `Pretty`, `Vertical`, etc.

Outputs

Name	Type	Description
stdout	Formatted text	Query results in the configured format. In interactive mode, results are displayed after each query. In single-query mode, the result is printed once and the client exits.
stderr	Text	Error messages, connection diagnostics, and progress indicators.
Exit code	Integer	`0` on success, non-zero on error. In single-query mode, the exit code reflects whether the query succeeded.
History file	File	`replxx` saves command history to `~/.clickhouse-client-history` (or a configured location) for persistence across sessions.

Usage Examples

Start an interactive session on localhost:

clickhouse client
# Presents prompt:
# ClickHouse client version X.Y.Z.
# Connecting to localhost:9000 as user default.
# Connected to ClickHouse server version X.Y.Z.
#
# myhost :) SELECT 1
#
# ┌─1─┐
# │ 1 │
# └───┘

Connect to a remote server:

clickhouse client --host prod-server.example.com --port 9000 --user admin --password

Auto-dispatch (no explicit "client" subcommand):

# These are equivalent due to auto-dispatch at lines 370-382:
clickhouse --host prod-server.example.com
clickhouse client --host prod-server.example.com

Single-query mode with JSON output:

clickhouse client -q "SELECT database, name, engine FROM system.tables LIMIT 5" --format JSON

Multi-query mode from a file:

clickhouse client --multiquery < schema_migrations.sql

Using the short alias:

# "chc" is a short alias for "clickhouse client"
chc -q "SELECT version()"

Specifying a default database:

clickhouse client --database mydb -q "SELECT count() FROM events"

Related Pages

Implements Principle

• Principle:ClickHouse_ClickHouse_Interactive_Client_Connection