Skip to content

README.md

Latest commit

 

History

History
242 lines (175 loc) · 17.1 KB

README.md

File metadata and controls

242 lines (175 loc) · 17.1 KB
Raw

ClickHouse C# Driver Examples

This directory contains examples demonstrating various features and usage patterns of the ClickHouse C# driver.

Overview

We aim to cover various scenarios of driver usage with these examples. You should be able to run any of these examples by following the instructions in the How to run section below.

If something is missing, or you found a mistake in one of these examples, please open an issue or a pull request. AGENTS.md has the checklist for adding one.

Examples are grouped by transport. Everything under Http/ uses ClickHouseClient or ClickHouseConnection over HTTP; everything under Tcp/ uses ClickHouseTcpClient over the native protocol, and needs port 9000 rather than 8123 — see Tcp/README.md.

Examples

Core Usage & Configuration

ASP.NET Integration

Authentication

Creating Tables

Inserting Data

Selecting Data

Data Types

ORM Integration

  • ORM_001_Dapper.cs - Using Dapper and Dapper.Contrib with ClickHouse: queries, inserts, type handlers, and known limitations
  • ORM_002_Linq2Db.cs - Using linq2db with ClickHouse: LINQ queries, inserts, BulkCopy, and entity mapping

Advanced Features

Troubleshooting

Testing

Native Protocol: Core Usage & Configuration

These use ClickHouseTcpClient and need port 9000. See Tcp/README.md first.

Native Protocol: Reading Data

Native Protocol: Writing Data

Native Protocol: Data Types

Native Protocol: Connections and Sessions

Native Protocol: Advanced

Native Protocol: Observability

How to run

Prerequisites

  • .NET 10.0 SDK or later
  • ClickHouse server (local or remote)
    • For local runs, you can use Docker: 
      docker run -d --name clickhouse-server -p 8123:8123 -p 9000:9000 clickhouse/clickhouse-server

Running examples

Navigate to the examples directory and run the example program:

cd examples

# Run all examples
dotnet run

# Run only one transport's examples
dotnet run -- --http
dotnet run -- --tcp

# List available examples, optionally for one transport
dotnet run -- --list
dotnet run -- --list --tcp

# Run specific example(s) using a filter
dotnet run -- --filter basicusage

# Shorthand (positional argument)
dotnet run -- basicusage

Before running an example that uses ExampleConfig, the runner checks its endpoint and reports what to fix if it cannot connect. Examples that configure or start their own server skip this preflight.

The filter matches the example's class name, which --list prints. A class name is the topic without the file's category prefix: Core_001_BasicUsage.cs declares class BasicUsage. Matching ignores case and underscores and accepts any substring, so basicusage, basic and usage all match it. The file's core001 prefix does not.

Connection configuration

Most examples take their live server endpoint from ExampleConfig.cs. The seven exceptions are listed below. The defaults are what a stock server container exposes on localhost, and the examples run with nothing set.

Variable Default
CLICKHOUSE_HOST localhost
CLICKHOUSE_HTTP_PORT 8123
CLICKHOUSE_TCP_PORT 9000
CLICKHOUSE_USER default
CLICKHOUSE_PASSWORD empty
CLICKHOUSE_DATABASE default

For an endpoint those pieces cannot describe — TLS, a cloud host, an extra setting — set CLICKHOUSE_HTTP_CONNECTION_STRING or CLICKHOUSE_TCP_CONNECTION_STRING to replace the whole string:

CLICKHOUSE_HOST=my-server CLICKHOUSE_PASSWORD=secret dotnet run -- basicusage

Seven examples do not rely on ExampleConfig for the endpoint they connect to. Two keep literal connection strings because configuration is what they teach: Core_002_ConnectionStringConfiguration.cs and Core_003_DependencyInjection.cs. Three use their own environment variables: Auth_001_JwtAuthentication.cs and Tables_003_CreateTableCloud.cs, plus Tcp_003_Tls.cs. Two start their own server: Testing_001_Testcontainers.cs and Tcp_005_Testcontainers.cs.

ClickHouse Cloud

If you want to use ClickHouse Cloud:

  1. Create a ClickHouse Cloud instance
  2. Update the connection string in the examples: 
    var connection = new ClickHouseConnection(
    "Host=your-instance.clickhouse.cloud;Port=8443;Protocol=https;Username=default;Password=your_password;Database=default"
);

Additional resources