Diagnose Clickhouse Errors
Koppelt een ClickHouse foutcode aan een per-code diagnose-playbook en een 3-delig Oorzaak/Oplossing antwoord
Werkt met setup
Wat het doet
Zet een ClickHouse runtime fout om in een vast Oorzaak / Oplossing / Voorbeeld antwoord door de numerieke foutcode te extraheren en een per-code playbook te laden (42, 47, 60, 115, 342 zijn gebundeld). Activeert wanneer een gebruiker een DB::Exception plakt of een ClickHouse foutcode noemt en database-niveau oorzaak- en oplossingsbegeleiding wil, en verwijst expliciet naar broncode-inspectie wanneer het doel is te vinden waar de falende SQL is gebouwd. De meeste playbooks verwachten een live ClickHouse om een system.columns / system.tables / system.settings lookup uit te voeren, met een gedocumenteerde tekst-alleen fallback wanneer die query niet kan worden uitgevoerd.
Testrapport
GitHub API was rate-limited, dus ik kloonde de repo en vond SKILL.md op resources/skills/diagnose-clickhouse-errors/; raw-fetched SKILL.md, references/60.md en references/342.md (allemaal HTTP 200; een verzonnen references/999.md retourneerde 404, wat bevestigt dat slechts 5 codes worden geleverd), grep vond geen curl|sh, base64, credentials of injection tekst, en ik voerde het installatieblok uit in een tijdelijke HOME=$(mktemp -d) waar het SKILL.md plus alle 5 referentiebestanden correct plaatste. Triggerzinnen die ik beoordeelde: MOET activeren — "My query failed with Code: 60. DB::Exception: Table analytics.evnts doesn't exist. (UNKNOWN_TABLE), what's wrong?", "ClickHouse throws error code 115 on my SETTINGS clause, how do I fix it?", "Getting NUMBER_OF_ARGUMENTS_DOESNT_MATCH from toStartOfInterval in ClickHouse"; MOET NIET — "This ClickHouse query takes 40 seconds, help me speed it up" (optimalisatie, geen storing) en "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (de beschrijving en een When-Not-To-Use sectie verwijzen dat expliciet naar broncode-inspectie); 5/5 correct. Output test gebruikte fout 342 omdat references/342.md het enige playbook is dat de ontbrekende execute_sql tool niet vereist: de baseline noemde de ontbrekende `payload` kolom, gaf read-only checks (system.replicas, clusterAllReplicas over system.columns) en drie herstelopties inclusief `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, terwijl de skill-gevolgde run inklapte tot ~180 woorden met koppen ## Cause / ## Fix, de verplichte opgeslagen/geparsete/lokale fragmentextractie, nul muterende commando's en "escalate to the cluster maintainer / SRE" — veiliger voor een productie-incident maar strikt minder bruikbaar voor een Claude Code gebruiker die de maintainer is, dus ik scoorde het niet beter dan baseline. Oordeel setup: voor 4 van de 5 codes is de bewijsstap een live `execute_sql` die ik niet kon uitvoeren, en drie toolnamen in de body (skill_resource, execute_sql, ask_user_question) zijn DataStoria productinternals die geen README of skill notitie markeert als niet beschikbaar buiten die app.
Getest op: 2026-07-21 · Claude Code 2.x (agent harness)
Installatie
git clone --depth 1 https://github.com/FrankChen021/datastoria.git /tmp/diagnose-clickhouse-errors-src
mkdir -p ~/.claude/skills
cp -R /tmp/diagnose-clickhouse-errors-src/resources/skills/diagnose-clickhouse-errors ~/.claude/skills/diagnose-clickhouse-errors
# Verified: places SKILL.md + references/{42,47,60,115,342}.md under ~/.claude/skills/diagnose-clickhouse-errors/
# The repo is the DataStoria web console (~large clone); only this one directory is needed.
# Sibling skills in the same folder that this one references: source-code-inspection, optimize-clickhouse-sql,
# clickhouse-system-queries, diagnose-clickhouse-clusters, sql-expert, visualization.
# MANUAL STEP: the skill body calls DataStoria-internal tools that do not exist in Claude Code:
# skill_resource -> read references/<code>.md yourself
# ask_user_question -> AskUserQuestion
# execute_sql -> needs a ClickHouse MCP server or a clickhouse-client you run by hand;
# without it, codes 42/47/60/115 fall back to text-only diagnosis (documented in each file). Commando's en voorbeeldprompts
/diagnose-clickhouse-errorsKoppelt een ClickHouse foutcode aan een per-code diagnose-playbook en een 3-delig Oorzaak/Oplossing antwoord
Skills reageren op gewone verzoeken — geen commando's om te onthouden. Na installatie activeren prompts zoals deze de skill (in het Engels):
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error