altinity-expert-clickhouse-mutations

Diagnose ClickHouse mutation performance using system.mutations and related views.

42|7|Updated Dec 26, 2025
One-click install
npx skills add https://github.com/ntk148v/clicklens --skill altinity-expert-clickhouse-mutations
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: altinity-expert-clickhouse-mutations
Source: https://github.com/ntk148v/clicklens/tree/main/.agent/skills/altinity-expert-clickhouse-mutations
Command: npx skills add https://github.com/ntk148v/clicklens --skill altinity-expert-clickhouse-mutations

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Mutations in ClickHouse can become long-running or stuck, leading to degraded write performance and potential data inconsistencies. This skill provides actionable diagnostics to monitor, diagnose, and remediate mutation-related issues across a cluster.

Core Features & Use Cases

  • Current Mutations Status: quickly view all ongoing mutations with status and age.
  • Mutation History & Performance: review completed and in-flight mutations to identify trends and bottlenecks.
  • Stuck Mutations Detection & Remediation Guidance: detect aging mutations and provide practical steps to resolve them.
  • Cross-Module Context: correlate mutations with merges, replication, and resource usage to diagnose root causes.

Quick Start

Identify active and pending mutations by querying system.mutations and related views, then assess their impact and plan remediation.

Frequently Asked Questions about altinity-expert-clickhouse-mutations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find and kill stuck ClickHouse mutations?

To find stuck ClickHouse mutations, query the system.mutations table to identify entries with an old age and pending status. This skill provides remediation guidance by correlating mutation data with system.merges and system.part_log to diagnose the root cause before killing the job.

How do I monitor current ClickHouse mutations and their performance impact?

You can monitor current ClickHouse mutations by querying system.mutations to view ongoing jobs, their status, and age. This skill evaluates mutation performance by cross-referencing system.part_log and resource usage to identify trends and bottlenecks.

Why are ClickHouse mutations blocking my database writes?

ClickHouse mutations can block writes when they become long-running or stuck, leading to degraded performance. This skill diagnoses write blocking by analyzing mutation history and correlating it with replication and merge operations across the cluster.

What is the best way to analyze ClickHouse mutation history and bottlenecks?

The best way to analyze ClickHouse mutation history is to review completed and in-flight mutations using system.mutations. This skill identifies performance bottlenecks by evaluating mutation impact across tables and correlating with merge operations.

Does this approach diagnose ClickHouse mutations for large deployments?

Yes, this diagnostic approach is specifically designed for DBAs and data engineers managing large ClickHouse deployments. It evaluates mutation impact across tables and provides actionable diagnostics for cluster-wide mutation issues.

How do ClickHouse mutations interact with merges and replication?

ClickHouse mutations interact with merges and replication by competing for system resources, which can cause jobs to stall. This skill provides cross-module context by correlating system.mutations, system.merges, and replication status to identify root causes.