Native TCP

The native TCP protocol is ClickHouse's own binary, columnar, streaming protocol. Default ports: 9000 (plain) and 9440 (TLS). Implementation: src/Server/TCPHandler.cpp (server) and src/Client/Connection.cpp (client).

It is the fastest and richest interface — the format is Native (whole Blocks on the wire), there are dedicated packet types for progress, profile, totals, extremes, and server log streaming, and it preserves rich error information.

Packets

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: Hello (revision, db, user, pass, OS info, client name/version)
    S-->>C: Hello (revision, server name/version, timezone, display name)
    C->>S: Query (id, info, settings, parameters, stage, secret, body)
    C->>S: Data (input)
    Note over S: Run query
    S-->>C: TableColumns (header)
    S-->>C: Data (output Block)
    S-->>C: Progress
    S-->>C: ProfileInfo
    S-->>C: ProfileEvents
    S-->>C: Logs (forwarded server log lines)
    S-->>C: Totals / Extremes (optional)
    S-->>C: EndOfStream

Other packet types: Cancel, Pong, Exception, TablesStatusRequest/Response, KeepAlive, ProfileEventsForwarded. The full list is enumerated in src/Core/Protocol.h.

Revision and feature flags

src/Core/ProtocolDefines.h carries the protocol revision and the feature-flag constants:

#define DBMS_TCP_PROTOCOL_VERSION 54501
#define DBMS_MIN_REVISION_WITH_PARALLEL_REPLICAS 54453
#define DBMS_MIN_REVISION_WITH_QUERY_PARAMETERS 54430
// ...

A new feature requires bumping the revision and gating the wire-format change behind a MIN_REVISION_WITH_* constant. Both the client and the server use these constants when emitting/parsing fields, which keeps the protocol forward- and backward-compatible.

Compression

network_compression_method (LZ4 default, ZSTD optional) compresses every Data packet. Headers and control packets are uncompressed.

Authentication

The Hello packet carries database, user, password. The handshake supports:

• Plain user + password.
• Server-provided salt for SHA256 / double SHA1 schemes.
• JWT (recent feature, behind a revision flag).
• Kerberos (GSSAPI sub-handshake).
• SSH key (signed challenge).
• mTLS at the TLS layer (port 9440).

See Access control.

Streaming inserts

INSERT INTO t FORMAT Native is followed by zero or more Data packets containing input blocks. Each block is one Native-format unit. Empty Data ends the stream.

Cancellation

Either side can send Cancel. The server stops the pipeline at the next safe boundary and returns EndOfStream (or Exception if the cancel was due to an error).

Multiplexed and hedged connections

MultiplexedConnections and HedgedConnections (in src/Client/) coordinate multiple native TCP sockets to drive Distributed reads or hedged-replica reads.

Tools that speak native TCP

• clickhouse-client (the CLI).
• The clickhouse-jdbc and clickhouse-go drivers (and many community drivers).
• ClickHouse server-to-server (InterserverIOHTTPHandler.cpp is HTTP, but server-side reads from peer replicas typically flow over native TCP).

Related pages

• Server protocols — full listing of every server-side handler.
• Client library — the C++ client implementation.
• Apps → Client — the user-facing CLI.