clickhouse-client

The interactive command-line client. Source lives in programs/client/ with the bulk of the protocol code in src/Client/. The clickhouse-client symlink is dispatched by programs/main.cpp.

Purpose

clickhouse-client connects to a server using ClickHouse's native binary protocol (default port 9000, or 9440 with TLS) and gives the user an interactive REPL with history, syntax highlighting, multi-line editing, query progress, profile events, and result formatting.

Source layout

Path	Purpose
programs/client/Client.cpp	Entry point. Inherits from ClientBase (src/Client/ClientBase.h).
programs/client/Client.h	Declarations.
programs/client/clickhouse-client.cpp	Tiny shim.
programs/client/clickhouse-client.xml	Default user config.
src/Client/ClientBase.cpp	Shared logic between client, local, and benchmark.
src/Client/Connection.cpp	Native protocol connection + Hello/Query/Data/Progress packets.
src/Client/QueryFuzzer.cpp	The query-mutation fuzzer driven by --query-fuzzer-runs.
src/Client/IServerConnection.h	Abstraction so clickhouse-local can run "queries" against the embedded engine through the same surface.
src/Client/Suggest.cpp	Tab completion using system.completions.

How it works

sequenceDiagram
    participant User
    participant Client as clickhouse-client
    participant Conn as Connection (native TCP)
    participant Server as clickhouse-server

    User->>Client: SQL line
    Client->>Conn: Hello (version, db, user)
    Conn->>Server: Hello
    Server-->>Conn: Hello + server version
    Client->>Conn: Query packet (formatted via Parsers)
    Conn->>Server: Query
    Server-->>Conn: Data packet (Block of columns)
    Conn-->>Client: Block stream
    Client->>User: render via OutputFormat (Pretty/TSV/JSON/...)
    Server-->>Conn: Progress / Profile / Logs / Totals / Extremes
    Server-->>Conn: EndOfStream

The native protocol is binary, columnar, and includes streaming progress messages and the server's log lines. ClientBase keeps the connection alive, multiplexes input handling with a progress indicator on the same TTY, and dispatches results to the right output Format.

Modes

• Interactive — REPL with replxx-based line editing, syntax highlighting (src/Client/InternalTextLogs.cpp), system.completions-driven tab completion, \ slash-commands.
• Non-interactive — clickhouse-client --query "..." or piped stdin. Output goes to stdout in the format selected via --format.
• Multi-query — --multiquery runs a stream of statements separated by ;.
• Server-side — used inside HTTP handlers and tests.

TLS, auth, and clusters

• TLS is enabled with --secure (port 9440 by default).
• Auth: password (--password), SSH key (--ssh-key-file against the ssh-keys user authentication mode), JWT, Kerberos, LDAP — handled by the server side (src/Access/Authentication.cpp).
• --host/--port can be repeated to fail over between replicas (MultiplexedConnections in src/Client/MultiplexedConnections.cpp).

Convenience features

• --time prints per-query elapsed time.
• --echo echoes statements before executing them (great in scripts).
• --progress controls the live progress bar.
• --queries-file reads a script file.
• --input_format_* / --output_format_* settings tune the formats.
• --copy / --testmode switches behaviour for replication tooling and tests.

Query fuzzer

clickhouse-client --query-fuzzer-runs=N "..." mutates the parsed AST through QueryFuzzer and re-runs it many times to surface invariants. CI uses this for regression hunting.

Entry points for modification

• To add a CLI flag: edit Client.cpp/ClientBase.cpp's argv parsing.
• To change the wire protocol or add a new packet type: see Connection.cpp and src/Server/TCPHandler.cpp. The protocol revision is bumped in src/Core/ProtocolDefines.h.
• To add an output format: implement an IOutputFormat under src/Processors/Formats/ and register it.

Related pages

• Server — the other side of the wire.
• Native TCP protocol
• Server protocols
• Local — same engine, no connection.