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.

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 add clickhouse

Aspire CLI 是交互式的；按提示选择合适的搜索结果：

Select an integration to add:

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

#:package 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

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);

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);

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);

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:

dotnet add package Aspire.ClickHouse.Driver

#:package Aspire.ClickHouse.Driver@*

<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.

builder.AddClickHouseDataSource(connectionName: "clickhousedb");

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:

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:

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:

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:

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:

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;

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:

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

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

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:

# 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:

// 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.