clickhousectl-local-dev

chore(deps): bump @vitest/mocker and vitest in /skills/clickhouse-js-node-rowbinary (#47) Bumps [@vitest/mocker](https://github.com/vitest-dev/vitest/tree/HEAD/packages/mocker) to 4.1.11 and updates ancestor dependency [vitest](https://github.com/vitest-dev/vitest/tree/HEAD/packages/vitest). These dependencies need to be updated together. Updates `@vitest/mocker` from 4.1.9 to 4.1.11 Release notes Sourced from @​vitest/mocker's releases. v4.1.11    🐞 Bug Fixes Revive global concurrency limit for test lifecycle [backport to v4]  -  by @​sheremet-va and @​hi-ogawa in vitest-dev/vitest#10992 (5146d) browser: Encode iframeId in tester iframe URL [backport to v4]  -  by @​sheremet-va, Pduhard and Claude Opus 4.8 in vitest-dev/vitest#10955 (10b2c) Trigger playwright/chromium gc on lower disk availability [backport to v4]  -  by @​hi-ogawa, Hiroshi Ogawa and OpenCode in vitest-dev/vitest#10951 (9851d) mocker: Restrict redirect mocks to the fs allowlist [backport to v4]  -  by @​sheremet-va in vitest-dev/vitest#10974 (fe5a1)     View changes on GitHub v4.1.10    🐞 Bug Fixes browser: Check fs access in builtin commands [backport to v4]  -  by @​hi-ogawa, Hiroshi Ogawa and OpenCode (claude-opus-4-8) in vitest-dev/vitest#10680 (5c18d) vm: Fix external module resolve error with deps optimizer query for encoded URI [backport to v4]  -  by @​SveLil and @​hi-ogawa in vitest-dev/vitest#10661 (bae52)     View changes on GitHub Commits 9bd8d46 chore: release v4.1.11 (#10995) fe5a11d fix(mocker): restrict redirect mocks to the fs allowlist [backport to v4] (#1... db616d2 chore: release v4.1.10 (#10718) See full diff in compare view Updates `vitest` from 4.1.9 to 4.1.11 Release notes Sourced from vitest's releases. v4.1.11    🐞 Bug Fixes Revive global concurrency limit for test lifecycle [backport to v4]  -  by @​sheremet-va and @​hi-ogawa in vitest-dev/vitest#10992 (5146d) browser: Encode iframeId in tester iframe URL [backport to v4]  -  by @​sheremet-va, Pduhard and Claude Opus 4.8 in vitest-dev/vitest#10955 (10b2c) Trigger playwright/chromium gc on lower disk availability [backport to v4]  -  by @​hi-ogawa, Hiroshi Ogawa and OpenCode in vitest-dev/vitest#10951 (9851d) mocker: Restrict redirect mocks to the fs allowlist [backport to v4]  -  by @​sheremet-va in vitest-dev/vitest#10974 (fe5a1)     View changes on GitHub v4.1.10    🐞 Bug Fixes browser: Check fs access in builtin commands [backport to v4]  -  by @​hi-ogawa, Hiroshi Ogawa and OpenCode (claude-opus-4-8) in vitest-dev/vitest#10680 (5c18d) vm: Fix external module resolve error with deps optimizer query for encoded URI [backport to v4]  -  by @​SveLil and @​hi-ogawa in vitest-dev/vitest#10661 (bae52)     View changes on GitHub Commits 9bd8d46 chore: release v4.1.11 (#10995) 9851dbc fix(browser): trigger playwright/chromium gc on lower disk availability [back... db616d2 chore: release v4.1.10 (#10718) bae52b5 fix(vm): fix external module resolve error with deps optimizer query for enco... See full diff in compare view Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- Dependabot commands and options You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/ClickHouse/agent-skills/network/alerts). Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot]

chore(deps-dev): bump postcss from 8.5.15 to 8.5.25 in /skills/clickhouse-js-node-rowbinary (#44)

Add infra-postgres and infra-clickhouse skills (#43) ## Summary Adds two `clickhousectl`-based infra skills in a normalized format, where each skill has a thin `SKILL.md` with a local-vs-cloud decision tree that routes to `ref/local.md` and `ref/cloud.md`, and the local workflow hands off to cloud when going to production. ### infra-postgres (new) - `ref/local.md` — Docker-backed local Postgres for development: start, psql client (host psql or Docker-exec fallback), `.env` wiring via `dotenv`, lifecycle (stop/remove). Verified end-to-end against clickhousectl 0.3.1 (container start, SQL, dotenv, list, stop, remove); example JSON output captured from real runs. - `ref/cloud.md` — managed ClickHouse Cloud Postgres services (beta): API-key auth, service creation, connections and TLS certs, runtime config (pgConfig/pgBouncerConfig), read replicas, promote/switchover, point-in-time restore. ### infra-clickhouse (merges clickhousectl-local-dev + clickhousectl-cloud-deploy) - Same structure: `ref/local.md` carries the local dev workflow, `ref/cloud.md` the ClickHouse Cloud deployment workflow. - Fixes a stale command from the old cloud-deploy skill: `clickhousectl cloud login` no longer exists in 0.3.1 — it's `clickhousectl cloud auth login`. - The superseded `clickhousectl-local-dev` and `clickhousectl-cloud-deploy` directories are removed. ### Registration - README: new "Infra ClickHouse" and "Infra Postgres" sections replace the two clickhousectl sections; Quick Start bullets updated. - `.claude-plugin/marketplace.json`: entries for both new skills; superseded entries removed. - `.claude-plugin/plugin.json`: skills array updated accordingly. ### Descriptions Frontmatter descriptions follow the [Agent Skills authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): third person, capabilities first, then "Use when …" trigger contexts using the vocabulary users actually say (Postgres/PostgreSQL, psql, deploy to ClickHouse Cloud), with both the local and cloud cases explicit. ## Test plan - [x] Local Postgres workflow run end-to-end with clickhousectl 0.3.1 (start → query → dotenv → list → stop → remove) - [x] Cloud command surface verified against `clickhousectl cloud postgres`/`cloud service`/`cloud auth` `--help` output - [x] All JSON files validate; no remaining references to the removed skill names outside intentional "supersedes" notes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5

Add clickstack-otel-collector skill (#42) ## Summary Transfers Dale's `clickstack-otel-collector` skill (v0.6.0) into this repo from [clickhouse-docs](https://github.com/ClickHouse/clickhouse-docs/pull/6367), where it was previously maintained. Co-authored-by: Claude Fable 5

Register clickhousectl skills in README and Claude plugin manifests (#41) ## Summary The `clickhousectl-local-dev` and `clickhousectl-cloud-deploy` skills were added under `skills/` (#32) but were never registered anywhere discoverable: - **README.md** — added both skills to the *Available Skills* section (matching the style of the existing entries) and added two Quick Start bullets - **.claude-plugin/marketplace.json** — added plugin entries for both skills (version `0.2.0`, matching their SKILL.md metadata) - **.claude-plugin/plugin.json** — appended both skill paths to the `skills` array This follows the same registration pattern used for the chdb skills in #35. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5

Sync JS skills and add clickhouse-js-node-rowbinary skill (#40) ## Summary - Adds a new `clickhouse-js-node-rowbinary` skill: RowBinary readers/writers for the ClickHouse JS client, with reference docs, examples, case studies, benchmarks, and a full test suite. - Syncs existing JS skills (`clickhouse-js-node-coding`, `clickhouse-js-node-troubleshooting`) with updated reference docs and SKILL.md content. ## Changes - **New skill** `clickhouse-js-node-rowbinary` — readers/writers for all RowBinary data types, streaming support, case studies (IoT, ledger, logs, WASM-vs-JS), and benchmarks. - **Updated** `clickhouse-js-node-coding` reference docs (data types, formats, compression, query parameters, sessions, etc.). - **Updated** `clickhouse-js-node-troubleshooting` reference docs (TLS, compression, query params, socket hangup, format clause, etc.). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context)

Add clickhouse-managed-postgres-rca skill (#37) A Claude skill for evidence-based RCA on ClickHouse-managed Postgres. Workflow: 1. OpenAPI discovery (cached 24h) — fetches the live spec, locates `slowQueryPatternsGetList` and `postgresInstancePrometheusGet` by `operationId`, builds a session role map from schema descriptions. 2. Single Prom scrape for system gauges. 3. Slow Query Patterns pull for per-pattern evidence. 4. Triage against a heuristic library (v0.1: full scan, hot loop, write congestion). 5. Structured recommendation: symptom → evidence → hypothesis → fix → long-term follow-ups. 6. Recommend-only by contract — never executes DDL, never kills queries. Co-Authored-By: Deepak Divya Tejaswi Co-Authored-By: Claude Opus 4.7 (1M context) Co-Authored-By: Claude Opus 4.8 (1M context) Co-Authored-By: Claude Opus 4.6 (1M context)

Use `local use` to put the clickhouse binary on PATH (#38) Updates the `clickhousectl-local-dev` skill to use `clickhousectl local use latest` for setup. Unlike `local install`, `local use` symlinks the binary into `~/.local/bin`, so `clickhouse` is available directly on PATH (e.g. `clickhouse client`). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context)

Register chdb-datastore and chdb-sql skills and sync descriptions (#35)

Add `clickhouse-js-node-coding` skill (#36) Forwarding from https://github.com/ClickHouse/clickhouse-js/tree/main/skills/clickhouse-js-node-coding

fix version in clickhouse-best-practices (#31) updated to match the version in the actual skill

Fix yaml syntax (#33) Escape semicolon to avoid error (including error in GitHub UI)

update clickhousectl skills for v0.2.0 (#32) ## Summary Bumps both `clickhousectl` skills to v0.2. **clickhousectl-cloud-deploy (v0.2.0)** - Switch from the deprecated `cloud service client` to `cloud service query` for all SQL execution. - Drop the OAuth/browser-login auth path — API key (Admin role) only, since every step in this flow requires a write-capable key. - New Step 6: create a dedicated `app_user` via `cloud service query`, generate a random password, and persist credentials to `.env` before the user is created so the password is never lost on partial failure. - Capture the HTTPS host and port from `service create` straight into `.env`; no follow-up `service get`. - Drop per-driver connection-string examples in favour of a one-line wrap-up — credentials are already in `.env`. **clickhousectl-local-dev (v0.2.0)** - Mention `clickhousectl skills` for installing the latest ClickHouse Agent Skills. - Update example version specifiers to `26.4` / `26.4.2.10`. - Drop a stale note about the server data path. --------- Co-authored-by: Claude Opus 4.7 (1M context)

Promote clickhouse-js-node-troubleshooting to top-level skill (#29) ## Why Installers/agents look one level deep. The npx skills add CLI and the agent skill directories listed in the README (.claude/skills/, .cursor/skills/, .github/skills/, etc.) expect each skill as a direct child of skills/. A nested skills/clickhouse-client-js/clickhouse-js-node-troubleshooting/ will not be picked up by those scanners. --- - [x] Promote `skills/clickhouse-client-js/clickhouse-js-node-troubleshooting/` to top-level `skills/clickhouse-js-node-troubleshooting/` - [x] Remove empty `skills/clickhouse-client-js/` wrapper directory - [x] Add an entry for the skill under "Available Skills" in `README.md` - [x] Add `./skills/clickhouse-js-node-troubleshooting/` to the `skills` array in `.claude-plugin/plugin.json` - [x] Add a plugin entry for the skill in `.claude-plugin/marketplace.json` --------- Co-authored-by: copilot-swe-agent[bot] Co-authored-by: peter-leonov-ch Co-authored-by: Peter Leonov

docs(best-practices): mention lightweight UPDATE in avoid-update rule (#27) https://github.com/ClickHouse/agent-skills/issues/26 ## Summary - Restructure the `avoid ALTER TABLE UPDATE` rule to mirror the `avoid ALTER TABLE DELETE` rule - Add a lightweight UPDATE (25.7+) alternative alongside ReplacingMergeTree - Add an update strategy comparison table ## Test plan - [ ] Render the rule and confirm formatting matches `insert-mutation-avoid-delete.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context)

use the exact team name instead of a super team (#30) Fix for: * https://github.com/ClickHouse/agent-skills/pull/28

Add JS client Node.js troubleshooting skill (#25) Source: * https://github.com/ClickHouse/clickhouse-js/tree/main/skills/clickhouse-js-node-troubleshooting --------- Co-authored-by: copilot-swe-agent[bot] Co-authored-by: peter-leonov-ch

Add ClickHouse/integrations team to CODEOWNERS (#28) The `@ClickHouse/integrations` team needs review ownership across the repository. - **`.github/CODEOWNERS`**: Added `@ClickHouse/integrations` to the global owners line alongside `@ClickHouse/ai-ml`. ``` * @ClickHouse/ai-ml @ClickHouse/integrations ``` Co-authored-by: copilot-swe-agent[bot] Co-authored-by: peter-leonov-ch

Add agent connectivity and query workflow rules (#23) ## Summary Adds 6 new rules (28 → 34 total) covering how AI agents should connect to, discover, and safely query ClickHouse. **Motivation:** Customer feedback that connecting AI agents to ClickHouse "required quite a bit of prompting to get the connection and credentials right." The existing skill covers schema/query/insert best practices but has no agent-specific workflow guidance. ### New rules | Rule | Impact | Coverage | |------|--------|----------| | `agent-connect-mcp` | HIGH | Self-hosted + Cloud MCP server setup, credential discovery | | `agent-connect-cli` | HIGH | `clickhouse-client` flags, format options, performance | | `agent-connect-http` | MEDIUM | HTTP interface for lambdas/programmatic access | | `agent-discovery-schema` | CRITICAL | 7-step schema discovery (databases → tables → columns → sort keys → skip indexes → sample → EXPLAIN) | | `agent-query-safety` | CRITICAL | LIMIT, timeouts, progressive exploration, EXPLAIN ESTIMATE | | `agent-format-selection` | HIGH | JSON vs JSONEachRow vs TSV — token efficiency | ### Key additions - **Where to find credentials**: Step-by-step for ClickHouse Cloud console - **Column comments**: Guidance on using `system.columns` comments for semantic understanding - **Skipping index discovery**: `system.data_skipping_indices` check before querying - **EXPLAIN verification**: Verify query plans before executing expensive queries - **MCP vs CLI performance tradeoffs**: When to use each approach ### Agent Query Workflow Every agent session should follow: Connect → Discover → Plan → Verify → Execute → Validate ---------

Add chdb skills: DataStore (pandas API) and SQL (#14) ## Summary - Add **chdb-datastore** skill: Pandas-compatible DataStore API for [chdb](https://clickhouse.com/docs/chdb). Drop-in pandas replacement backed by ClickHouse (`import chdb.datastore as pd`), supporting 16+ data sources (MySQL, PostgreSQL, S3, MongoDB, ClickHouse, Iceberg, Delta Lake, etc.) and 10+ file formats with cross-source joins. - Add **chdb-sql** skill: In-process ClickHouse SQL API for Python. Covers `chdb.query()`, Session, DB-API 2.0, parametrized queries, UDFs, streaming, and all ClickHouse table functions. - Update root `README.md` and `AGENTS.md` to include the new skills. ## Skill Structure Each skill follows the agent-skills format with: | File | Purpose | |------|---------| | `SKILL.md` | Skill definition with YAML frontmatter and quick-start | | `metadata.json` | Version, organization, abstract | | `README.md` | Maintainer guide with trigger phrases | | `references/*.md` | API references and function docs | | `examples/examples.md` | Runnable examples with expected output | | `scripts/verify_install.py` | Environment verification script | ## Why Two Skills? The skills are split by usage pattern so agents load only what's relevant: - **chdb-datastore** activates for pandas-style data analysis (filter, groupby, join, sort — same API as pandas) - **chdb-sql** activates for raw SQL queries (ClickHouse table functions, window functions, sessions, UDFs) Both cross-reference each other in their SKILL.md so the agent knows when to switch. ## Test Plan - [x] Verify `SKILL.md` frontmatter parses correctly (name, description, license, metadata fields) - chdb-datastore: name=chdb-datastore, license=Apache-2.0, author=chdb-io, version=4.1 - chdb-sql: name=chdb-sql, license=Apache-2.0, author=chdb-io, version=4.1 - [x] Verify all internal links in SKILL.md resolve to their reference files - chdb-datastore: 7 links (references/connectors.md, references/api-reference.md, examples/examples.md, scripts/verify_install.py) — all resolved - chdb-sql: 7 links (references/table-functions.md, references/sql-functions.md, references/api-reference.md, examples/examples.md) — all resolved - [x] Run `python scripts/verify_install.py` in both skill directories (requires `pip install chdb`) - chdb-datastore: 8/8 checks passed (import chdb, from datastore import DataStore, from chdb.datastore import DataStore, import chdb.datastore as pd, filter, sort, groupby) - chdb-sql: 6/6 checks passed (import chdb, basic query, DataFrame output, Session, parametrized query) - [x] Install skills via `npx skills add` and verify agent activation on trigger phrases - `npx skills add auxten/agent-skills --list` correctly detected all 3 skills (chdb-datastore, chdb-sql, clickhouse-best-practices) - `npx skills add --all` installed 3 skills to 42 agent directories via symlinks - Verified `.claude/skills/`, `.windsurf/skills/` etc. contain correct symlinks - `skills-lock.json` generated with correct source and hashes --------- Co-authored-by: Copilot Autofix powered by AI

Add clickhouse-architecture-advisor skill (#19) # Proposed PR: Add `clickhouse-architecture-advisor` skill ## Summary This PR adds a new skill, `clickhouse-architecture-advisor`, intended to complement the existing `clickhouse-best-practices` skill. The new skill does **not** replace official best practices. Instead, it provides a workload-aware architecture decision layer that helps agents and users reason about: - when to apply specific ClickHouse patterns - why a pattern fits a given workload - how to translate best practices into a concrete architecture ## Why this belongs in `agent-skills` The current `clickhouse-best-practices` skill is excellent at rule-backed guidance for schema design, query optimization, and ingestion. This proposal fills a different gap: - multi-step architecture design - workload classification - tradeoff-driven decisioning - explicit distinction between official guidance and field heuristics This is especially useful for: - early-stage customer architecture - real-time design workshops - workload sizing discussions - POC design - SA/TAM advisory workflows ## What this PR includes ### New skill - `skills/clickhouse-architecture-advisor/` ### New components - `SKILL.md` - `README.md` - `AGENTS.md` - `metadata.json` - `schemas/recommendation_schema.yaml` - `mappings/doc_links.yaml` ### Decision rules - `decision-ingestion-strategy.md` - `decision-partitioning-timeseries.md` - `decision-join-enrichment.md` - `decision-late-arriving-upserts.md` - `decision-real-time-preaggregation.md` ### Examples - `observability-high-throughput.md` - `finserv-market-surveillance.md` - `siem-security-analytics.md` ## Recommendation model Every recommendation is explicitly classified as one of: - `official` — directly backed by official docs - `derived` — inferred from official docs and ClickHouse behavior - `field` — experience-based, explicitly labeled as such This keeps the skill aligned with the principle that docs remain the source of truth while still allowing architecture guidance to be useful in real-world scenarios. ## Non-goals This PR does not: - override `clickhouse-best-practices` - introduce commercial recommendations - create a parallel documentation system - present field heuristics as official guidance ## Suggested review focus - Naming and scope of the skill - Whether the official / derived / field classification is the right pattern - Whether the decision rules should remain separate or partially merge into the existing best-practices skill - Whether more explicit docs links are needed in specific rules ## Notes This proposal is intentionally conservative: - it cites official documentation - it flags heuristics - it uses examples to show how the architecture layer complements existing rules

fix: correct join_use_nulls default value (0, not 1) (#20) ## Summary The table in `query-join-null-handling.md` incorrectly labels `join_use_nulls = 1` as the default. The actual default is `0` (false). ## Evidence **ClickHouse source code** ([`Settings.cpp#L2305`](https://github.com/ClickHouse/ClickHouse/blob/4d79f6ea35f896060e55128fe8ca4216f455d9c0/src/Core/Settings.cpp#L2305)): ```cpp DECLARE(Bool, join_use_nulls, false, ...) ``` **Verified on ClickHouse Cloud instance:** ```sql SELECT name, value, changed FROM system.settings WHERE name = 'join_use_nulls' -- value=0, changed=0 ``` ## Why this matters With `join_use_nulls = 0` (the actual default), LEFT JOIN non-matches return the type's default value (`''` for String, `0` for Int) — not NULL. Code that uses `IS NOT NULL` to detect matches will silently always return true. ## Change Swapped the `(default)` label from `join_use_nulls = 1` to `join_use_nulls = 0` in the "When to use" table.

clickhousectl cloud deploy: OAuth is now read-only, API key needed for mutations (#21) ## Summary - OAuth browser login (`clickhousectl cloud login`) is now read-only — it can list orgs, services, and query data, but cannot create, modify, or delete cloud resources - Updated Step 2 auth options to make this distinction clear upfront, so agents know which auth method to use - Added a reminder in Step 3 (service creation) that API key auth is required Co-authored-by: Claude Opus 4.6 (1M context)

feat: add clickhousectl local-dev and cloud-deploy agent skills (#16) ## Summary - Adds `clickhousectl-local-dev` skill: guides agents through setting up a local ClickHouse dev environment using `clickhousectl` (install CLI, install ClickHouse, init project, start server, create schema, seed data, verify) - Adds `clickhousectl-cloud-deploy` skill: guides agents through deploying to ClickHouse Cloud (sign up, authenticate via OAuth device flow or API keys, create service, migrate local schemas, verify, configure app connection) These are flow-based skills — they walk agents through end-to-end workflows rather than providing rules to check. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context)

Update README installation instructions via clickhousectl (#17) Added installation instructions via clickhousectl.

Add Claude Code plugin structure for marketplace distribution (#18) ## Summary Adds `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` so the `clickhouse-best-practices` skill can be distributed through the Claude Code plugin marketplace. This is a **skills-only plugin** — no MCP server, no `.mcp.json`, no behavioral changes. The existing `skills/clickhouse-best-practices/` directory is referenced as-is. ## What's added | File | Purpose | |------|---------| | `.claude-plugin/plugin.json` | Plugin manifest — declares the skill, version, author, license | | `.claude-plugin/marketplace.json` | Marketplace metadata — name, owner, category (`database`) | Both files pass `claude plugin validate .` cleanly. ## Why The Claude Code plugin marketplace requires these two files for a plugin to be discoverable and installable via `claude plugin install`. Without them, the skill works via `npx skills add` but isn't available in the Claude Code marketplace. ## After merge Once merged, the plugin can be submitted to the Claude Code marketplace for review and distribution. No changes to the existing `npx skills add` installation path.

chore(docs): Add AI Policy (#12)

Update installation command for ClickHouse skill (#10) old method is deprecated.

Update installation command in README

chore: add workflow to publish to npm