skilld
All skills
clickhouse avatar

/clickhouse-managed-postgres-rca

@544384f official
by clickhouseclickhouse/agent-skills543 stars
39

MUST USE when investigating performance issues on a ClickHouse-managed Postgres instance. Provides an evidence-based RCA workflow that scrapes the Prometheus endpoint for system signal, pulls per-digest evidence from the Slow Query Patterns API, and recommends (does not apply) a fix.

Ask your Agent

Use this Skill: https://skilld.dev/gh/clickhouse/agent-skills/clickhouse-managed-postgres-rca

This session only. Nothing lands on disk.

README.md

≈342 tokens on demand. Your agent reads this file only when SKILL.md points to it.

ClickHouse Managed Postgres RCA Skill

A Claude skill for diagnosing performance issues on ClickHouse-managed Postgres. Surfaces two API endpoints to the agent and guides it through an evidence-based RCA loop:

  • The Prometheus metrics endpoint (postgresInstancePrometheusGet) — system and workload signal.
  • The Slow Query Patterns API (slowQueryPatternsGetList) — per-digest evidence.

The skill encodes a workflow: scrape Prom for stress signal, pull top slow query patterns, triage the signal shape against a small library of heuristics, and produce a structured recommendation.

v0.1 heuristic library

  • Full scan — read-path patterns with high blocks-read-per-row.
  • Hot loop (N+1) — patterns with very high call rate and very low per-call latency.
  • Write congestion — deadlocks, slow writes, high rollback rate.

If the signal does not match any of these, the skill surfaces what it saw and asks rather than inventing a hypothesis. New heuristics are welcome as PRs.

Recommend-only

The skill never issues DDL, never kills queries, never mutates the instance. It writes the SQL (or app-side change) the human should make and explains the reasoning.

Both APIs are currently in Beta. The skill resolves exact paths and field names from the OpenAPI spec on first use, so it remains correct as the surface evolves.

Source: SKILL.md on GitHub

Third-party checks

1 alert3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill provides a structured diagnostic workflow for ClickHouse-managed Postgres instances. It fetches system metrics and query patterns from official ClickHouse Cloud APIs to identify performance bottlenecks like full scans or hot loops. It includes a strong 'recommend-only' guardrail, ensuring no modifications are made to the database.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: HIGH · 3 issues

Provenance

Signed by skilld at 544384f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 4 months ago

Capability

metadata
{
  "author": "ClickHouse Inc",
  "version": "0.1.0"
}

Topics

  • Performance
  • clickhouse
  • postgres
  • rca
  • troubleshooting
  • prometheus
  • slow-query
  • managed-database

README badge

README badge for clickhouse/agent-skills/clickhouse-managed-postgres-rca

What it does

Investigates performance issues on ClickHouse-managed Postgres instances by scraping Prometheus metrics and querying the Slow Query Patterns API to identify the root cause. Follows a six-step RCA workflow that reasons from system signals and query digests to recommend (but not apply) fixes like addressing full table scans, N+1 loops, or write congestion.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with self-hosted Postgres or only ClickHouse Cloud?
Only ClickHouse Cloud managed Postgres instances. The skill requires the ClickHouse Cloud API endpoints for Prometheus metrics and the Slow Query Patterns API.
What credentials do I need to use this skill?
A ClickHouse Cloud API key and secret pair for HTTP Basic auth, plus the organization ID and service ID for the Postgres instance you're investigating.
Can this skill apply fixes automatically?
No. The skill diagnoses the issue and recommends a fix, but the human must apply it. The skill never runs DDL or backend termination commands.
Does this skill provide query plans or EXPLAIN output?
No. It reasons from Prometheus system metrics and slow query pattern statistics, not from query plans. You will not get per-table scan counts or autovacuum timestamps.
How long does the RCA workflow take?
Approximately 1 second. Steps 2 and 3 (Prometheus scrape and slow query patterns) run in parallel, reducing wall time from ~2s sequential to ~1s.

Generated from the current SKILL.md. These answers refresh after source changes.