Tcp

Native protocol examples

These examples use ClickHouseTcpClient and ClickHouse's native TCP protocol. The HTTP examples use ClickHouseClient or ClickHouseConnection instead. See the example index to choose and run an example.

Before you start

The native protocol normally listens on port 9000. Port 8123 is for HTTP.

docker run -d --name clickhouse-server -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-server
dotnet run -- --tcp

The native client API is experimental. Its main client, data source, session, operations interfaces, and dependency-injection extensions produce warning CHTCP0001. This project acknowledges the warning globally. In another project, add this setting while you evaluate the API:

<NoWarn>$(NoWarn);CHTCP0001</NoWarn>

Choose the right transport

The native client provides:

• columnar block reads through StreamAsync;
• pinned sessions through OpenSessionAsync;
• insert-block and query progress, profile info, server log and profile-event blocks, totals, and extremes callbacks;
• native block compression and QBit plane access;
• W3C trace context propagation to ClickHouse.

Use the HTTP client when you need:

• ADO.NET or an ORM;
• CSV, JSONEachRow, Parquet, or raw stream input and output;
• bearer authentication or custom HTTP headers;
• custom parameter type resolution, parameter formatting, or read conversion;
• a per-query database or role.

One type detail is easy to miss: row reads return DateTime, DateTime64, Time, and Time64 as their wire integer values. QueryAsync<T> converts mapped POCO properties. On the block tier, Block.Column<T> is a cast to the type the column decoded to, while Block.ReadAs<T> converts to any other type the ClickHouse type offers, and IDateTimeColumn and ITimeColumn convert per row. ClickHouseTcpTypes.CanRead and CanWrite answer which CLR types a given ClickHouse type accepts.