ClickHouse C# client

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/language-clients/csharp.md)

The official C# client for connecting to ClickHouse.
The client source code is available in the [GitHub repository](https://github.com/ClickHouse/clickhouse-cs).
Originally developed by [Oleg V. Kozlyuk](https://github.com/DarkWanderer).

The library provides two main APIs:

- **`ClickHouseClient`** (recommended): A high-level, thread-safe client designed for singleton use. Provides a simple async API for queries and bulk inserts. Best for most applications.
- **ADO.NET** (`ClickHouseDataSource`, `ClickHouseConnection`, `ClickHouseCommand`): Standard .NET database abstractions. Required for ORM integration (Dapper, Linq2db) and when you need ADO.NET compatibility. `ClickHouseBulkCopy` is a helper class for efficiently inserting data using an ADO.NET connection. `ClickHouseBulkCopy` is deprecated and will be removed in a future release; use `ClickHouseClient.InsertBinaryAsync` instead.

Both APIs share the same underlying HTTP connection pool and can be used together in the same application.

## Migration guide[​](#migration-guide "Direct link to Migration guide")

1. Update your `.csproj` file with the new package name `ClickHouse.Driver` and [the latest version on NuGet](https://www.nuget.org/packages/ClickHouse.Driver).
2. Update all `ClickHouse.Client` references to `ClickHouse.Driver` in your codebase.

---

## Supported .NET versions[​](#supported-net-versions "Direct link to Supported .NET versions")

`ClickHouse.Driver` supports the following .NET versions:

- .NET 6.0
- .NET 8.0
- .NET 9.0
- .NET 10.0

## Installation[​](#installation "Direct link to Installation")

Install the package from NuGet:

```
dotnet add package ClickHouse.Driver
```

Or using the NuGet Package Manager:

```
Install-Package ClickHouse.Driver
```

## Quick start[​](#quick-start "Direct link to Quick start")

```
using ClickHouse.Driver;

// Create a client (typically as a singleton)
using var client = new ClickHouseClient("Host=my.clickhouse;Protocol=https;Port=8443;Username=user");

// Execute a query
var version = await client.ExecuteScalarAsync("SELECT version()");
Console.WriteLine(version);
```

## Configuration[​](#configuration "Direct link to Configuration")

There are two ways of configuring your connection to ClickHouse:

- **Connection string:** Semicolon-separated key/value pairs that specify the host, authentication credentials, and other connection options.
- **`ClickHouseClientSettings` object:** A strongly typed configuration object that can be loaded from configuration files or set in code.

Below is a full list of all the settings, their default values, and their effects.

### Connection settings[​](#connection-settings "Direct link to Connection settings")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Host `string` `"localhost"` `Host` Hostname or IP address of the ClickHouse server|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Port `ushort` 8123 (HTTP) / 8443 (HTTPS) `Port` Port number; defaults based on protocol|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Username `string` `"default"` `Username` Authentication username|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Password `string` `""` `Password` Authentication password|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Database `string` `""` `Database` Default database; empty uses server/user default|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Protocol `string` `"http"` `Protocol` Connection protocol: `"http"` or `"https"`| Path `string` `null` `Path` URL path for reverse proxy scenarios (e.g., `/clickhouse`)| Timeout `TimeSpan` 2 minutes `Timeout` Operation timeout (stored as seconds in connection string) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

### Data format & serialization[​](#data-format-serialization "Direct link to Data format & serialization")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UseCompression `bool` `true` `Compression` Enable gzip compression for data transfer|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UseCustomDecimals `bool` `true` `UseCustomDecimals` Use `ClickHouseDecimal` for arbitrary precision; if false, uses .NET `decimal` (128-bit limit)| ReadStringsAsByteArrays `bool` `false` `ReadStringsAsByteArrays` Read `String` and `FixedString` columns as `byte[]` instead of `string`; useful for binary data| UseFormDataParameters `bool` `false` `UseFormDataParameters` Send parameters as form data instead of URL query string|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | JsonReadMode `JsonReadMode` `Binary` `JsonReadMode` How JSON data is returned: `Binary` (returns `JsonObject`) or `String` (returns raw JSON string)| JsonWriteMode `JsonWriteMode` `String` `JsonWriteMode` How JSON data is sent: `String` (serializes via `JsonSerializer`, accepts all inputs) or `Binary` (registered POCOs only with type hints) | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

### Session management[​](#session-management "Direct link to Session management")