ClickHouse C# client

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

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UseSession `bool` `false` `UseSession` Enable stateful sessions; serializes requests|  |  |  |  |  | | --- | --- | --- | --- | --- | | SessionId `string` `null` `SessionId` Session ID; auto-generates GUID if null and UseSession is true | | | | | | | | | | | | | | |

Note

The `UseSession` flag enables persistence of the server session, allowing use of `SET` statements and temporary tables. Sessions will be reset after 60 seconds of inactivity (default timeout). Session lifetime can be extended by setting session settings via ClickHouse statements or the server configuration.

The `ClickHouseConnection` class normally allows for parallel operation (multiple threads can run queries concurrently). However, enabling `UseSession` flag will limit that to one active query per connection at any moment of time (this is a server-side limitation).

### Security[​](#security "Direct link to Security")

|  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  | | --- | --- | --- | --- | --- | | SkipServerCertificateValidation `bool` `false` — Skip HTTPS certificate validation; **not for production use** | | | | | | | | | |

### HTTP client configuration[​](#http-client-configuration "Direct link to HTTP client configuration")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | HttpClient `HttpClient` `null` — Custom pre-configured HttpClient instance|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | HttpClientFactory `IHttpClientFactory` `null` — Custom factory for creating HttpClient instances|  |  |  |  |  | | --- | --- | --- | --- | --- | | HttpClientName `string` `null` — Name for HttpClientFactory to create specific client | | | | | | | | | | | | | | | | | | | |

### Logging & debugging[​](#logging-debugging "Direct link to Logging & debugging")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | LoggerFactory `ILoggerFactory` `null` — Logger factory for diagnostic logging|  |  |  |  |  | | --- | --- | --- | --- | --- | | EnableDebugMode `bool` `false` — Enable .NET network tracing (requires LoggerFactory with level set to Trace); **significant performance impact** | | | | | | | | | | | | | | |

### Custom settings & roles[​](#custom-settings-roles "Direct link to Custom settings & roles")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Default Connection String Key Description|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | CustomSettings `IDictionary<string, object>` Empty `set_*` prefix ClickHouse server settings, see note below|  |  |  |  |  | | --- | --- | --- | --- | --- | | Roles `IReadOnlyList<string>` Empty `Roles` Comma-separated ClickHouse roles (e.g., `Roles=admin,reader`) | | | | | | | | | | | | | | |

Note

When using a connection string to set custom settings, use the `set_` prefix, e.g. "set\_max\_threads=4". When using a ClickHouseClientSettings object, don't use the `set_` prefix.

For a full list of available settings, see [here](https://clickhouse.com/docs/operations/settings/settings).

---

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

#### Basic connection[​](#basic-connection "Direct link to Basic connection")

```
Host=localhost;Port=8123;Username=default;Password=secret;Database=mydb
```

#### With custom ClickHouse settings[​](#with-custom-clickhouse-settings "Direct link to With custom ClickHouse settings")

```
Host=localhost;set_max_threads=4;set_readonly=1;set_max_memory_usage=10000000000
```

---

### QueryOptions[​](#query-options "Direct link to QueryOptions")

`QueryOptions` allows you to override client-level settings on a per-query basis. All properties are optional and only override the client defaults when specified.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Property Type Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | QueryId `string` Custom query identifier for tracking in `system.query_log` or cancellation| Database `string` Override the default database for this query|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Roles `IReadOnlyList<string>` Override client roles for this query|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | CustomSettings `IDictionary<string, object>` ClickHouse server settings for this query (e.g., `max_threads`)| CustomHeaders `IDictionary<string, string>` Additional HTTP headers for this query|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | UseSession `bool?` Override session behavior for this query|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | SessionId `string` Session ID for this query (requires `UseSession = true`)| BearerToken `string` Override authentication token for this query|  |  |  | | --- | --- | --- | | MaxExecutionTime `TimeSpan?` Server-side query timeout (passed as `max_execution_time` setting); server cancels query if exceeded | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

**Example:**

```
var options = new QueryOptions
{
    QueryId = "report-2024-001",
    Database = "analytics",
    CustomSettings = new Dictionary<string, object>
    {
        { "max_threads", 4 },
        { "max_memory_usage", 10_000_000_000 }
    },
    MaxExecutionTime = TimeSpan.FromMinutes(5)
};

var reader = await client.ExecuteReaderAsync(
    "SELECT * FROM large_table",
    parameters: null,
    options: options
);
```

---

### InsertOptions[​](#insert-options "Direct link to InsertOptions")

`InsertOptions` extends `QueryOptions` with settings specific to bulk insert operations via `InsertBinaryAsync`.