Get started with the ClickHouse integrations

ClickHouse is a high-performance, column-oriented SQL database management system (DBMS) for online analytical processing (OLAP). The Aspire ClickHouse integration provides a way to connect to existing ClickHouse instances, or create new instances from the clickhouse/clickhouse-server container image.

In this introduction, you’ll see how to install and use the Aspire ClickHouse integrations in a simple configuration. If you already have this knowledge, see ClickHouse Hosting integration for full reference details.

Nota

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire ClickHouse Hosting integration in your Aspire AppHost project. This integration allows you to create and manage ClickHouse instances from your Aspire hosting projects:

Aspire CLI

Aspire CLI — Añadir paquete Aspire.Hosting.ClickHouse

aspire add clickhouse

La CLI de Aspire es interactiva; asegúrate de seleccionar el resultado adecuado cuando se te pida:

Aspire CLI — Ejemplo de salida

Select an integration to add:

> clickhouse (Aspire.Hosting.ClickHouse)
> Other results listed as selectable options...

Nota

Si solo hay un resultado, la CLI lo selecciona automáticamente. Aún tendrás que confirmar la versión.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.ClickHouse@*

PackageReference (*.csproj)

XML — Añadir referencia de paquete Aspire.Hosting.ClickHouse

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

Next, in the AppHost project, create instances of ClickHouse server and database resources, then pass the database to the consuming client projects:

Select your programming language to get started

C# Python JavaScript

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")
                            .WaitFor(clickhousedb)
                            .WithReference(clickhousedb);

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

var exampleProject = builder.AddUvicornApp("api", "./api", "main:app")
                            .WithExternalHttpEndpoints()
                            .WaitFor(clickhousedb)
                            .WithReference(clickhousedb);

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

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

var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js")
                 .WithExternalHttpEndpoints()
                 .WaitFor(clickhousedb)
                 .WithReference(clickhousedb);

Consejo

This is the simplest implementation of ClickHouse resources in the AppHost. There are many more options you can choose from to address your requirements. For full details, see ClickHouse Hosting integration.

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire ClickHouse client integration:

.NET CLI

.NET CLI — Add Aspire.ClickHouse.Driver package

dotnet add package Aspire.ClickHouse.Driver

Program.cs (C# file-based app)

Program.cs

#:package Aspire.ClickHouse.Driver@*

PackageReference (*.csproj)

XML — Add Aspire.ClickHouse.Driver package reference

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

In the Program.cs file of your client-consuming project, call the AddClickHouseDataSource extension method on any IHostApplicationBuilder to register an IClickHouseClient and a ClickHouseDataSource for use via the dependency injection container. The method takes a connection name parameter.

C# — Program.cs

builder.AddClickHouseDataSource(connectionName: "clickhousedb");

Consejo

The connectionName parameter must match the name used when adding the ClickHouse database resource in the AppHost project. For more information, see Set up hosting integration.

To interact with ClickHouse in your Python consuming projects, you can use the clickhouse-connect library. You can install this library using pip:

pip install clickhouse-connect

Ensure that you import the ClickHouse client in code files that interact with ClickHouse. You should also import the os module to access environment variables:

Python - Import clickhouse-connect

import clickhouse_connect
import os

To interact with ClickHouse in your JavaScript consuming projects, you can use the official @clickhouse/client library. You can install this library using npm:

npm install @clickhouse/client

Ensure that you import the ClickHouse client in code files that interact with ClickHouse:

JavaScript - Import @clickhouse/client

import { createClient } from '@clickhouse/client';

Use injected ClickHouse properties

In the AppHost, when you used the WithReference method to pass a ClickHouse database resource to a consuming client project, Aspire injects several configuration properties that you can 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.

Use the GetValue() method to obtain these environment variables in consuming projects:

C# - Obtain configuration properties

string connectionString = builder.Configuration.GetConnectionString("clickhousedb");
string host = builder.Configuration.GetValue<string>("CLICKHOUSEDB_HOST");
string databaseName = builder.Configuration.GetValue<string>("CLICKHOUSEDB_DATABASENAME");

Use the os.getenv() method to obtain these environment variables in consuming projects:

Python - Obtain configuration properties

connection_string = os.getenv("ConnectionStrings__clickhousedb")
host = os.getenv("CLICKHOUSEDB_HOST")
port = os.getenv("CLICKHOUSEDB_PORT")
username = os.getenv("CLICKHOUSEDB_USERNAME")
password = os.getenv("CLICKHOUSEDB_PASSWORD")
database_name = os.getenv("CLICKHOUSEDB_DATABASENAME")

Use the process.env method to obtain these environment variables in consuming projects:

JavaScript - Obtain configuration properties

const connectionString = process.env.ConnectionStrings__clickhousedb;
const host = process.env.CLICKHOUSEDB_HOST;
const port = process.env.CLICKHOUSEDB_PORT;
const username = process.env.CLICKHOUSEDB_USERNAME;
const password = process.env.CLICKHOUSEDB_PASSWORD;
const databaseName = process.env.CLICKHOUSEDB_DATABASENAME;

Consejo

The full set of properties that Aspire injects depends on the ClickHouse resource configuration. For more information, see Properties of the ClickHouse resources.

Use ClickHouse resources in client code

Now that you’ve registered ClickHouse in the consuming project, you can use the database. Get the IClickHouseClient instance using dependency injection. For example, to retrieve the client from an example service, define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

C# — ExampleService.cs

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

If you need ADO.NET access (connections, commands, transactions), you can inject ClickHouseDataSource instead:

C# — ExampleService.cs

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

Having obtained the client or data source, you can work with ClickHouse as you would in any other C# application.

Use the information you have obtained about the ClickHouse resource to connect to the database. Here is an example of how to connect using clickhouse-connect:

Python - Connect to ClickHouse

# Create ClickHouse client using connection properties
client = clickhouse_connect.get_client(
    host=host,
    port=int(port),
    username=username,
    password=password,
    database=database_name
)

# Verify connection
print(f"Connected to ClickHouse database: {database_name}")

Having obtained the client, you can work with ClickHouse as you would in any other Python application.

Use the information you have obtained about the ClickHouse resource to connect to the database. Here is an example of how to connect using the @clickhouse/client package:

JavaScript - Connect to ClickHouse

// Create ClickHouse client using connection properties
const client = createClient({
  url: `http://${host}:${port}`,
  username: username,
  password: password,
  database: databaseName,
});

// Verify connection
const result = await client.ping();
console.log('ClickHouse connection status:', result.success);

Having obtained the client, you can work with ClickHouse as you would in any other JavaScript application.

Next steps

Now, that you have an Aspire app with ClickHouse integrations up and running, you can use the following reference documents to learn how to configure and interact with the ClickHouse resources:

Understand the ClickHouse hosting integration Discover how to configure data volumes, parameters, and more.

Understand the ClickHouse client integration Discover how to configure keyed clients, client integration health checks, and more.