Set up ClickHouse in the AppHost

This article is the reference for the Aspire ClickHouse Hosting integration. It enumerates the AppHost APIs that you use to model ClickHouse server and database resources in your AppHost project.

If you’re new to the ClickHouse integration, start with the Get started with ClickHouse integrations guide. For how consuming apps read the connection information this page exposes, see Connect to ClickHouse.

Not

TypeScript AppHost support for the ClickHouse integration is not yet available. All examples on this page are for C# AppHosts.

Installation

To start building an Aspire app that uses ClickHouse, install the 📦 Aspire.Hosting.ClickHouse NuGet package:

Terminal

aspire add clickhouse

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.ClickHouse@*

XML — AppHost.csproj

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

Add ClickHouse server resource

Once you’ve installed the hosting integration in your AppHost project, you can add a ClickHouse server resource and then add a database resource as shown in the following example:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var clickhouse = builder.AddClickHouse("clickhouse");
var clickhousedb = clickhouse.AddDatabase("clickhousedb");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(clickhousedb)
    .WaitFor(clickhousedb);

// After adding all resources, run the app...

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the clickhouse/clickhouse-server image, it creates a new ClickHouse server instance on your local machine. A reference to the clickhousedb database resource is then used to add a dependency to the consuming project.

2. The database is automatically created using CREATE DATABASE IF NOT EXISTS when the server resource becomes ready.

3. The ClickHouse server resource includes default credentials with a CLICKHOUSE_USER of default and a randomly generated CLICKHOUSE_PASSWORD.

4. The password is stored in the AppHost’s secret store in the Parameters section:

   JSON — secrets.json

   {
     "Parameters:clickhouse-password": "<THE_GENERATED_PASSWORD>"
   }

5. The WithReference call configures a connection in the consuming project named after the referenced database resource, such as clickhousedb in the preceding example.

Not

When you reference a ClickHouse resource from the AppHost, Aspire makes several properties available to the consuming project, such as hostnames, port numbers, and credentials. For a complete list of these properties and per-language connection examples, see Connect to ClickHouse.

İpucu

If you’d rather connect to an existing ClickHouse server, call AddConnectionString instead. For more information, see Reference existing resources.

Add ClickHouse resource with data volume

Add a data volume to the ClickHouse resource as shown in the following example:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var clickhouse = builder.AddClickHouse("clickhouse")
    .WithDataVolume(isReadOnly: false);

var clickhousedb = clickhouse.AddDatabase("clickhousedb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
    .WithReference(clickhousedb)
    .WaitFor(clickhousedb);

// After adding all resources, run the app...

The data volume is used to persist the ClickHouse data outside the lifecycle of its container. The data volume is mounted at the /var/lib/clickhouse path in the ClickHouse container and when a name parameter isn’t provided, the name is generated at random. For more information on data volumes and details on why they’re preferred over bind mounts, see Docker docs: Volumes.

Dikkat

Some database integrations, including the ClickHouse integration, can’t successfully use data volumes after deployment to Azure Container Apps (ACA). This is because ACA uses Server Message Block (SMB) to connect containers to data volumes, and some systems can’t use this connection. In the Aspire Dashboard, a database affected by this issue has a status of Activating or Activation Failed but is never listed as Running.

You can resolve the problem by deploying to a Kubernetes cluster, such as Azure Kubernetes Services (AKS). For more information, see Deploy your first Aspire app.

Add ClickHouse resource with data bind mount

Add a data bind mount to the ClickHouse resource as shown in the following example:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var clickhouse = builder.AddClickHouse("clickhouse")
    .WithDataBindMount(
        source: "/ClickHouse/Data",
        isReadOnly: false);

var clickhousedb = clickhouse.AddDatabase("clickhousedb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
    .WithReference(clickhousedb)
    .WaitFor(clickhousedb);

// After adding all resources, run the app...

Not

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine’s filesystem to persist the ClickHouse data across container restarts. The data bind mount is mounted at the C:\ClickHouse\Data on Windows (or /ClickHouse/Data on Unix) path on the host machine in the ClickHouse container. For more information on data bind mounts, see Docker docs: Bind mounts.

Add ClickHouse resource with parameters

When you want to explicitly provide the username and password used by the container image, you can provide these credentials as parameters:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username", secret: true);
var password = builder.AddParameter("password", secret: true);

var clickhouse = builder.AddClickHouse("clickhouse", userName: username, password: password);
var clickhousedb = clickhouse.AddDatabase("clickhousedb");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
    .WithReference(clickhousedb)
    .WaitFor(clickhousedb);

// After adding all resources, run the app...

The username and password parameters are usually specified as user secrets:

JSON — secrets.json

{
  "Parameters": {
    "username": "default",
    "password": "your-secure-password"
  }
}

For more information, see External parameters.

You can also specify a custom host port:

C# — AppHost.cs

var clickhouse = builder.AddClickHouse("clickhouse", port: 18123);

Connection properties

For the full reference of ClickHouse connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to ClickHouse.

Hosting integration health checks

The ClickHouse hosting integration automatically adds a health check for the ClickHouse resource. The health check sends an HTTP GET request to the /ping endpoint on the ClickHouse server and verifies that the instance is running and responsive.