tikv-scale

Diagnose bottlenecks in TiKV scale-out and scale-in operations for TiDB clusters.

Updated Jun 3, 2026
One-click install
npx skills add https://github.com/alex-quan-001/nutshell-skills --skill tikv-scale
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tikv-scale
Source: https://github.com/alex-quan-001/nutshell-skills/tree/main/skills/diagnosis/tikv-scale
Command: npx skills add https://github.com/alex-quan-001/nutshell-skills --skill tikv-scale

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill eliminates guesswork when troubleshooting slow or stuck TiKV scale-out and scale-in operations in TiDB clusters, helping you quickly identify whether the bottleneck lies in PD operator generation or TiKV data migration.

Core Features & Use Cases

  • PD Operator Diagnosis: Analyze PD scheduling metrics and logs to pinpoint slow operator creation for balance-region and replace-rule-offline-* operations.
  • TiKV Migration Troubleshooting: Diagnose stuck add learner operations, snapshot migration bottlenecks, and store state transition delays.
  • Use Case: If your new TiKV node stays empty after a scale-out operation, or your scale-in operation is stuck on replace-rule-offline-peer creation, this Skill guides you through exact steps to find the root cause.

Quick Start

Use the tikv-scale skill to diagnose why your TiDB cluster's TiKV scale-in operation is stuck and identify the root cause bottleneck.

Frequently Asked Questions about tikv-scale

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

FAQPage Schema
Why does my TiKV node stay empty after a TiDB cluster scale-out operation?

An empty TiKV node after scale-out indicates a bottleneck in PD operator creation or TiKV data migration. Diagnosing PD scheduling metrics and logs helps pinpoint if slow balance-region operators prevent snapshot migration from initiating.

How do I troubleshoot stuck TiKV scale-in operations in a TiDB cluster?

To troubleshoot stuck TiKV scale-in operations, analyze PD logs for replace-rule-offline-* operator delays and inspect TiKV store state transitions. Identifying whether the bottleneck is in operator generation or data migration guides the exact resolution steps.

What causes slow PD operator creation during TiKV store migration?

Slow PD operator creation during TiKV store migration stems from scheduling configuration issues or cluster constraints. Analyzing PD scheduling metrics isolates the bottleneck, enabling specific configuration knob recommendations to accelerate balance-region operations.

How do I diagnose stuck add learner operations when scaling TiKV?

Diagnosing stuck add learner operations requires checking TiKV snapshot migration performance and store state transition logs. Applying workflow heuristics isolates the delay, providing configuration adjustments to resolve the scaling bottleneck.

Can I use this to find root causes for TiKV snapshot migration performance issues?

Yes, you can diagnose TiKV snapshot migration performance issues by analyzing store state transition delays and PD operator logs. This approach provides workflow heuristics and configuration recommendations to resolve scaling bottlenecks.

What are the limitations when diagnosing TiKV scaling bottlenecks in TiDB clusters?

Diagnosing TiKV scaling bottlenecks relies on accessing accurate PD scheduling logs and TiKV state metrics. Without proper log access, identifying slow operator creation or stuck add learner operations remains constrained by available diagnostic data.