> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> The official C# client for connecting to ClickHouse over the native TCP protocol.
# ClickHouse C# native TCP client
Experimental status
The native TCP client API is experimental. Its public surface may change in a future release.
The main client, data source, session, operations interfaces, and dependency-injection extensions
produce compiler warning `CHTCP0001`. To acknowledge the warning while evaluating the API, add it
to `NoWarn` in your project file:
```xml theme={null}
$(NoWarn);CHTCP0001
```
Suppress the warning only after accepting that code using the API may need changes in a future
release.
Supported .NET versions
The native TCP client supports the following .NET versions:
* .NET 8.0
* .NET 9.0
* .NET 10.0
Supported ClickHouse versions
The TCP client officially supports the last 2 LTS versions, as well as the last 3 releases of the ClickHouse server.
Installation
The native TCP client is included in the `ClickHouse.Driver` package. Install it from NuGet:
```bash theme={null}
dotnet add package ClickHouse.Driver
```
Or using the NuGet Package Manager:
```bash theme={null}
Install-Package ClickHouse.Driver
```
Quick start
```csharp theme={null}
using ClickHouse.Driver.Tcp;
// Create and reuse a client. It is thread-safe and owns a connection pool.
await using var client = new ClickHouseTcpClient(
"Host=my.clickhouse;Port=9000;Username=user");
// Execute a query
object version = await client.ExecuteScalarAsync("SELECT version()");
Console.WriteLine(version);
```
Migrating from the HTTP client
The TCP API is separate from `IClickHouseClient`; it is not a transport option for
`ClickHouseClient` or `ClickHouseConnection`. Most SQL can be reused, but construct a
`ClickHouseTcpClient` and migrate each operation to its TCP equivalent.
Method equivalents
| HTTP client | TCP client | Important difference |
| - | - | - |
| `new ClickHouseClient(...)` | `new ClickHouseTcpClient(...)` | Use `ClickHouseTcpClientOptions` or a TCP connection string and the native port, normally 9000 without TLS. Reuse either client across operations. |
| `ExecuteNonQueryAsync(...)` | `ExecuteAsync(...)` | The TCP method completes when ClickHouse acknowledges the statement and does not return an affected-row count. |
| `ExecuteScalarAsync(...)` | `ExecuteScalarAsync(...)` | Both return the first value, or `null` for an empty result. The TCP method drains the complete response before returning so the connection can be reused. |
| `ExecuteReaderAsync(...)` | `QueryAsync(...)`, `QueryAsync(...)`, or `StreamAsync(...)` | TCP has no `DbDataReader`. Choose allocated `object[]` rows, mapped POCOs, or borrowed columnar blocks. |
| `QueryAsync(...)` | `QueryAsync(...)` | TCP builds and caches the POCO mapping automatically; no registration call is required. Use `ClickHouseTcpColumn` and `ClickHouseTcpNotMapped` instead of the HTTP mapping attributes. |
| `InsertBinaryAsync(table, columns, rows)` | `InsertRowsAsync(sql, rows)` | Pass a materialized `IReadOnlyList`; the SQL must end at `VALUES`. The TCP method does not return an inserted-row count. |
| `InsertBinaryAsync(table, rows)` | `InsertRowsAsync(sql, rows)` | TCP needs no POCO registration, but every column named by the statement must map to a compatible public property. |
| — | `InsertAsync(sql, columns)` | Use typed `IColumn` values to avoid the row-to-column projection and value-type boxing of row inserts. |
| `PingAsync(...)` | `PingAsync(...)` | HTTP returns `false` for a failed ping; TCP completes successfully on `Pong` and otherwise throws. |
| `ExecuteRawResultAsync(...)`, `InsertRawStreamAsync(...)`, `PostStreamAsync(...)` | No equivalent | Keep the HTTP client for raw streams and formats such as CSV, JSONEachRow, and Parquet. |
| `CreateConnection()` or ADO.NET types | No equivalent | Keep the HTTP client for ADO.NET and ORMs. |
For example, an HTTP reader loop:
```csharp theme={null}
using var reader = await http.ExecuteReaderAsync(
"SELECT id, name FROM events ORDER BY id");
while (reader.Read())
{
Console.WriteLine($"{reader.GetFieldValue(0)}: {reader.GetString(1)}");
}
```
becomes an asynchronous TCP row stream:
```csharp theme={null}
await foreach (object[] row in tcp.QueryAsync(
"SELECT id, name FROM events ORDER BY id"))
{
Console.WriteLine($"{row[0]}: {row[1]}");
}
```
Options and parameters
HTTP `QueryOptions` and `ClickHouseParameterCollection` are not interchangeable with their TCP
counterparts. Move the values into `ClickHouseTcpQueryOptions`, where settings are strings and
parameters are part of the options object:
```csharp theme={null}
var options = new ClickHouseTcpQueryOptions
{
QueryId = "events-by-score",
Settings = new Dictionary
{
["max_execution_time"] = "30",
},
Parameters = new ClickHouseTcpParameterCollection
{
{ "minimum", 18.0 },
},
};
await foreach (object[] row in client.QueryAsync(
"SELECT id, score FROM events WHERE score >= {minimum:Float64}",
options))
{
Console.WriteLine($"{row[0]}: {row[1]}");
}
```
The TCP client supports ClickHouse-native `{name:Type}` placeholders but does not rewrite
ADO.NET-style `@name` placeholders. It also has no per-query database, role, bearer token, custom
header, parameter resolver or formatter, or read converter. See [limitations](#limitations) for the
features that remain HTTP-only.
Connection and result lifetime
Both high-level clients are thread-safe and should be reused. The TCP client owns persistent native
connections rather than HTTP connections, implements `IAsyncDisposable`, and should normally be
disposed asynchronously when the application shuts down.
`QueryAsync` rows are caller-owned. `StreamAsync` blocks and their columns are borrowed and valid
only for the current iteration; copy any values that must outlive it. Always finish or dispose an
enumeration so its connection returns to the pool. Use `OpenSessionAsync` when several operations
must run on the same connection and retain session state.
See the complete
[HTTP-to-TCP migration example](https://github.com/ClickHouse/clickhouse-cs/blob/main/examples/Tcp/Core/Tcp_004_MigratingFromHttp.cs)
for both clients used against the same table.
Configuration
There are two ways to configure a native TCP client:
* **Connection string:** Semicolon-separated key/value pairs that specify the server endpoint,
authentication credentials, and other connection options.
* **`ClickHouseTcpClientOptions` object:** A strongly typed, immutable configuration object set in
code.
Pass either form to the `ClickHouseTcpClient` constructor. Use
`ClickHouseTcpConnectionStringBuilder` to parse or build a connection string and convert it to
`ClickHouseTcpClientOptions`.
```csharp theme={null}
var builder = new ClickHouseTcpConnectionStringBuilder
{
Host = "my.clickhouse",
Username = "user",
UseTls = true,
Compression = "zstd",
};
await using var client = new ClickHouseTcpClient(builder.ToOptions());
```
The following sections list the available settings, their defaults, and their effects.
Connection settings
Connection-string values for `TimeSpan` properties are expressed in seconds.
| Property | Type | Default | Connection String Key | Description |
| - | - | - | - | - |
| Host | `string` | `"localhost"` | `Host` | ClickHouse server hostname or IP address |
| Port | `int?` | `null` | `Port` | Native-protocol port; when omitted, uses 9000 without TLS or 9440 with TLS |
| Username | `string` | `"default"` | `Username` | Authentication username |
| Password | `string` | `""` | `Password` | Authentication password |
| Database | `string` | `"default"` | `Database` | Default database for operations |
| QuotaKey | `string` | `""` | `QuotaKey` | Key used with a ClickHouse keyed quota |
| DialTimeout | `TimeSpan` | 30 seconds | `DialTimeout` | Timeout for the socket connection, TLS negotiation, and native-protocol handshake |
| ReadTimeout | `TimeSpan` | 5 minutes | `ReadTimeout` | Maximum time for each transport read during an operation; zero disables the timeout |
Data format and serialization
| Property | Type | Default | Connection String Key | Description |
| - | - | - | - | - |
| SendJsonAndDynamicSerializationSettings | `bool` | `true` | `SendJsonAndDynamicSerializationSettings` | Requests the `JSON` and `Dynamic` wire formats supported by the client. Set to `false` for a readonly user that cannot modify settings; reading those types may then fail. |
| MaxSendBufferBytes | `int` | 1 MiB | `MaxSendBufferBytes` | Soft cap on buffered insert data. The client checks it after each column, so one column can take the buffer past the cap. |
| Compressor | `IClickHouseCompressor` | `Lz4Compressor.Default` | `Compression` | Compresses blocks written by the client and requests compressed results. Connection strings accept `lz4`, `zstd`, or `none`; a custom compressor can be set only through options. |
Connection pooling
One connection runs one operation at a time. The pool lets operations run concurrently and reuses
connections between them.
| Property | Type | Default | Connection String Key | Description |
| - | - | - | - | - |
| MinPoolSize | `int` | `0` | `MinPoolSize` | Number of connections the pool keeps open when possible, including connections currently in use |
| MaxPoolSize | `int` | `20` | `MaxPoolSize` | Hard limit on open connections and concurrent operations; additional operations wait for a connection |
| PoolTimeout | `TimeSpan` | 30 seconds | `PoolTimeout` | Maximum time to wait for a connection when the pool is full; establishing a new connection is bounded separately by `DialTimeout` |
| MaxConnectionLifetime | `TimeSpan` | 30 minutes | `MaxConnectionLifetime` | Maximum connection age for reuse; zero disables the limit; active operations are never interrupted |
| IdleTimeout | `TimeSpan` | 5 minutes | `IdleTimeout` | Maximum time an unused connection remains eligible for reuse; zero disables the limit |
| SweepInterval | `TimeSpan?` | `null` (derived) | `SweepInterval` | How often expired connections are retired and `MinPoolSize` is restored; the default derives from the lifetime and idle limits |
| PoolReusePolicy | `ClickHouseTcpPoolReusePolicy` | `Lifo` | `PoolReusePolicy` | Selects the most recently returned (`Lifo`) or least recently returned (`Fifo`) idle connection |
Security
| Property | Type | Default | Connection String Key | Description |
| - | - | - | - | - |
| UseTls | `bool` | `false` | `UseTls` | Enables TLS before the native-protocol handshake. When `Port` is omitted, enabling TLS changes the default port from 9000 to 9440. |
| TlsServerName | `string` | `null` | `TlsServerName` | Hostname sent as SNI and matched against the server certificate; `null` uses `Host` |
| TlsAllowInvalidCertificates | `bool` | `false` | `TlsAllowInvalidCertificates` | Accepts a certificate that fails validation; use only for local development |
| TlsCaCertificatePath | `string` | `null` | `TlsCaCertificatePath` | Path to a PEM file containing at least one trusted root certificate; replaces the host trust store and cannot be combined with `TlsAllowInvalidCertificates` |
| ConfigureTls | `Action` | `null` | — | Adjusts TLS options before each handshake, after the other TLS properties are applied; available only through `ClickHouseTcpClientOptions` |
Without TLS, the password and all query data travel over the network without encryption. Keep
`TlsAllowInvalidCertificates` set to `false` outside local development.
The secure native protocol is a separate server endpoint rather than an in-band upgrade. A TLS
client must connect to a secure native port; it does not fall back to plaintext. `ConfigureTls` is
applied last and can override certificate and hostname validation, so review custom callbacks
carefully.
Logging and debugging
| Property | Type | Default | Connection String Key | Description |
| - | - | - | - | - |
| LoggerFactory | `ILoggerFactory` | `null` | — | Provides loggers for connection, pool, and operation lifecycle events under `ClickHouse.Driver.Tcp.*` categories |
| IncludeSqlInActivityTags | `bool` | `false` | — | Adds statement text to the OpenTelemetry `db.query.text` attribute, capped by `StatementMaxLength` |
| StatementMaxLength | `int` | `5` | — | Maximum statement characters included in debug logs and activity tags; zero or less omits the text |
The client logger records client-side lifecycle and operation events. Server log packets are sent
to `ClickHouseTcpQueryCallbacks.OnLog` instead. Statement text can contain sensitive data, so it is
excluded from activity tags by default and heavily truncated in debug logs.
Custom settings
`ClickHouseTcpClientOptions.CustomSettings` applies ClickHouse server settings to every query and
insert. Per-operation `ClickHouseTcpQueryOptions.Settings` values override client-level values with
the same name.
```csharp theme={null}
var options = new ClickHouseTcpClientOptions
{
Host = "my.clickhouse",
CustomSettings = new Dictionary
{
["max_threads"] = "4",
},
};
```
In a connection string, prefix each server setting with `set_`:
```text theme={null}
Host=my.clickhouse;set_max_threads=4;set_max_memory_usage=10000000000
```
Do not include the `set_` prefix when adding a setting to `CustomSettings` or per-operation
`Settings`.
ClickHouseTcpQueryOptions
`ClickHouseTcpQueryOptions` supplies per-operation settings. All properties are optional.
| Property | Type | Default | Description |
| - | - | - | - |
| QueryId | `string` | `null` | Identifier used in `system.query_log`, logs, and trace spans; `null` or empty generates a new GUID for each operation |
| Settings | `IReadOnlyDictionary` | `null` | Server settings for this operation; values override matching client-level `CustomSettings` |
| Parameters | `ClickHouseTcpParameterCollection` | `null` | Values bound to `{name:Type}` placeholders in the SQL statement |
| Callbacks | `ClickHouseTcpQueryCallbacks` | `null` | Synchronous callbacks for progress, profile information, server logs, profile events, totals, and extremes |
```csharp theme={null}
var queryOptions = new ClickHouseTcpQueryOptions
{
QueryId = $"report-{Guid.NewGuid():N}",
Settings = new Dictionary
{
["max_threads"] = "4",
},
};
object count = await client.ExecuteScalarAsync(
"SELECT count() FROM numbers(1000)",
queryOptions);
```
ClickHouseTcpInsertOptions
`ClickHouseTcpInsertOptions` extends `ClickHouseTcpQueryOptions` with settings for native block
inserts. All query-option properties are also available.
| Property | Type | Default | Description |
| - | - | - | - |
| MaxRowsPerBlock | `int?` | `50,000` | Maximum rows per wire block; `null` writes the insert as one block. Lower values also reduce temporary memory used by row and POCO inserts. |
| DeduplicationToken | `string` | `null` | Identifies one batch for server-side insert deduplication. Reuse the same token for every retry of that batch and a different token for each new batch. |
```csharp theme={null}
var insertOptions = new ClickHouseTcpInsertOptions
{
MaxRowsPerBlock = 10_000,
DeduplicationToken = batchContentHash,
};
await client.InsertRowsAsync(
"INSERT INTO events (id, name) VALUES",
rows,
insertOptions);
```
ClickHouseTcpClient
`ClickHouseTcpClient` is the high-level API for the native TCP protocol. It executes statements and
scalar queries, streams results as columnar blocks, rows, or POCOs, inserts columnar or row data,
and opens pinned sessions.
The client is thread-safe and owns a connection pool. Create one client per endpoint, share it
across the application, and dispose it at shutdown. Operations run concurrently up to
`MaxPoolSize`; additional operations wait for a connection for up to `PoolTimeout`.
Creating a client
Create a client from a connection string or `ClickHouseTcpClientOptions`. See
[Configuration](#configuration) for the available settings.
Using a connection string:
```csharp theme={null}
using ClickHouse.Driver.Tcp;
await using var client = new ClickHouseTcpClient(
"Host=localhost;Port=9000;Username=default");
```
Using strongly typed options:
```csharp theme={null}
var options = new ClickHouseTcpClientOptions
{
Host = "my.clickhouse",
Username = "user",
UseTls = true,
MaxPoolSize = 20,
};
await using var client = new ClickHouseTcpClient(options);
```
Prefer asynchronous disposal. Disposing the client closes idle connections and waits up to
`PoolTimeout` for active operations before aborting them.
Dependency injection
`AddClickHouseTcpDataSource` registers one singleton data source and exposes its shared client as
`IClickHouseTcpClient` and `IClickHouseTcpOperations`:
```csharp theme={null}
using ClickHouse.Driver.Tcp;
using Microsoft.Extensions.DependencyInjection;
services.AddClickHouseTcpDataSource(
"Host=my.clickhouse;UseTls=true;Username=user");
public sealed class ReportService(IClickHouseTcpClient client)
{
public async Task