ClickFlow

ClickFlow is the developer-friendly ClickHouse client for TypeScript. It simplifies high-performance OLAP workloads with typed schemas, robust migrations, and native NestJS integration.

Unlike traditional ORMs, ClickFlow follows a SQL-first philosophy. It doesn't attempt to mimic relational primitives (save, update, delete), but instead provides the necessary tools to harness the real power of ClickHouse: typed schemas, robust migrations, and efficient ingestion buffers.

Key Features

• 🚀 SQL-first: Full control over your queries without heavy ORM abstractions.
• 🏗️ Typed Schemas: Define tables and materialized views with TypeScript type safety.
• 📦 Modular Monorepo: Decoupled packages for the core engine and NestJS integration.
• 🔄 Migrations: Built-in system to manage your data schema evolution.
• 📥 Ingest Buffers: Optimized for high-volume data insertion.
• 🧩 NestJS Integration: Native module for clean and easy dependency injection.

Packages

Package	Description
@kerobit/clickflow-core	Core client, safe sql templates, defineTable, migrations, and read helpers (find, count, exists).
@kerobit/clickflow-nest	NestJS integration via ClickFlowModule, dedicated injectors, and services.

Development

Prerequisites

• pnpm (version 9+)
• Node.js (version 20+)

Useful Commands

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run linters
pnpm lint

# Run unit tests
pnpm test

Integration tests

Specs live under packages/core/tests/integration/. Defaults (CLICKFLOW_TEST_URL, database, user, password) are centralized in packages/core/tests/integration/config.ts and applied via vitest.integration.config.ts.

When you run pnpm test:integration, Vitest global setup starts the repo’s compose.test.yaml (host port 39487) and tears it down after the run—unless CI=true (GitHub Actions already provides ClickHouse) or CLICKFLOW_TEST_SKIP_DOCKER=1 (use your own server; still waits until /ping succeeds).

pnpm test:integration

Documentation

• Architecture & Design Principles
• Core Package Guide
• NestJS Integration Guide

CI/CD

We use GitHub Actions to ensure code quality through automated build, lint, unit test, and integration test processes against a real ClickHouse instance. See the workflow in .github/workflows/ci.yml.

Roadmap

• Query Builder subset support.
• Zod integration as a peer dependency for validation.
• OpenTelemetry support (observability).
• Richer DDL (TTL, engine settings).
• Migration rollback hardening.

---

Built with ❤️ by Kerobit.