ClickHouse client integration reference

이 콘텐츠는 아직 번역되지 않았습니다.

To get started with the Aspire ClickHouse client integration, install the 📦 Aspire.ClickHouse.Driver NuGet package:

This article includes full details about the Aspire ClickHouse Client integration, which allows you to connect to and interact with ClickHouse databases from your Aspire consuming projects.

dotnet add package Aspire.ClickHouse.Driver

#:package Aspire.ClickHouse.Driver@*

<PackageReference Include="Aspire.ClickHouse.Driver" Version="*" />

The ClickHouse client integration registers two services you can use to interact with ClickHouse:

IClickHouseClient — A simple, high-level API for querying and inserting data into ClickHouse.
ClickHouseDataSource — An ADO.NET-compatible data source for scenarios that require connections or commands (e.g. for ORM usage).

For an introduction to the ClickHouse integration, see Get started with the ClickHouse integrations.

Add ClickHouse data source

In the Program.cs file of your client-consuming project, call the AddClickHouseDataSource extension method to register both IClickHouseClient and ClickHouseDataSource for use via the dependency injection container:

builder.AddClickHouseDataSource(connectionName: "clickhousedb");

You can then retrieve either service using dependency injection. Use IClickHouseClient for a simple query and insert API:

public class ExampleService(IClickHouseClient client)
{
    // Use client...
}

Or use ClickHouseDataSource when you need ADO.NET access (connections, commands, transactions):

public class ExampleService(ClickHouseDataSource dataSource)
{
    // Use data source...
}

Add keyed ClickHouse data source

There might be situations where you want to register multiple ClickHouse instances with different connection names. To register keyed ClickHouse data sources, call the AddKeyedClickHouseDataSource method:

builder.AddKeyedClickHouseDataSource(name: "analytics");
builder.AddKeyedClickHouseDataSource(name: "logging");

Then you can retrieve the instances using dependency injection. Both IClickHouseClient and ClickHouseDataSource are available as keyed services:

public class ExampleService(
    [FromKeyedServices("analytics")] IClickHouseClient analyticsClient,
    [FromKeyedServices("logging")] IClickHouseClient loggingClient)
{
    // Use clients...
}

For more information on keyed services, see .NET dependency injection: Keyed services.

Properties of the ClickHouse resources

When you use the WithReference method to pass a ClickHouse server or database resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project.

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Host property of a resource called clickhousedb becomes CLICKHOUSEDB_HOST.

ClickHouse server

The ClickHouse server resource exposes the following connection properties:

Property Name	Description
`Host`	The hostname or IP address of the ClickHouse server
`Port`	The port number the ClickHouse server is listening on (default: 8123)
`Username`	The username for authentication (default: `default`)
`Password`	The password for authentication

ClickHouse database

The ClickHouse database resource inherits all properties from its parent ClickHouseServerResource and adds:

Property Name	Description
`DatabaseName`	The ClickHouse database name

Configuration

The ClickHouse integration provides multiple options to configure the server connection based on the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling AddClickHouseDataSource:

builder.AddClickHouseDataSource("clickhousedb");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "clickhousedb": "Host=localhost;Port=8123;Username=default;Password=secret;Database=clickhousedb"
  }
}

Use configuration providers

The ClickHouse integration supports Microsoft.Extensions.Configuration. It loads the ClickHouseClientSettings from configuration using the Aspire:ClickHouse:Driver key. Example appsettings.json:

{
  "Aspire": {
    "ClickHouse": {
      "Driver": {
        "ConnectionString": "Host=localhost;Port=8123;Username=default;Database=clickhousedb",
        "DisableHealthChecks": false,
        "DisableTracing": false,
        "DisableMetrics": true,
        "HealthCheckTimeout": "00:00:03"
      }
    }
  }
}

The integration also supports named configuration sections for keyed services. When you call AddKeyedClickHouseDataSource with a name, the integration loads settings from Aspire:ClickHouse:Driver:{name} and merges them with the top-level settings. Named configuration takes precedence over the top-level configuration.

Use inline delegates

You can pass the Action<ClickHouseClientSettings> delegate to set up options inline:

builder.AddClickHouseDataSource(
    "clickhousedb",
    static settings => settings.DisableHealthChecks = true);

You can also configure the underlying connection string builder using the Action<ClickHouseConnectionStringBuilder> delegate:

builder.AddClickHouseDataSource(
    "clickhousedb",
    configureConnectionString: static csb =>
    {
        csb.ConnectionString = "Host=localhost;Port=8123;Database=clickhousedb";
    });

Configuration options

Here are the configurable options with corresponding default values:

Name	Description
`ConnectionString`	The connection string of the ClickHouse database to connect to
`DisableHealthChecks`	A boolean value that indicates whether the database health check is disabled or not. Default: `false`
`DisableTracing`	A boolean value that indicates whether the OpenTelemetry tracing is disabled or not. Default: `false`
`DisableMetrics`	A boolean value that indicates whether the OpenTelemetry metrics are disabled or not. Default: `true` (the ClickHouse driver doesn’t currently emit metrics)
`HealthCheckTimeout`	A `TimeSpan?` value that indicates the health check timeout. Default: `null` (uses system default)

Client integration health checks

By default, Aspire integrations enable health checks for all services. For more information, see Aspire integrations overview.

The ClickHouse client integration handles the following:

Adds a health check that calls PingAsync on the configured ClickHouseDataSource. If the ping succeeds, the health check is considered healthy.
The health check name is "ClickHouse" for unkeyed services, or "ClickHouse_{name}" for keyed services.
Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.

Observability and telemetry

Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. Depending on the backing service, some integrations may only support some of these features. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The Aspire ClickHouse client integration uses the following log categories:

ClickHouse.Driver
ClickHouse.Driver.BulkCopy
ClickHouse.Driver.Client
ClickHouse.Driver.Command
ClickHouse.Driver.Connection
ClickHouse.Driver.Transport

Tracing

The Aspire ClickHouse client integration emits the following tracing activities using OpenTelemetry:

ClickHouse.Driver

Metrics

The Aspire ClickHouse client integration doesn’t currently expose any OpenTelemetry metrics. The DisableMetrics setting defaults to true.