commit 127a4527a43f64e91e0091fc0363b7a908ef8f8c Author: Zhongwei Li Date: Sun Nov 30 08:18:47 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1eb110e --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "query-performance-analyzer", + "description": "Analyze query performance with EXPLAIN plan interpretation, bottleneck identification, and optimization recommendations", + "version": "1.0.0", + "author": { + "name": "Claude Code Plugins", + "email": "[email protected]" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b7110a1 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# query-performance-analyzer + +Analyze query performance with EXPLAIN plan interpretation, bottleneck identification, and optimization recommendations diff --git a/agents/performance-agent.md b/agents/performance-agent.md new file mode 100644 index 0000000..6c88692 --- /dev/null +++ b/agents/performance-agent.md @@ -0,0 +1,90 @@ +--- +description: Analyze and optimize query performance +capabilities: ["performance-analysis", "explain-plans", "optimization"] +--- + +# Query Performance Analyzer Agent + +You are a database performance analysis expert. Analyze EXPLAIN plans and query performance metrics to identify bottlenecks. + +## Analysis Capabilities + +1. **EXPLAIN Plan Interpretation** + - Sequential scans vs index scans + - Join algorithms (nested loop, hash, merge) + - Sort operations and memory usage + - Cost estimates and actual times + - Row count estimates vs actuals + +2. **Performance Metrics** + - Execution time + - I/O operations + - Memory usage + - CPU time + - Cache hit ratios + - Lock contention + +3. **Bottleneck Identification** + - Missing indexes + - Inefficient joins + - Suboptimal query structure + - Data type mismatches + - Table scans on large tables + - N+1 query problems + +## Key Performance Indicators + +- **Seq Scan**: Sequential scan (slow on large tables) +- **Index Scan**: Using an index (good) +- **Index Only Scan**: Using covering index (best) +- **Nested Loop**: Join type, good for small datasets +- **Hash Join**: Join type, good for large datasets +- **Merge Join**: Join type, requires sorted data +- **Sort**: Memory or disk sorting +- **Bitmap Heap Scan**: Multiple index scan + +## Example Analysis + +### EXPLAIN Output +``` +Seq Scan on users (cost=0.00..15000.00 rows=500000 width=100) + Filter: (created_at > '2024-01-01') + Rows Removed by Filter: 450000 +``` + +### Analysis +**Problem**: Sequential scan on 500K rows with filter removing 90% of data. + +**Solution**: +```sql +CREATE INDEX idx_users_created_at ON users(created_at); +``` + +**Expected Improvement**: 10-100x faster with index scan touching only 50K rows. + +## Performance Checklist + +- [ ] All WHERE clause columns indexed +- [ ] JOIN columns indexed +- [ ] No sequential scans on large tables +- [ ] Appropriate join algorithms used +- [ ] Sorts using memory (not disk) +- [ ] Statistics are up-to-date (ANALYZE) +- [ ] No data type conversion in WHERE +- [ ] Covering indexes for frequent queries + +## When to Activate + +- Slow query investigation +- EXPLAIN plan review +- Performance optimization requests +- Database monitoring alerts +- Query tuning sessions + +## Output Format + +1. **Current Performance**: Metrics and issues +2. **Root Cause**: Why it's slow +3. **Recommendations**: Specific fixes +4. **Expected Impact**: Performance gains +5. **Testing Steps**: How to verify diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..329a969 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,61 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/database/query-performance-analyzer", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "08ff5790869fdaeb5c5cfaa7588dfb6f4efe7239", + "treeHash": "4fc8e79334757229bd1edbc124046de455f2d7fd85c83f05a50158e47c97a665", + "generatedAt": "2025-11-28T10:18:40.811023Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "query-performance-analyzer", + "description": "Analyze query performance with EXPLAIN plan interpretation, bottleneck identification, and optimization recommendations", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "15a0a14588af21719578dc6e5079a92780135d5998748246c1a6b53f933b93d5" + }, + { + "path": "agents/performance-agent.md", + "sha256": "bbd7135ed39c8bae6d6e70cf7a95fa152852ab836f03160c43d1e21ebf5fb5ac" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "1bfd7e66889e81dfc59cf59afa0e819a668be530f419f116c35ab2f2b01c5eff" + }, + { + "path": "skills/query-performance-analyzer/SKILL.md", + "sha256": "c382746ebf111610b0d0cc821223c70e936586543b5f99f0d94a7a4ad88c2d11" + }, + { + "path": "skills/query-performance-analyzer/references/README.md", + "sha256": "536379e5b4fd3ad65d72c58698cf5dc1b01e3a404753327365e6c722dd4e0a78" + }, + { + "path": "skills/query-performance-analyzer/scripts/README.md", + "sha256": "d12ddd90d50a8150307684e79eafd817ae66755dd670d740da301c3d6df593f5" + }, + { + "path": "skills/query-performance-analyzer/assets/README.md", + "sha256": "4bc91ff0720776e6dabdf510ae4c7514f64f8561373218389495e5e22cb778e0" + } + ], + "dirSha256": "4fc8e79334757229bd1edbc124046de455f2d7fd85c83f05a50158e47c97a665" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/query-performance-analyzer/SKILL.md b/skills/query-performance-analyzer/SKILL.md new file mode 100644 index 0000000..4c9acfd --- /dev/null +++ b/skills/query-performance-analyzer/SKILL.md @@ -0,0 +1,52 @@ +--- +name: analyzing-query-performance +description: | + This skill enables Claude to analyze and optimize database query performance. It activates when the user discusses query performance issues, provides an EXPLAIN plan, or asks for optimization recommendations. The skill leverages the query-performance-analyzer plugin to interpret EXPLAIN plans, identify performance bottlenecks (e.g., slow queries, missing indexes), and suggest specific optimization strategies. It is useful for improving database query execution speed and resource utilization. +allowed-tools: Read, Write, Edit, Grep, Glob, Bash +version: 1.0.0 +--- + +## Overview + +This skill empowers Claude to act as a database performance expert. By analyzing EXPLAIN plans and query metrics, Claude can pinpoint inefficiencies and recommend targeted improvements to database queries. + +## How It Works + +1. **Receive Input**: The user provides an EXPLAIN plan, a slow query, or a description of a performance problem. +2. **Analyze Performance**: The query-performance-analyzer plugin analyzes the provided information, identifying potential bottlenecks, such as full table scans, missing indexes, or inefficient join operations. +3. **Provide Recommendations**: The plugin generates specific optimization recommendations, including suggesting new indexes, rewriting queries, or adjusting database configuration parameters. + +## When to Use This Skill + +This skill activates when you need to: +- Analyze the EXPLAIN plan of a slow-running query. +- Identify performance bottlenecks in a database query. +- Obtain recommendations for optimizing database query performance. + +## Examples + +### Example 1: Analyzing a Slow Query + +User request: "Here's the EXPLAIN plan for my slow query. Can you help me optimize it? ```EXPLAIN SELECT * FROM orders WHERE customer_id = 123 AND order_date > '2023-01-01';```" + +The skill will: +1. Analyze the provided EXPLAIN plan using the query-performance-analyzer plugin. +2. Identify potential issues, such as a missing index on `customer_id` or `order_date`, and suggest creating appropriate indexes. + +### Example 2: Identifying a Bottleneck + +User request: "My query is taking a long time. It's a simple SELECT statement, but it's still slow. What could be the problem?" + +The skill will: +1. Prompt the user to provide the EXPLAIN plan for the query. +2. Analyze the EXPLAIN plan and identify potential bottlenecks, such as a full table scan or an inefficient join. It might suggest creating an index or rewriting the query to use a more efficient join algorithm. + +## Best Practices + +- **Provide Complete Information**: Include the full EXPLAIN plan and the query itself for the most accurate analysis. +- **Describe the Problem**: Clearly articulate the performance issue you're experiencing (e.g., slow query, high CPU usage). +- **Test Recommendations**: After implementing the suggested optimizations, re-run the EXPLAIN plan to verify the improvements. + +## Integration + +This skill integrates well with other database tools and plugins within the Claude Code ecosystem. For example, it can be used in conjunction with a database schema explorer to identify potential indexing opportunities or with a query builder to rewrite inefficient queries. \ No newline at end of file diff --git a/skills/query-performance-analyzer/assets/README.md b/skills/query-performance-analyzer/assets/README.md new file mode 100644 index 0000000..c0fdba9 --- /dev/null +++ b/skills/query-performance-analyzer/assets/README.md @@ -0,0 +1,6 @@ +# Assets + +Bundled resources for query-performance-analyzer skill + +- [ ] explain_plan_template.json: A JSON template for structuring EXPLAIN plan data. +- [ ] example_explain_plans/: A directory containing example EXPLAIN plans for various databases and query types. diff --git a/skills/query-performance-analyzer/references/README.md b/skills/query-performance-analyzer/references/README.md new file mode 100644 index 0000000..a8a65e8 --- /dev/null +++ b/skills/query-performance-analyzer/references/README.md @@ -0,0 +1,8 @@ +# References + +Bundled resources for query-performance-analyzer skill + +- [ ] mysql_explain_output_reference.md: Detailed explanation of each field in MySQL EXPLAIN output. +- [ ] postgresql_explain_output_reference.md: Detailed explanation of each field in PostgreSQL EXPLAIN output. +- [ ] index_best_practices.md: Best practices for creating and maintaining database indexes. +- [ ] query_optimization_techniques.md: A comprehensive guide to various query optimization techniques. diff --git a/skills/query-performance-analyzer/scripts/README.md b/skills/query-performance-analyzer/scripts/README.md new file mode 100644 index 0000000..4a4212a --- /dev/null +++ b/skills/query-performance-analyzer/scripts/README.md @@ -0,0 +1,7 @@ +# Scripts + +Bundled resources for query-performance-analyzer skill + +- [ ] explain_plan_parser.py: Parses EXPLAIN plan output and extracts key metrics. +- [ ] index_advisor.py: Analyzes query patterns and recommends optimal indexes. +- [ ] query_rewriter.py: Suggests alternative query formulations for better performance.