Add ClickHouse module

docs/modules/clickhouse.md

@@ -0,0 +1,69 @@
+# ClickHouse Module
+
+[ClickHouse](https://clickhouse.com/) 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
+
+```bash
+npm install @testcontainers/clickhouse --save-dev
+```
+
+## Examples
+
+<!--codeinclude-->
+
+[Connect and execute query:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:connectWithOptions
+
+<!--/codeinclude-->
+
+<!--codeinclude-->
+
+[Connect using URL and execute query:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:connectWithUrl
+
+<!--/codeinclude-->
+
+<!--codeinclude-->
+
+[Connect with username and password and execute query:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:connectWithUsernameAndPassword
+
+<!--/codeinclude-->
+
+<!--codeinclude-->
+
+[Set database:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:setDatabase
+
+<!--/codeinclude-->
+
+<!--codeinclude-->
+
+[Set username:](../../packages/modules/clickhouse/src/clickhouse-container.test.ts) inside_block:setUsername
+
+<!--/codeinclude-->
+
+### Connection Methods
+
+The module provides several methods to connect to the ClickHouse container:
+
+1. `getClientOptions()` - Returns a configuration object suitable for `@clickhouse/client`:
+
+   ```typescript
+   {
+     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 that supports HTTP connections.

mkdocs.yml

@@ -51,6 +51,7 @@ nav:
       - Azurite: modules/azurite.md
       - Cassandra: modules/cassandra.md
       - ChromaDB: modules/chromadb.md
+      - ClickHouse: modules/clickhouse.md
       - CosmosDB: modules/cosmosdb.md
       - Couchbase: modules/couchbase.md
       - CockroachDB: modules/cockroachdb.md

packages/modules/clickhouse/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@testcontainers/clickhouse",
+  "version": "10.24.1",
+  "license": "MIT",
+  "keywords": [
+    "clickhouse",
+    "testing",
+    "docker",
+    "testcontainers"
+  ],
+  "description": "ClickHouse module for Testcontainers",
+  "homepage": "https://github.com/testcontainers/testcontainers-node#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/testcontainers/testcontainers-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/testcontainers/testcontainers-node/issues"
+  },
+  "main": "build/index.js",
+  "files": [
+    "build"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "shx cp ../../../README.md . && shx cp ../../../LICENSE .",
+    "build": "tsc --project tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@clickhouse/client": "^1.11.0"
+  },
+  "dependencies": {
+    "testcontainers": "^10.24.1"
+  }
+} 

packages/modules/clickhouse/src/clickhouse-container.test.ts

@@ -0,0 +1,184 @@
+import { ClickHouseClient, createClient } from "@clickhouse/client";
+import { Wait } from "testcontainers";
+import { ClickHouseContainer } from "./clickhouse-container";
+
+interface ClickHouseQueryResponse<T> {
+  data: T[];
+}
+
+describe("ClickHouseContainer", { timeout: 180_000 }, () => {
+  it("should start successfully with default settings", async () => {
+    const container = new ClickHouseContainer();
+    const startedContainer = await container.start();
+    expect(startedContainer.getHost()).toBeDefined();
+    expect(startedContainer.getHttpPort()).toBeDefined();
+    expect(startedContainer.getDatabase()).toBeDefined();
+    expect(startedContainer.getUsername()).toBeDefined();
+    expect(startedContainer.getPassword()).toBeDefined();
+    await startedContainer.stop();
+  });
+
+  // connectWithOptions {
+  it("should connect using the client options object", async () => {
+    const container = await new ClickHouseContainer().start();
+    let client: ClickHouseClient | undefined;
+
+    try {
+      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);
+    } finally {
+      await client?.close();
+      await container.stop();
+    }
+  });
+  // }
+
+  // connectWithUrl {
+  it("should connect using the URL", async () => {
+    const container = await new ClickHouseContainer().start();
+    let client: ClickHouseClient | undefined;
+
+    try {
+      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);
+    } finally {
+      await client?.close();
+      await container.stop();
+    }
+  });
+  // }
+
+  // connectWithUsernameAndPassword {
+  it("should connect using the username and password", async () => {
+    const container = await new ClickHouseContainer()
+      .withUsername("customUsername")
+      .withPassword("customPassword")
+      .start();
+
+    let client: ClickHouseClient | undefined;
+
+    try {
+      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);
+    } finally {
+      await client?.close();
+      await container.stop();
+    }
+  });
+  // }
+
+  // setDatabase {
+  it("should set database", async () => {
+    const customDatabase = "customDatabase";
+    const container = await new ClickHouseContainer().withDatabase(customDatabase).start();
+
+    let client: ClickHouseClient | undefined;
+
+    try {
+      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);
+    } finally {
+      await client?.close();
+      await container.stop();
+    }
+  });
+  // }
+
+  // setUsername {
+  it("should set username", async () => {
+    const customUsername = "customUsername";
+    const container = await new ClickHouseContainer().withUsername(customUsername).start();
+
+    let client: ClickHouseClient | undefined;
+
+    try {
+      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);
+    } finally {
+      await client?.close();
+      await container.stop();
+    }
+  });
+  // }
+
+  it("should work with restarted container", async () => {
+    const container = await new ClickHouseContainer().start();
+    await container.restart();
+
+    let client: ClickHouseClient | undefined;
+    try {
+      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);
+    } finally {
+      await client?.close();
+      await container.stop();
+    }
+  });
+
+  /**
+   * Verifies that a custom Docker health check that fails immediately
+   * causes the container startup process (`container.start()`) to reject with an error.
+   *
+   * Note: This test pattern was adapted from a similar test case used for
+   * PostgreSQL containers to ensure custom failing health checks are handled correctly.
+   */
+  it("should allow custom healthcheck", async () => {
+    const container = new ClickHouseContainer()
+      .withHealthCheck({
+        test: ["CMD-SHELL", "exit 1"],
+        interval: 100,
+        retries: 0,
+        timeout: 100,
+      })
+      .withWaitStrategy(Wait.forHealthCheck());
+
+    await expect(() => container.start()).rejects.toThrow();
+  });
+});