ClickHouse Module

ClickHouse is a column-oriented database management system for online analytical processing (OLAP) that allows users to generate analytical reports using SQL queries in real-time.

Install

npm install @testcontainers/clickhouse --save-dev

Examples

Connect and execute query:

it("should connect using the client options object", async () => {
  const container = await new ClickHouseContainer().start();
  const client = createClient(container.getClientOptions());

  const result = await client.query({
    query: "SELECT 1 AS value",
    format: "JSON",
  });
  const data = (await result.json()) as ClickHouseQueryResponse<{ value: number }>;
  expect(data?.data?.[0]?.value).toBe(1);

  await client.close();
  await container.stop();
});

Connect using URL and execute query:

it("should connect using the URL", async () => {
  const container = await new ClickHouseContainer().start();
  const client = createClient({
    url: container.getConnectionUrl(),
  });

  const result = await client.query({
    query: "SELECT 1 AS value",
    format: "JSON",
  });

  const data = (await result.json()) as ClickHouseQueryResponse<{ value: number }>;
  expect(data?.data?.[0]?.value).toBe(1);

  await client.close();
  await container.stop();
});

Connect with username and password and execute query:

it("should connect using the username and password", async () => {
  const container = await new ClickHouseContainer()
    .withUsername("customUsername")
    .withPassword("customPassword")
    .start();

  const client = createClient({
    url: container.getHttpUrl(),
    username: container.getUsername(),
    password: container.getPassword(),
  });

  const result = await client.query({
    query: "SELECT 1 AS value",
    format: "JSON",
  });

  const data = (await result.json()) as ClickHouseQueryResponse<{ value: number }>;
  expect(data?.data?.[0]?.value).toBe(1);

  await client.close();
  await container.stop();
});

Set database:

it("should set database", async () => {
  const customDatabase = "customDatabase";
  const container = await new ClickHouseContainer().withDatabase(customDatabase).start();

  const client = createClient(container.getClientOptions());

  const result = await client.query({
    query: "SELECT currentDatabase() AS current_database",
    format: "JSON",
  });

  const data = (await result.json()) as ClickHouseQueryResponse<{ current_database: string }>;
  expect(data?.data?.[0]?.current_database).toBe(customDatabase);

  await client.close();
  await container.stop();
});

Set username:

it("should set username", async () => {
  const customUsername = "customUsername";
  const container = await new ClickHouseContainer().withUsername(customUsername).start();

  const client = createClient(container.getClientOptions());

  const result = await client.query({
    query: "SELECT currentUser() AS current_user",
    format: "JSON",
  });

  const data = (await result.json()) as ClickHouseQueryResponse<{ current_user: string }>;
  expect(data?.data?.[0]?.current_user).toBe(customUsername);

  await client.close();
  await container.stop();
});

Connection Methods

The module provides several methods to connect to the ClickHouse container:

1. getClientOptions() - Returns a configuration object suitable for @clickhouse/client:

   {
     url: string; // HTTP URL with host and port
     username: string; // Container username
     password: string; // Container password
     database: string; // Container database
   }
   

2. getConnectionUrl() - Returns a complete HTTP URL including credentials and database:

   http://[username[:password]@][host[:port]]/database
   

3. getHttpUrl() - Returns the base HTTP URL without credentials:

   http://[host[:port]]
   

These methods can be used with the @clickhouse/client package or any other ClickHouse client.