# Altinity Expert Clickhouse Connection

> Establishes the ClickHouse connection mode, cluster macro, and default log timeframe for diagnostics. Use first, before any other altinity-expert-clickhouse skill, to verify connectivity and set shared analysis rules.

- Skill: `altinity/altinity-expert-clickhouse-connection` (Agent Skill)
- Install (CLI): `npx skillmds@latest add altinity/altinity-expert-clickhouse-connection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/altinity/altinity-expert-clickhouse-connection/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: altinity (https://skillmd.com/u/altinity)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/altinity/altinity-expert-clickhouse-connection

---


## Connection mode

Decide connection mode first and verify connectivity then:
```sql
select
    hostName() as hostname,
    version() as version,
    getMacro('cluster') as cluster_name,
    formatReadableTimeDelta(uptime()) as uptime_human,
    getSetting('max_memory_usage') as max_memory_usage,
    (select value from system.asynchronous_metrics where metric = 'OSMemoryTotal') as os_memory_total
```

### MCP mode

Try to use MCP server with clickhouse in the name.
If multiple ClickHouse MCP servers are available, ask the user which one to use.
When executing queries by the MCP server, push a single SQL statement to the MCP server (no multi-query!)

### Exec mode (clickhouse-client)

- if MCP is unavailable, try to run `clickhouse-client`. Don't rely on env vars. On failure, ask how to run it properly.
- Prefer running queries from a `.sql` file with `--queries-file` and forcing JSON output (`-f JSON`) when capturing results to files.

## Cluster selection for `clusterAllReplicas('{cluster}', ...)`

- Verify from the query results above if a cluster_name (cluster macro var) is not empty. If defined - leave macro as-is.
- if not, ask the user to choose from: `SELECT DISTINCT cluster FROM system.clusters where not is_local` and replace `'{cluster}'` placeholders in the queries in all `.sql` files.
- if the query above returns nothing, consider single-server mode and automatically rewrite `clusterAllReplicas('{cluster}', system.<table>)` → `system.<table>` before execution.

## Timeframe default for logs/errors

- If the user explicitly provides a timeframe in the initial prompt, use it exactly.
- Otherwise always default to **last 24 hours**:

```sql
-- Use this pattern for system.*_log tables and system.errors time filters:
-- WHERE event_time >= now() - INTERVAL 24 HOUR
```
- never extend the time window without an explicit user prompt. If needed, ask the user to extend it

## Schema-safe rule

- If a query fails with `UNKNOWN_IDENTIFIER`, run `DESCRIBE TABLE system.<table>` and drop/adjust only the missing columns.
- If a query fails with `UNKNOWN_TABLE`, skip that query and note the table is disabled or unavailable (e.g., `system.part_log`, `system.detached_parts`).

## Report Output

In all reports, always provide a header with information:
- Connection mode used: MCP or clickhouse-client
- cluster name (or “no cluster / single node”)
- clickhouse version
- time window used for analysis