Integration ClickHouse Extension

The Kronikol.Extensions.ClickHouse package adds ClickHouse operation tracking to your test diagrams using a DbConnection wrapping decorator pattern.

Works with both clients. ClickHouse on .NET is typically accessed through one of two ADO.NET providers — ClickHouse.Client (ClickHouse.Client.ADO.ClickHouseConnection) or Octonica.ClickHouseClient (Octonica.ClickHouseClient.ClickHouseConnection). Both derive from DbConnection, so this extension supports either one and takes no hard dependency on a specific client package.

Why wrapping? Neither ClickHouse client emits DiagnosticSource events. This extension wraps the connection with TrackingClickHouseConnection, which intercepts all command executions (and transactions, where supported).

---

How It Works

TrackingClickHouseConnection wraps a real ClickHouse DbConnection and returns TrackingClickHouseCommand instances that intercept all 6 execution methods (ExecuteReader/NonQuery/Scalar × sync/async). All intercepted operations are classified by UnifiedSqlClassifier and logged to RequestResponseLogger.

The classifier understands ClickHouse-specific SQL in addition to standard DML/DDL:

ClickHouse statement	Classified as	Detailed label
ALTER TABLE t UPDATE col = … WHERE …	Update	UPDATE t
ALTER TABLE t DELETE WHERE …	Delete	DELETE FROM t
ALTER TABLE t ADD COLUMN …	AlterTable	ALTER TABLE t
OPTIMIZE TABLE t FINAL	Optimize	OPTIMIZE t
RENAME TABLE a TO b	Rename	RENAME a
ATTACH TABLE t / DETACH TABLE t	Attach / Detach	ATTACH t / DETACH t
INSERT INTO t FORMAT …	Insert	INSERT INTO t
CREATE TABLE t (…) ENGINE = MergeTree()	CreateTable	CREATE TABLE t

ON CLUSTER clauses are handled transparently when detecting mutations.

---

Install

dotnet add package Kronikol.Extensions.ClickHouse
# plus whichever ClickHouse client you already use:
dotnet add package ClickHouse.Client        # or
dotnet add package Octonica.ClickHouseClient

---

Setup

Option A — Dependency Injection

services.AddClickHouseTestTracking(options =>
{
    options.Verbosity = SqlTrackingVerbosityLevel.Detailed;
});

This decorates all DbConnection registrations with a type-check guard — only ClickHouse connections (from either supported client) are wrapped; others pass through unchanged.

Option B — Manual Wrapping (No DI)

using Kronikol.Extensions.ClickHouse;

// ClickHouse.Client
var inner = new ClickHouse.Client.ADO.ClickHouseConnection("Host=localhost;Port=8123;Database=analytics");
// — or — Octonica.ClickHouseClient
// var inner = new Octonica.ClickHouseClient.ClickHouseConnection("Host=localhost;Port=9000;Database=analytics");

var tracked = inner.WithClickHouseTestTracking(new ClickHouseTrackingOptions
{
    Verbosity = SqlTrackingVerbosityLevel.Detailed
});

await tracked.OpenAsync();
// Use `tracked` as your DbConnection (also works as the connection for Dapper)...

Note: WithClickHouseTestTracking returns a TrackingClickHouseConnection (a DbConnection), not the concrete client type. Client-specific APIs that require the concrete connection — e.g. ClickHouseBulkCopy — should be given the inner connection (tracked.InnerConnection); such bulk paths bypass tracking.

---

Configuration

Property	Default	Description
ServiceName	"ClickHouse"	Participant name in diagrams
CallerName	"Caller"	The caller participant name
Verbosity	Detailed	Raw, Detailed, or Summarised
CurrentTestInfoFetcher	null	Returns the current test's name and ID. Required for the wrapping approach
HttpContextAccessor	null	Optional — enables dual-resolution of test identity from HTTP headers
LogSqlText	true	Include full SQL text in Detailed mode
LogParameters	false	Include parameter values
DependencyCategory	"ClickHouse"	Controls participant shape/colour
UriScheme	"clickhouse"	URI scheme in diagram URIs
ExcludedOperations	[]	Operations to exclude from tracking
SetupVerbosity	null	Verbosity override for the Setup phase. See Phase-Aware Tracking
ActionVerbosity	null	Verbosity override for the Action phase. See Phase-Aware Tracking
TrackDuringSetup	true	When false, tracking is suppressed during Setup
TrackDuringAction	true	When false, tracking is suppressed during Action
LogResponseContent	true	Include response data in diagram arrows at all verbosity levels
MaxResponseRows	10	Maximum rows to capture in response content
MaxValueDisplayLength	500	Truncate individual cell values beyond this length
ResponseDetail	RowCountAndColumns	RowCountOnly, RowCountAndColumns, or FullRows

All options inherit from SqlTrackingOptionsBase.

---

Verbosity Levels

Level	Arrow label	URI
Raw	Full SQL text	clickhouse://host/database
Detailed	SELECT FROM events	clickhouse://host/database/events
Summarised	SELECT	clickhouse:///database/events

---

Response Payload Capture

TrackingClickHouseCommand captures response data from ExecuteReader and ExecuteScalar calls. The ResponseDetail option controls the level of detail:

ResponseDetail	Example output
RowCountOnly	3 rows
RowCountAndColumns (default)	3 rows [name, ts, value]
FullRows	JSON row preview (up to MaxResponseRows)

Set LogResponseContent = false to restore empty-arrow behaviour.

---

Using ClickHouse via EF Core or Dapper

If you access ClickHouse through EF Core (e.g. a community ClickHouse provider), use Integration EF Core Relational Extension — it intercepts commands from any relational provider. If you use Dapper over a ClickHouse connection, you can also use Integration Dapper Extension by wrapping the connection. The dedicated Kronikol.Extensions.ClickHouse package is the best choice for raw ADO.NET usage and gives a first-class ClickHouse participant in diagrams.