Server protocols

src/Server/ implements every wire protocol ClickHouse speaks. Each protocol gets its own handler, paired with a small protocol class. Listeners are wired up by programs/server/Server.cpp.

Catalog

Protocol	Handler	Default port	Notes
HTTP / HTTPS	HTTPHandler.cpp	8123 / 8443	The most popular interface. Supports ?query=, body queries, multipart, sessions, Prometheus exposition, replicated-status, embedded UIs (/play, /dashboard).
Native TCP / TLS	TCPHandler.cpp	9000 / 9440	Binary, columnar, streaming. The fastest path. See Native TCP.
Interserver HTTP	InterserverIOHTTPHandler.cpp	9009	Carries part fetches between replicas (DataPartsExchange.cpp) and DDL coordination.
MySQL wire	MySQLHandler.cpp	9004	Lets MySQL clients connect. Translates statements through a MySQL-flavoured parser (src/Parsers/MySQL/).
PostgreSQL wire	PostgreSQLHandler.cpp	9005	Same idea for psql/libpq clients.
gRPC	GRPCServer.cpp	9100	Protobuf-defined query API. Schema in src/Server/grpc_protos/clickhouse_grpc.proto.
ArrowFlight	ArrowFlightHandler.cpp	9006	Apache Arrow Flight RPC. Streams RecordBatch data.
Prometheus	PrometheusMetricsWriter.cpp	9363	Plain-text metrics exposition.
Replicas Status	ReplicasStatusHandler.cpp	8123 (path)	Health endpoint reporting per-replica delays.
Static / play / dashboard	WebUIRequestHandler.cpp, StaticRequestHandler.cpp	8123 (paths)	Serves the embedded HTML SPAs.
Keeper TCP	KeeperTCPHandler.cpp (in src/Coordination/)	9181	The ZooKeeper wire protocol.

HTTP handler

HTTPHandler.cpp is the busy one. It:

• Parses query parameters (query=, database=, default_format=, settings) and HTTP body.
• Authenticates via Authorization, X-ClickHouse-User/X-ClickHouse-Key, or basic auth.
• Builds a Context per request.
• Streams the response in the requested format (?default_format=Parquet).
• Supports HTTP sessions (session_id parameter) so consecutive requests share state.
• Honours timeouts, decompression of the request body (gzip, zstd, br), and compression of the response.
• Routes special URIs:
  • /, /?query=... — generic query endpoint.
  • /ping, /replicas_status — health.
  • /play, /dashboard, /binary, /merges, /jemalloc — static UIs.
  • /metrics — Prometheus.
  • /?param_<name>=<value> — parameterised queries.

The handler factory is HTTPRequestHandlerFactoryMain.cpp, which composes routes and middleware (CORS, decompression, request logging).

Native TCP

TCPHandler.cpp implements the binary protocol shared by clickhouse-client, JDBC/ODBC, and language drivers. Packets:

• Hello (handshake with version + db + user).
• Query (text query + settings + client info + parameters).
• Data (a Block of rows; sent both ways).
• Progress (rows/bytes processed; sent server → client).
• ProfileInfo (final profile counters).
• Totals, Extremes (for WITH TOTALS/extremes).
• Log (server log lines).
• EndOfStream, Exception, Cancel, Pong, TablesStatus.

The protocol revision is bumped in src/Core/ProtocolDefines.h and tracked per-feature for backward compatibility.

InterserverIOHTTP

InterserverIOHTTPHandler.cpp is the HTTP service for replication:

• GET /?endpoint=DataPartsExchange:... — fetch a part from a peer.
• GET /?endpoint=PartialPathExchange:... — fetch only required files.
• DDL queue progress.

Auth between cluster nodes uses a shared interserver password configured under <interserver_http_credentials>.

gRPC

grpc_protos/clickhouse_grpc.proto declares the schema. A single bidirectional ExecuteQuery RPC streams query result blocks alongside log events and progress messages. The handler is GRPCServer.cpp. The reference Python client is in utils/grpc-client/.

ArrowFlight

ArrowFlightHandler.cpp exposes a regular ClickHouse server as an Arrow Flight endpoint. Useful for analytics tools (Polars, DuckDB, Spark) that prefer Arrow Flight as a source.

MySQL and Postgres

These handlers translate the wire protocols into ClickHouse's internal representation. Most queries pass through; some statements (SHOW TABLES, DESCRIBE, SET, EXPLAIN) are mapped to ClickHouse equivalents. Non-trivial parts:

• The MySQL handler implements MySQL's authentication (mysql_native_password, caching_sha2_password).
• The Postgres handler maps types per the Postgres wire protocol.
• Both handlers can be disabled in production deployments that don't need them.

Listener wiring

Server::main (in programs/server/Server.cpp) opens sockets for every enabled protocol, attaches the handler factory, and registers the listener with the global thread pool. <listen_host>, <tcp_port>, <http_port>, <mysql_port>, etc. control which ports bind.

TLS

OpenSSL is initialized in programs/main.cpp via OpenSSLInitializer. Certificate/key paths come from <openSSL> in the config. TLS variants (HTTPS, secure native, mTLS) share the same certificate chain.

Entry points for modification

• New protocol → add a handler under src/Server/, register it in Server.cpp's listener loop, expose options in <protocols> of config.xml.
• New native packet type → bump ProtocolDefines.h, handle it in TCPHandler.cpp and the matching client (src/Client/Connection.cpp).
• New HTTP route → extend HTTPRequestHandlerFactoryMain.cpp.

Related pages

• Server — bootstraps the listeners.
• Client — talks the native TCP protocol.
• API → HTTP interface, API → Native TCP
• Access control — authentication runs here.