New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Clickhouse Reference Architecture

by jeremylongshore in jeremylongshore/tons-of-skills-marketplace

Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology.

MITAuto-check: notesDatabases

Install Clickhouse Reference Architecture

skills CLI
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill clickhouse-reference-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jeremylongshore/tons-of-skills-marketplace clickhouse-reference-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/clickhouse-reference-architecture .claude/skills/clickhouse-reference-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
clickhouse-reference-architecture
GitHub stars
2.8k
Token cost
~2k tokens
SKILL.md length
561 words
Files
4 (incl. references)
Skills in repo
3,342
Repo updated
First seen
Licence
MIT

At a glance

Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology.

  • Works in 5 steps: Project Structure → Data Flow Architecture → Schema Design (3-Layer Pattern) → …
  • Designing a new ClickHouse system
  • SKILL.md covers Overview, Prerequisites, Instructions and Architecture Decision Records, plus 5 more sections
  • Calls clickhouse

What it does

Clickhouse Reference Architecture is an agent skill from jeremylongshore/tons-of-skills-marketplace. Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology. Use when designing a new ClickHouse system, reviewing an existing analytics architecture, or establishing standards for ClickHouse integrations. Trigger with "clickhouse architecture", "clickhouse project structure", "clickhouse design", "clickhouse multi-tenant", "clickhouse reference".

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including reference files (for example `references/client-module.md`, `references/multi-tenant-patterns.md` and `references/schema-design.md`). Compatibility notes: Designed for Claude Code

It sits in Databases, covering Data warehousing and Multi-tenancy. It works with ClickHouse. The repository describes itself as: Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com. The licence is MIT.

When your agent uses it

  • Designing a new ClickHouse system
  • Reviewing an existing analytics architecture
  • Establishing standards for ClickHouse integrations
  • With clickhouse architecture

Example prompts

  • “clickhouse architecture”
  • “clickhouse project structure”
  • “clickhouse design”
  • “/clickhouse-reference-architecture”

Requirements

  • Node.js
  • Docker
  • Compatibility (from SKILL.md): Designed for Claude Code
  • Pre-approved tools (allowed-tools): Read, Grep

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Project Structure
  2. Data Flow Architecture
  3. Schema Design (3-Layer Pattern)
  4. Multi-Tenant Patterns
  5. Client Module

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Grep

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • clickhouse

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • clickhouse.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Designed for Claude Code

    From compatibility in the SKILL.md frontmatter.

Context cost

Clickhouse Reference Architecture loads about 2k tokens when it runs, and up to ~3.5k if it reads all its reference files. Until then it costs about 117 tokens; SKILL.md has 561 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~117
When it runs · the whole SKILL.md, loaded when a task matches
~2k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:63
    # development / staging / production .env
  • NoteMentions a .env fileSKILL.md:200
    skill, which covers per-environment `.env` files, staging/production connection

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 561 words, ~2,002 tokens.

Download SKILL.mdSave it as .claude/skills/clickhouse-reference-architecture/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
clickhouse-reference-architecture
description
Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology. Use when designing a new ClickHouse system, reviewing an existing analytics architecture, or establishing standards for ClickHouse integrations. Trigger with "clickhouse architecture", "clickhouse project structure", "clickhouse design", "clickhouse multi-tenant", "clickhouse reference".
allowed-tools
Read, Grep
compatibility
Designed for Claude Code
version
1.7.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
saas, database, analytics, clickhouse, olap

ClickHouse Reference Architecture

Overview

Production-grade architecture for ClickHouse analytics platforms covering project layout, data flow, multi-tenancy, and operational patterns. Work through the five steps below to get the high-level shape, then drill into the linked reference files for the full DDL, client code, and tenancy trade-offs.

Prerequisites

  • Understanding of ClickHouse fundamentals — table engines, ORDER BY sort keys, and partitioning.
  • A TypeScript/Node.js project (the client examples use @clickhouse/client).
  • When reviewing an existing codebase, Grep for createClient( to locate the current client module and Read the SQL files under clickhouse/schemas/.

Instructions

Step 1: Project Structure

Keep SQL DDL as the source of truth under clickhouse/schemas/, named query functions under clickhouse/queries/, and ingestion/API/jobs in sibling modules.

my-analytics-platform/
├── src/
│   ├── clickhouse/
│   │   ├── client.ts           # Singleton client with health checks
│   │   ├── schemas/            # SQL DDL files (source of truth)
│   │   │   ├── 001-events.sql
│   │   │   ├── 002-users.sql
│   │   │   └── 003-materialized-views.sql
│   │   ├── queries/            # Named query functions
│   │   └── migrations/         # Schema migrations (runner.ts + *.sql)
│   ├── ingestion/              # webhook-receiver, kafka-consumer, buffer
│   ├── api/                    # routes.ts, middleware.ts (auth, rate limit)
│   └── jobs/                   # daily-rollup.ts, cleanup.ts (TTL enforcement)
├── tests/                      # unit/ + integration/
├── docker-compose.yml          # Local ClickHouse
├── init-db/                    # Docker init scripts
└── config/                     # development / staging / production .env
Step 2: Data Flow Architecture

Data moves in one direction: sources → a batching ingestion layer → ClickHouse (raw MergeTree → materialized views → aggregate tables) → an API that reads only the aggregate tables → dashboards.

Data Sources (Webhooks, API, Kafka, S3)
        │
Ingestion Layer (Buffer + batch, 10K+ rows/insert)
        │
ClickHouse Server
   Raw Event Tables (MergeTree, append-only)
        │  auto-aggregate on INSERT
   Materialized Views (hourly, daily, tenant-level)
        │
   Aggregate Tables (AggregatingMergeTree)
        │
API Layer (queries aggregate tables, never raw events)
        │
Dashboards / Client Apps
Step 3: Schema Design (3-Layer Pattern)

Three layers — raw append-only events, hourly aggregation, and a daily rollup for dashboards — with materialized views auto-populating each aggregate on INSERT. The essential raw-table skeleton:

sql
CREATE TABLE analytics.events_raw (
    event_id    UUID DEFAULT generateUUIDv4(),
    tenant_id   UInt32,
    event_type  LowCardinality(String),
    user_id     UInt64,
    properties  String CODEC(ZSTD(3)),
    created_at  DateTime64(3) DEFAULT now64(3)
)
ENGINE = MergeTree()
ORDER BY (tenant_id, event_type, toDate(created_at), user_id)
PARTITION BY toYYYYMM(created_at)
TTL created_at + INTERVAL 90 DAY;

Full three-layer DDL, materialized views, and the rationale: see references/schema-design.md.

Step 4: Multi-Tenant Patterns

Choose an isolation strategy. Default to Approach A (shared table, tenant_id first in ORDER BY) — it scales to 10K+ tenants:

sql
ORDER BY (tenant_id, event_type, created_at)
SELECT count() FROM events_raw WHERE tenant_id = 42;  -- scans only tenant 42

Database-per-tenant (strict isolation) and row-level security (RBAC) alternatives with trade-offs: see references/multi-tenant-patterns.md.

Step 5: Client Module

Use a singleton @clickhouse/client instance and parameterized queries that read from the aggregate tables. Full client + query-function code: references/client-module.md.

Architecture Decision Records

DecisionChoiceWhy
EngineMergeTree (raw) + AggregatingMergeTree (rollups)Best for append + pre-agg
Multi-tenantShared table + tenant_id in ORDER BYScales to 10K+ tenants
IngestionBuffer + batch INSERTAvoids "too many parts"
AggregationMaterialized views (not cron)Real-time, zero-lag
FormatJSONEachRowClient support, debugging
CompressionZSTD(3) for strings, Delta for ints10-20x compression
Show full SKILL.md (262 more words)Show less

Output

Applying this skill produces a concrete architecture plan for a ClickHouse system:

  • A project directory layout (Step 1) with DDL as the source of truth.
  • A 3-layer schema — raw MergeTree table, hourly and daily AggregatingMergeTree tables, each fed by a materialized view.
  • A chosen multi-tenant isolation strategy (shared table / database-per-tenant / row policy) with the reasoning recorded.
  • A singleton client module plus named, parameterized query functions that read only from aggregate tables.
  • A filled-in Architecture Decision Record table capturing engine, tenancy, ingestion, aggregation, format, and compression choices.

Error Handling

IssueCauseSolution
Cross-tenant data leakMissing WHERE tenant_idUse row policies or middleware
Stale dashboard dataMV not createdVerify MV exists and is attached
Schema driftManual DDL changesUse migration runner
Slow dashboard queriesQuerying raw tableQuery aggregate tables instead

Examples

Design a new multi-tenant analytics platform. Start from the Step 1 layout and the Step 3 raw-table skeleton, then open references/schema-design.md for the full three-layer DDL and references/multi-tenant-patterns.md to pick an isolation strategy.

Query a tenant dashboard from Node.js. Read from the daily rollup, not the raw table — the pattern the client module in references/client-module.md implements:

sql
SELECT date, sum(total) AS events, uniqMerge(users) AS unique_users
FROM analytics.events_daily
WHERE tenant_id = {tid:UInt32} AND date >= today() - {days:UInt32}
GROUP BY date ORDER BY date;

Review an existing ClickHouse integration. Grep for createClient( and any raw-table SELECTs in the API layer; flag queries hitting events_raw instead of an aggregate table against the Error Handling table above.

Resources

Next Steps

For multi-environment configuration, layer on the clickhouse-multi-env-setup skill, which covers per-environment .env files, staging/production connection settings, and migration promotion between environments.

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in skills/.curated/clickhouse-reference-architecture of jeremylongshore/tons-of-skills-marketplace.

  • SKILL.md
  • references/client-module.md
  • references/multi-tenant-patterns.md
  • references/schema-design.md

Open the folder on GitHubat commit cfae287

Compare with similar skills

Clickhouse Reference Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Clickhouse Reference Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Clickhouse Reference Architecture this skilljeremylongshore/tons-of-skills-marketplace2.8k—~2kAutomated safety check: NotesMIT
Keeper Stress AnalysisClickHouse/ClickHouse50k—~4.7kAutomated safety check: PassApache-2.0
Perf ComparisonClickHouse/ClickHouse50k—~3.9kAutomated safety check: NotesApache-2.0
Patch Release CheckClickHouse/ClickHouse50k—~4kAutomated safety check: NotesApache-2.0
Clickhouse Architecture Advisorvemetric/vemetric3952 repos~791Automated safety check: PassApache-2.0
Backend Dev Guidelineslitefuse/litefuse1011 repos~5.8kAutomated safety check: PassCustom licence

Similar skills

  • Keeper Stress Analysis

    ClickHouse/ClickHouse

    Analyze ClickHouse Keeper stress-test results from play.clickhouse.com / keeperstresstests data warehouse.

    50k GitHub stars~4.7k tokensUpdated today
    DatabasesAuto-check passed

  • Perf Comparison

    ClickHouse/ClickHouse

    Evaluate ClickHouse performance test results from existing CI/dashboard data or local perf.py runs.

    50k GitHub stars~3.9k tokensUpdated today
    DatabasesAuto-check: notes

  • Patch Release Check

    ClickHouse/ClickHouse

    Check whether ClickHouse's supported versions (last 3 majors + latest LTS) have recent stable patch releases, diagnose why the scheduled AutoReleases pipeline failed, and identify which releases…

    50k GitHub stars~4k tokensUpdated today
    DatabasesAuto-check: notes

  • Clickhouse Architecture Advisor

    vemetric/vemetric

    MUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system designs.

    395 GitHub starsUsed in 2 repos~791 tokens
    DatabasesAuto-check passed

  • Backend Dev Guidelines

    litefuse/litefuse

    Comprehensive backend development guide for Litefuse's Next.js 14/tRPC/Express/TypeScript monorepo.

    101 GitHub starsUsed in 1 repo~5.8k tokens
    Backend & APIsAuto-check passed

  • Decompress Binary

    ClickHouse/ClickHouse

    Extract the inner ELF from a ClickHouse self-extracting clickhouse binary, including when its architecture differs from the host (e.g.

    50k GitHub stars~1.1k tokensUpdated today
    DatabasesAuto-check passed

More from jeremylongshore/tons-of-skills-marketplace

All 3,342 skills in this repo

  • Performing Security Code Review

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to conduct a security-focused code review using the security-agent plugin.

    2.8k GitHub starsUsed in 2 repos~1.3k tokens
    Auto-check: notes

  • Adapting Transfer Learning Models

    jeremylongshore/tons-of-skills-marketplace

    Build this skill automates the adaptation of pre-trained machine learning models using transfer learning techniques.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Agent Context Loader

    jeremylongshore/tons-of-skills-marketplace

    Execute proactive auto-loading: automatically detects and loads agents.md files.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Aggregating Performance Metrics

    jeremylongshore/tons-of-skills-marketplace

    Aggregate and centralize performance metrics from applications, systems, databases, caches, and services.

    2.8k GitHub stars~1.2k tokensUpdated today
    Auto-check passed

  • Analyzing Capacity Planning

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth.

    2.8k GitHub stars~947 tokensUpdated today
    Auto-check passed

  • Analyzing Database Indexes

    jeremylongshore/tons-of-skills-marketplace

    Process use when you need to work with database indexing. An agent skill from jeremylongshore/tons-of-skills-marketplace.

    2.8k GitHub stars~2k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Clickhouse Reference Architecture

What does Clickhouse Reference Architecture do?

Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology. Clickhouse Reference Architecture is an agent skill from jeremylongshore/tons-of-skills-marketplace. Production reference architecture for ClickHouse-backed applications — project layout, data flow, multi-tenant patterns, and operational topology.

When should I use Clickhouse Reference Architecture?

Clickhouse Reference Architecture fits situations like: designing a new ClickHouse system; reviewing an existing analytics architecture; establishing standards for ClickHouse integrations; with clickhouse architecture.

How do I install Clickhouse Reference Architecture in Claude Code?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill clickhouse-reference-architecture -a claude-code`. Or copy the skill folder (skills/.curated/clickhouse-reference-architecture in jeremylongshore/tons-of-skills-marketplace) into .claude/skills/clickhouse-reference-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Clickhouse Reference Architecture in Codex?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill clickhouse-reference-architecture -a codex`. Or copy the skill folder (skills/.curated/clickhouse-reference-architecture in jeremylongshore/tons-of-skills-marketplace) into .agents/skills/clickhouse-reference-architecture in your project. Codex loads it when a task matches its description.

Can I use Clickhouse Reference Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill clickhouse-reference-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/clickhouse-reference-architecture, .gemini/skills/clickhouse-reference-architecture, .github/skills/clickhouse-reference-architecture and .opencode/skills/clickhouse-reference-architecture in your project.

What does Clickhouse Reference Architecture need to run?

Going by SKILL.md and its folder, Clickhouse Reference Architecture needs the command-line tools its instructions call (clickhouse). Our summary lists: Node.js; Docker. Its frontmatter pre-approves these tools: Read, Grep. Compatibility (from SKILL.md): Designed for Claude Code.

Does Clickhouse Reference Architecture access the network?

SKILL.md names 1 domain. As links in the text: clickhouse.com. This is read from the text; nothing was executed.

Is Clickhouse Reference Architecture safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Clickhouse Reference Architecture use?

Clickhouse Reference Architecture is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Clickhouse Reference Architecture use?

About 2k tokens (SKILL.md is roughly 8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.5k tokens, read only when the agent opens those files.

What are the alternatives to Clickhouse Reference Architecture?

Skills that share tags, products or a category with Clickhouse Reference Architecture: Keeper Stress Analysis (ClickHouse/ClickHouse, 50k stars), Perf Comparison (ClickHouse/ClickHouse, 50k stars), Patch Release Check (ClickHouse/ClickHouse, 50k stars) and Clickhouse Architecture Advisor (vemetric/vemetric, 395 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Clickhouse Reference Architecture?

jeremylongshore (a GitHub user) maintains it in jeremylongshore/tons-of-skills-marketplace, which has 2,827 GitHub stars. The repository holds 3,342 skills in this directory. The repository was last updated on October 10, 2026.

Source: jeremylongshore/tons-of-skills-marketplace on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.