# SQL Insight

Translate natural language to SQL, optimize query performance, and interpret EXPLAIN...

- Repository: https://github.com/zebbern/claude-code-guide (4691 stars)
- Category: Data and ML
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add zebbern/claude-code-guide --skill sql-insight -g -a claude-code -y`
Codex: `npx skills add zebbern/claude-code-guide --skill sql-insight -g -a codex -y`
Cursor: `npx skills add zebbern/claude-code-guide --skill sql-insight -g -a cursor -y`
Gemini CLI: `npx skills add zebbern/claude-code-guide --skill sql-insight -g -a gemini-cli -y`

## Description

Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL. Triggered when users ask to convert questions into SQL, improve slow queries, tune indexes, analyze execution plans, or mention keywords like NL2SQL, query tuning, or full table scan.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# sql-insight

SQL query assistant, natural language to SQL translation, query optimization analysis, and EXPLAIN plan interpretation.

## Capabilities

| Feature | Description |
|---------|-------------|
| Schema Extraction | Extracts database table structure (columns, types, indexes, foreign keys, sample data) to provide context for NL→SQL |
| Natural Language → SQL | Translates natural language descriptions into SQL queries using schema context |
| Query Optimization Analysis | Detects SQL anti-patterns based on 13 rules and provides optimization suggestions |
| EXPLAIN Interpretation | Runs EXPLAIN and interprets the query plan, identifying full table scans, missing indexes, and more |

## Workflow

### Natural Language → SQL

1. Use the `schema` command to extract the database table structure
2. Use the schema as context to translate the user's natural language request into SQL
3. Use the `optimize` command to check if the generated SQL can be improved
4. Use the `explain` command to verify the query execution plan

```bash
# Step 1: Extract schema (compact mode, suitable for LLM context)
python3 scripts/sql_query_helper.py --db-path data.db schema --compact

# Step 2: Analyze SQL optimization suggestions
python3 scripts/sql_query_helper.py optimize "SELECT * FROM orders WHERE user_id = 100"

# Step 3: View EXPLAIN execution plan
python3 scripts/sql_query_helper.py --db-path data.db explain "SELECT * FROM orders WHERE user_id = 100"
```

## Quick Start

### Schema Extraction

```bash
# Extract full schema (JSON format, with sample data)
python3 scripts/sql_query_helper.py --db-path data.db schema

# Compact mode (plain text, suitable for embedding in prompts)
python3 scripts/sql_query_helper.py --db-path data.db schema --compact

# Skip data sampling
python3 scripts/sql_query_helper.py --db-path data.db schema --sample-rows 0

The rest: https://github.com/zebbern/claude-code-guide/blob/HEAD/skills/sql-insight/SKILL.md