ClickHouse CI Integration

Overview

Run integration tests against a real ClickHouse server in GitHub Actions using Docker service containers. No mocks needed for schema and query validation — the workflow spins up clickhouse/clickhouse-server, applies your schema, and runs unit + integration tests against the live instance.

This skill produces four artifacts: a GitHub Actions workflow, a shared test setup, integration/schema test files, and the package.json scripts that tie them together. SKILL.md gives you the workflow skeleton and the moving parts; the full copy-paste-ready test harness lives in references/implementation.md and references/examples.md.

Prerequisites

• GitHub repository with Actions enabled
• @clickhouse/client in project dependencies
• Test suite (vitest or jest)

Instructions

Read any existing .github/workflows/ and package.json first, then create or edit the four artifacts below.

Step 1: Add the workflow with a ClickHouse service container

Create .github/workflows/clickhouse-tests.yml. The core is a services.clickhouse block with a health check plus a schema-apply step before tests run:

services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    ports: ["8123:8123", "9000:9000"]
    options: >-
      --health-cmd "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1"
      --health-interval 10s --health-timeout 5s --health-retries 5

Full workflow (checkout, Node setup, npm ci, schema-apply loop, unit + integration steps, and credential handling): references/implementation.md Step 1.

Step 2: Wire the shared test setup

Add tests/setup-integration.ts — it creates a @clickhouse/client, pings on beforeAll to fail fast if the service is unreachable, TRUNCATEs between tests, and closes on afterAll. See references/implementation.md Step 2 for the file.

Step 3: Write the integration and schema tests

Add tests/events.integration.test.ts (insert → aggregate → assert, plus parameterized-query and empty-result cases) and tests/schema.integration.test.ts (asserts column types + table engine via system.columns / system.tables). Both files: references/examples.md.

Step 4: Add package scripts and (optionally) a version matrix

Edit package.json to add test, test:integration, and test:ci scripts. To catch behavioral drift before a server upgrade, add a strategy.matrix over several clickhouse-version values. Both: references/implementation.md Steps 3–4.

Output

Running this skill leaves the repository with:

• .github/workflows/clickhouse-tests.yml — CI job with a ClickHouse service container
• tests/setup-integration.ts — shared client + per-test cleanup
• tests/events.integration.test.ts — query/insert behavior tests
• tests/schema.integration.test.ts — column-type + engine assertions
• Updated package.json scripts (test, test:integration, test:ci)

On push/PR, the workflow reports pass/fail per job; with the matrix, one job per ClickHouse version. Coverage and JUnit output are emitted for CI reporting.

Error Handling

Issue	Cause	Solution
Service not healthy	Slow container start	Increase health-retries
Schema not found	Init scripts not run	Run schema step before tests
Flaky test order	Shared state	Use beforeEach with TRUNCATE
Port conflict	Another process	Use random port mapping

Examples

Minimal integration-test shape — insert rows, aggregate, assert:

await client.insert({ table: 'events', values: rows, format: 'JSONEachRow' });
const rs = await client.query({
  query: 'SELECT event_type, count() AS cnt FROM events GROUP BY event_type',
  format: 'JSONEachRow',
});
expect(await rs.json()).toHaveLength(2);

Full, runnable example files — the events integration suite (aggregation, parameterized-query injection guard, empty-result handling) and the schema validation suite (column types + MergeTree engine assertions) — are in references/examples.md.

Resources

• GitHub Actions Service Containers
• ClickHouse Docker Image
• Vitest Documentation
• references/implementation.md — full workflow, test setup, package scripts, version matrix
• references/examples.md — complete integration + schema test files

Next Steps

For deployment patterns, see the clickhouse-deploy-integration skill, which covers migration ordering and production rollout once your CI suite is green.