Add ClickHouse module (#981)

Author: Victorlouisdg

docs/modules/clickhouse.md

@@ -0,0 +1,55 @@
+# 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.

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

package-lock.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/package.json

@@ -0,0 +1,129 @@
+import { createClient } from "@clickhouse/client";
+import { ClickHouseContainer } from "./clickhouse-container";
+
+interface ClickHouseQueryResponse<T> {
+  data: T[];
+}
+
+describe("ClickHouseContainer", { timeout: 180_000 }, () => {
+  // connectWithOptions {
+  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();
+  });
+  // }
+
+  // connectWithUrl {
+  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();
+  });
+  // }
+
+  // connectWithUsernameAndPassword {
+  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();
+  });
+  // }
+
+  // setDatabase {
+  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();
+  });
+  // }
+
+  // setUsername {
+  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();
+  });
+  // }
+
+  it("should work with restarted container", async () => {
+    const container = await new ClickHouseContainer().start();
+    await container.restart();
+
+    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();
+  });
+});