Client library

src/Client/ is the shared C++ library used by clickhouse-client, clickhouse-local, clickhouse-benchmark, and the in-process server-to-server client. It also implements the user-facing terminal experience: prompts, history, syntax highlighting, output formatting, progress bars.

For the binary, see Apps → Client.

Roles

• Wire protocol client. Connection.cpp, MultiplexedConnections.cpp, IServerConnection.h, LocalConnection.cpp. Speaks the native TCP protocol (and an in-process variant for clickhouse-local).
• Interactive shell. ClientBase.cpp, ClientApplicationBase.cpp, LineReader.cpp, ReplxxLineReader.cpp, Suggest.cpp. Handles history, multi-line edits, tab completion (against system.completions), syntax highlighting.
• Output rendering. Plumbing into src/Processors/Formats/ to render results in the requested format.
• Failover and load balancing. ConnectionPool.cpp, ConnectionPoolWithFailover.cpp, HedgedConnectionsFactory.cpp, HedgedConnections.cpp.
• Client-side query fuzzer. QueryFuzzer.cpp.

Connection lifecycle

sequenceDiagram
    participant App as Client app
    participant ConnFactory as ConnectionPool
    participant Conn as Connection
    participant Server as TCPHandler

    App->>ConnFactory: get(host, port, ...)
    ConnFactory-->>App: Connection
    App->>Conn: sendHello(database, user, password)
    Conn->>Server: Hello
    Server-->>Conn: Hello + version
    App->>Conn: sendQuery(text, settings, ...)
    Conn->>Server: Query
    Server-->>Conn: Data, Progress, Totals, Logs
    Conn-->>App: Block stream
    Server-->>Conn: EndOfStream
    App->>Conn: poolReturn()

Connection is a single TCP socket plus protocol state. ConnectionPool keeps idle connections to one host. ConnectionPoolWithFailover extends that to multiple hosts with health checking and ranking. HedgedConnections issues a query to several replicas and picks the fastest responder.

Multi-connection patterns

• MultiplexedConnections — fans a single query over connections to multiple shards (used by Distributed).
• HedgedConnections — speculative replica execution.
• ConnectionEstablisher — non-blocking connect (lets HedgedConnections race many connects in parallel).

Local connection

LocalConnection.cpp is a fake IServerConnection that drives the engine in the same process. clickhouse-local and clickhouse-server-side system.tables reads use it to share the same client surface as the network case.

Suggestions

Suggest.cpp powers tab completion. It runs a one-shot query against system.completions (a virtual table that aggregates keywords, table names, column names, function names, and macro values) and stores the result as a sorted set used by replxx.

Output formats

After the server sends data, the client picks an IOutputFormat from src/Processors/Formats/ (PrettyCompact, JSONEachRow, CSV, TSV, Native, Parquet, Arrow, …). The client doesn't know about formats directly; it constructs the format and feeds it Blocks.

Settings and history

ClientBase supports per-user history (~/.clickhouse-client-history by default), command-line flags, and ~/.clickhouse-client/config.xml. The fuzzer flag (--query-fuzzer-runs) is implemented here too.

Internals worth knowing

• The native protocol is versioned, with feature-flag negotiation. New features ship behind a revision bump in src/Core/ProtocolDefines.h and degraded behaviour for older peers.
• The client can act as a proxy for multiple servers (e.g. when reading from a Distributed table); MultiplexedConnections handles the streaming join.
• InternalTextLogs.cpp formats the server log lines streamed inside the protocol so they appear inline in the client.

Related pages

• Apps → Client
• Apps → Local
• Server protocols
• API → Native TCP