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

by speakeasy-api in speakeasy-api/gram

A skill your agent uses when changing or reviewing Gram ClickHouse schemas, migrations, queries, inserts, access principals, bootstrap SQL, Cloud compatibility, partial migration failures, or…

AGPL-3.0Auto-check passedDatabases

Install Clickhouse

skills CLI
$ npx skills add speakeasy-api/gram --skill clickhouse -a claude-code

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

GitHub CLI
$ gh skill install speakeasy-api/gram clickhouse --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/speakeasy-api/gram.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/clickhouse .claude/skills/clickhouse && 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
GitHub stars
272
Token cost
~3.2k tokens
SKILL.md length
1,453 words
Files
1
Skills in repo
39
Repo updated
First seen
Licence
AGPL-3.0

At a glance

A skill your agent uses when changing or reviewing Gram ClickHouse schemas, migrations, queries, inserts, access principals, bootstrap SQL, Cloud compatibility, partial migration failures, or…

  • Works in 3 steps: Create a params struct for query inputs → Build the query using squirrel (the sq… → Use pagination helpers from pagination.go
  • Reviewing Gram ClickHouse schemas
  • SKILL.md covers Official ClickHouse guidance, Infrastructure ownership and…, Partially applied migrations and Schema design and evolution, plus 1 more section
  • Calls mise

What it does

Clickhouse is an agent skill from speakeasy-api/gram. Use when changing or reviewing Gram ClickHouse schemas, migrations, queries, inserts, access principals, bootstrap SQL, Cloud compatibility, partial migration failures, or performance for analytics, telemetry, risk, authz, and spend features

Its SKILL.md is about 3.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases, covering Data warehousing. It works with ClickHouse and SQL. The repository describes itself as: Securely scale AI usage across your organization. A single stack to Connect, Secure, Observe and Distribute agents, MCPs, and Skills within your company. The licence is AGPL-3.0.

When your agent uses it

  • Reviewing Gram ClickHouse schemas
  • Access principals
  • Cloud compatibility
  • Partial migration failures

Example prompts

  • “/clickhouse”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Create a params struct for query inputs
  2. Build the query using squirrel (the sq var in queries.sql.go is pre-configured for ClickHouse)
  3. Use pagination helpers from pagination.go

What it can do on your machine

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

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • mise

    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.

Context cost

Clickhouse loads about 3.2k tokens when it runs. Until then it costs about 63 tokens; SKILL.md has 1,453 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~63
When it runs · the whole SKILL.md, loaded when a task matches
~3.2k

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 passed

The automated check found no risky patterns in SKILL.md.

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 speakeasy-api/gram at commit ad78247, republished under its AGPL-3.0 licence (© speakeasy-api). 1,453 words, ~3,233 tokens.

Download SKILL.mdSave it as .claude/skills/clickhouse/SKILL.md (or your agent's skills folder).
name
clickhouse
description
Use when changing or reviewing Gram ClickHouse schemas, migrations, queries, inserts, access principals, bootstrap SQL, Cloud compatibility, partial migration failures, or performance for analytics, telemetry, risk, authz, and spend features

Official ClickHouse guidance

Gram conventions and the checked-in schema remain authoritative. Also use:

  • clickhouse-best-practices when reviewing or changing a ClickHouse schema, query, insert strategy, or configuration. Read its applicable rule files and cite the rules in review findings.
  • clickhouse-architecture-advisor when choosing between ingestion patterns, raw tables and materialized views, partitioning or retention strategies, joins or enrichment, or mutable-state models.

Infrastructure ownership and Cloud compatibility

Local ClickHouse success is not proof of ClickHouse Cloud compatibility. Local containers and CI accept DDL and authentication settings that Cloud rejects.

ObjectOwner
Databases, users, roles, credentials, role settingsTerraform; never application schema migrations
Tables, views, materialized views, schema-bound grants/revokesAtlas migrations, mirrored in golang-migrate
Local/CI/Atlas development-database prerequisiteslocal/clickhouse/initdb/01-marts-definer.sql

Provision infrastructure prerequisites before applying dependent migrations. Do not put CREATE DATABASE, CREATE USER, or CREATE ROLE into desired schema files or either migration flavor, or drop infrastructure-owned objects in down migrations. If generation proposes these statements, fix the bootstrap/baseline and regenerate; do not accept them just because local replay passes.

Cloud footguns:

  • CREATE DATABASE ... ENGINE = Atomic is not supported in ClickHouse Cloud. Do not explicitly select the local database engine for Cloud.
  • CREATE USER ... HOST NONE without authentication is still a passwordless user definition. Cloud's default policy rejects it; HOST NONE does not waive the password requirement. Never relax that policy to accommodate a definer.
  • Provision Cloud definers through Terraform with a generated password that is not exposed to people, logs, outputs, or this repository. A definer does not need an interactive login, but still needs valid authentication configuration.

Local bootstrap is an exception, not a deployment template. 01-marts-definer.sql supplies the marts database, marts_reader role/limits, and marts_definer principal to local containers, CI replay, and Atlas's development database (server/atlas.hcl). Keep it idempotent. Its passwordless HOST NONE user is local-only; never copy it into Cloud provisioning or migrations.

For marts, edit server/clickhouse/mart.sql. Views use DEFINER = marts_definer SQL SECURITY DEFINER: reads of underlying tables run with the definer's privileges, not the reader's. Migrations own the definer's narrowly scoped source grants and the reader's grants on approved views, not the principals. Atlas ignores grants in desired state, so keep explicit matching grants/revokes in both migration flavors. See ClickHouse view SQL security.

Partially applied migrations

ClickHouse migrations can fail after earlier statements have taken effect. Editing the failed file and rehashing does not reconcile those effects with Atlas's recorded progress; repeated in-place edits can leave the runner stuck.

  • Treat published/applied migration files as immutable during normal development. Use a forward migration; if a failed revision prevents progress, recovery requires an explicit operator-controlled repair, not another automatic retry.
  • Before repair, stop concurrent migration/reconciliation attempts and inspect both the actual objects/grants and Atlas revision state. Identify the exact corrected migration artifact and which statements already ran.
  • Reconcile the database to that artifact deliberately. Rewinding with atlas migrate set changes revision bookkeeping; it does not undo SQL. Only consider rewinding to the preceding revision and applying one migration after proving every statement is safe to replay and accounting for existing effects. IF NOT EXISTS alone does not prove existing objects have the intended definition.
  • Verify database state and migration status before resuming automated reconciliation. Never blindly rewind, mark a failed migration applied, or clear its error to bypass unfinished work.

Schema design and evolution

The ClickHouse schema is defined in server/clickhouse/schema.sql, with marts views in server/clickhouse/mart.sql. Edit the relevant desired schema file and generate a migration:

sh
mise run clickhouse:diff <migration-name>

This produces migrations in two flavors that must always stay in sync:

  • server/clickhouse/migrations/ — Atlas format. This is the source of truth: only these migrations are carried forward and applied in production.
  • server/clickhouse/local/golang_migrate/ — golang-migrate format (.up.sql/.down.sql pairs). Used only for local development, so contributors without an Atlas Pro login can still run migrations.

mise run clickhouse:diff generates both flavors together. When adjusting a newly generated, unpublished migration (for example, adding grants Atlas ignores), make the equivalent change in both directories, then run mise run clickhouse:hash to regenerate atlas.sum. Hashing updates checksums, not database or revision state. Apply pending migrations locally with mise run clickhouse:migrate.

No semicolons in COMMENT '...' strings. golang-migrate splits statements naively, so a semicolon inside a column/table comment breaks its parser and the local migrations fail to replay. Rephrase the comment instead.

Three CI checks guard this on every PR:

  • atlas-lint — runs the Atlas migration linter, plus a porcelain check that migrations were generated and are up to date with both the Postgres and ClickHouse schemas. If you edited schema.sql without running mise run clickhouse:diff, this fails.
  • golang-migrate-clickhouse — replays all golang-migrate migrations against a real ClickHouse instance to prove they're valid. If the two flavors drifted, this is where it shows up.
  • migration-order — fails if a newly added migration in either ClickHouse dir (server/clickhouse/migrations or server/clickhouse/local/golang_migrate) has a timestamp at or before the latest already on main. It also runs in the merge queue, so two PRs branched from the same head cannot both land and produce non-linear history (the INC-418 failure mode).

Out-of-order timestamps. If migration-order reports a ClickHouse migration timestamp at or before the latest on main, do not rename files, hand-edit atlas.sum, or run atlas migrate rebase. Delete the generated Atlas migration and both matching golang-migrate .up.sql/.down.sql files, identified by migration name; update from main; then re-run mise run clickhouse:diff <name>. That regenerates both flavors on top with fresh, ordered timestamps and keeps them in sync. Avoid atlas migrate rebase: it renames only one dir (drifting the two flavors apart) and, for golang-migrate, moves an already-applied migration to a higher version so migrate up silently skips it on teammates' local databases.

Show full SKILL.md (595 more words)Show less

ClickHouse Queries (Telemetry Package)

The server/internal/telemetry package uses ClickHouse for high-performance analytics queries. Unlike PostgreSQL queries, ClickHouse queries are not auto-generated by SQLc. The telemetry repository uses Squirrel for dynamic query construction.

CRITICAL: Squirrel is permitted for ClickHouse repository code, including packages outside telemetry. Never use it for PostgreSQL queries; PostgreSQL repositories must use SQLc-generated code. Follow the target ClickHouse package's neighboring query and scan patterns.

Read from summary views, not raw telemetry_logs

The pre-aggregated materialized views are the default read path for anything that powers a dashboard, analytics surface, or filter control: trace_summaries, metrics_summaries, attribute_metrics_summaries, attribute_keys, chat_token_summaries. Query the raw telemetry_logs table only in the rare cases where per-log detail is genuinely required:

  • individual log records / a single trace's full log list (detail/inspection views),
  • free-text search over the log body,
  • arbitrary user-supplied attribute-path filters (e.g. @user.region) that a fixed-column summary cannot express,
  • an event shape not yet captured by any summary (e.g. traceless trigger events).

Why it matters: raw telemetry_logs reads are full-range table scans with per-row JSON extraction; the summary views are pre-aggregated and cheap. A filter dropdown, summary card, count, or default list that scans raw logs on every page load is a performance bug — the unified Tool Logs page regressed exactly this way before being moved back onto trace_summaries. If a summary is missing a column you need, prefer extending the MV (+ a backfill migration) over falling back to a raw-log scan.

Reading trace_summaries (one row per trace_id, AggregatingMergeTree): GROUP BY trace_id, use *Merge combinators for AggregateFunction columns (anyIfMerge(http_status_code)) and plain any()/min()/sum()/max() for SimpleAggregateFunction columns. Tool calls carry a real trace_id (recorded by the gateway in ToolProxy.Do), so hosted MCP, shadow MCP, skill, and local tool events are all present in the view.

Gotcha — ILLEGAL_AGGREGATION (code 184): when a grouped read is wrapped in a CTE/subquery that a caller then aggregates over (e.g. uniqExact(tool_name) over a WITH normalized_events AS (... GROUP BY trace_id ...)), ClickHouse merges the subquery back into the outer aggregate if an aggregate alias shadows a base column (any(gram_urn) AS gram_urn). Alias grouped aggregates to non-colliding names — prefix them, e.g. any(gram_urn) AS g_gram_urn — so the boundary holds.

File Structure
  • queries.sql.go: Query implementations using squirrel
  • pagination.go: Cursor pagination helpers (withPagination, withOrdering, etc.)
  • README.md: Detailed documentation and patterns specific to ClickHouse
Adding ClickHouse Queries

When asked to add a new ClickHouse query to the telemetry package:

  1. Create a params struct for query inputs

  2. Build the query using squirrel (the sq var in queries.sql.go is pre-configured for ClickHouse):

    go
    type GetMetricsParams struct {
    ProjectID    string
    DeploymentID string  // optional
    Limit        int
}

func (q *Queries) GetMetrics(ctx context.Context, arg GetMetricsParams) ([]Metric, error) {
    sb := sq.Select("id", "value", "timestamp").
        From("metrics").
        Where("project_id = ?", arg.ProjectID)

    // Optional filters - explicit conditionals for clarity
    if arg.DeploymentID != "" {
        sb = sb.Where(squirrel.Eq{"deployment_id": arg.DeploymentID})
    }

    sb = sb.Limit(uint64(arg.Limit))

    query, args, err := sb.ToSql()
    if err != nil {
        return nil, fmt.Errorf("building query: %w", err)
    }

    rows, err := q.conn.Query(ctx, query, args...)
    // ... handle rows
}

  3. Use pagination helpers from pagination.go:

    • withPagination(sb, cursor, sortOrder) - cursor pagination
    • withOrdering(sb, sortOrder, primaryCol, secondaryCol) - ORDER BY
Testing ClickHouse Queries
  • Use the target package's existing ClickHouse fixture pattern (testenv.Launch or testenv.NewTestClickhouse) and a real ClickHouse container.
  • For async_insert=0, read directly after the insert.
  • For async_insert=1, wait_for_async_insert=1, read directly after the insert returns.
  • For async_insert=1, wait_for_async_insert=0, call testenv.FlushClickHouseAsyncInserts(t, conn) after the application issues the write and before reading. Synchronize any application goroutine first; do not use time.Sleep or polling to wait for the async queue.
  • Do not use clickhouse.WithAsync(false) to request synchronous insertion: it enables fire-and-forget async inserts. Omit async options or set async_insert=0 explicitly.
  • Use table-driven tests with descriptive it-prefix names and helper functions for test data insertion.

See server/internal/telemetry/README.md for comprehensive documentation.

© speakeasy-api, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/clickhouse of speakeasy-api/gram.

Open the folder on GitHubat commit ad78247

Compare with similar skills

Clickhouse 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 compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Clickhouse this skillspeakeasy-api/gram272—~3.2kAutomated safety check: PassAGPL-3.0
Clickhouse Logs Queriessupabase/supabase111k—~2.4kAutomated safety check: PassApache-2.0
Chdb SQLvemetric/vemetric3941 repos~1.2kAutomated safety check: PassApache-2.0
BisectClickHouse/ClickHouse50k—~1.4kAutomated safety check: PassApache-2.0
Clickhouse System QueriesFrankChen021/datastoria327—~731Automated safety check: PassCustom licence
Webapp Buildersidequery/sidemantic129—~5.5kAutomated safety check: PassAGPL-3.0

Similar skills

  • Clickhouse Logs Queries

    supabase/supabase

    Official

    Write, review, and migrate Supabase logs queries against the ClickHouse-backed logs table (the logs.all.otel analytics endpoint).

    111k GitHub stars~2.4k tokensUpdated today
    DatabasesAuto-check passed

  • Chdb SQL

    vemetric/vemetric

    A skill your agent uses when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse…

    394 GitHub starsUsed in 1 repo~1.2k tokens
    DatabasesAuto-check passed

  • Bisect

    ClickHouse/ClickHouse

    Bisect a ClickHouse regression using pre-built master binaries from CI.

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

  • Clickhouse System Queries

    FrankChen021/datastoria

    Query ClickHouse system tables to inspect query logs, monitor cluster health, check replication status, and analyze slow queries.

    327 GitHub stars~731 tokensUpdated 2 mo ago
    DatabasesAuto-check passed

  • Webapp Builder

    sidequery/sidemantic

    Build interactive analytics webapps, demos, dashboards, or embedded app surfaces from Sidemantic semantic models using copyable component primitives and deterministic query inspection.

    129 GitHub stars~5.5k tokensUpdated yesterday
    DatabasesAuto-check passed

  • Cpu Profile

    ClickHouse/ClickHouse

    Profile a ClickHouse query using the sampling query profiler and system.tracelog.

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

More from speakeasy-api/gram

All 39 skills in this repo

  • Gram Playwright CLI

    speakeasy-api/gram

    A skill your agent uses when automating the Gram dashboard in a browser, capturing screenshots, inspecting pages.

    272 GitHub stars~3.4k tokensUpdated today
    Auto-check passed

  • Transactional Email

    speakeasy-api/gram

    A skill your agent uses when adding, changing, restyling, reviewing, validating, or previewing a Gram/Speakeasy transactional email, in Go or in LMX/MJML — a template<name.go, a TemplateKey…

    272 GitHub stars~4.7k tokensUpdated today
    Auto-check passed

  • Admin Shadcn

    speakeasy-api/gram

    A skill your agent uses when adding, changing, or styling UI in client/admin (the Gram admin dashboard) that touches shadcn/ui — a button, dialog, table, sidebar, badge, select, tabs, tooltip, card…

    272 GitHub stars~1k tokensUpdated today
    Auto-check passed

  • Authoring Platform MCP Skills

    speakeasy-api/gram

    A skill your agent uses when adding, editing, reviewing, testing, or locating a reviewed skill distributed with the Platform MCP plugin; triggers include "Platform MCP skill", "platformmcpskills"…

    272 GitHub stars~2.2k tokensUpdated today
    Auto-check passed

  • Feature Flag

    speakeasy-api/gram

    A skill your agent uses when gating a feature behind a flag, dogfooding or gradually rolling out a change, choosing between productfeatures and PostHog feature flags, adding or checking a product…

    272 GitHub stars~2.6k tokensUpdated today
    Auto-check passed

  • Gram Pubsub Python

    speakeasy-api/gram

    How to build and run GCP Pub/Sub stream subscribers in Python under pystreams/ — the multi command (start at pystreams/src/pystreams/cmd/multi.py), the graminfra.pubsub publisher/subscriber library…

    272 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Clickhouse

What does Clickhouse do?

A skill your agent uses when changing or reviewing Gram ClickHouse schemas, migrations, queries, inserts, access principals, bootstrap SQL, Cloud compatibility, partial migration failures, or…. Clickhouse is an agent skill from speakeasy-api/gram.

When should I use Clickhouse?

Clickhouse fits situations like: reviewing Gram ClickHouse schemas; access principals; cloud compatibility; partial migration failures.

How do I install Clickhouse in Claude Code?

Run `npx skills add speakeasy-api/gram --skill clickhouse -a claude-code`. Or copy the skill folder (.agents/skills/clickhouse in speakeasy-api/gram) into .claude/skills/clickhouse in your project. Claude Code loads it when a task matches its description.

How do I install Clickhouse in Codex?

Run `npx skills add speakeasy-api/gram --skill clickhouse -a codex`. Or copy the skill folder (.agents/skills/clickhouse in speakeasy-api/gram) into .agents/skills/clickhouse in your project. Codex loads it when a task matches its description.

Can I use Clickhouse 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 speakeasy-api/gram --skill clickhouse -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, .gemini/skills/clickhouse, .github/skills/clickhouse and .opencode/skills/clickhouse in your project.

What does Clickhouse need to run?

Going by SKILL.md and its folder, Clickhouse needs the command-line tools its instructions call (mise).

Does Clickhouse 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 safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Clickhouse use?

Clickhouse is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Clickhouse use?

About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Clickhouse?

Skills that share tags, products or a category with Clickhouse: Clickhouse Logs Queries (supabase/supabase, 111k stars), Chdb SQL (vemetric/vemetric, 394 stars), Bisect (ClickHouse/ClickHouse, 50k stars) and Clickhouse System Queries (FrankChen021/datastoria, 327 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Clickhouse?

speakeasy-api (a GitHub organization) maintains it in speakeasy-api/gram, which has 272 GitHub stars. The repository holds 39 skills in this directory. The repository was last updated on October 8, 2026.

Source: speakeasy-api/gram on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.