SQL Helper

Генерация SQL-запросов из текстового вопроса и DDL-схемы.

Загружай этот скилл когда нужно превратить вопрос на естественном языке в SQL: для быстрых запросов к базе, разбора плана выполнения или форматирования SQL.

🎯 When to use

Use this skill when:

• Есть DDL-файл (CREATE TABLE) и вопрос, по которому нужен SQL-запрос
• Нужно быстро собрать SELECT/JOIN/GROUP BY/COUNT по шаблону
• Просят «сгенерируй sql», «напиши sql», «sql запрос», «sql helper»
• Нужно посмотреть план выполнения запроса (EXPLAIN) в читаемом виде

Do NOT use when:

• Нужна только проверка синтаксиса без схемы — достаточно обычного редактора
• Нужна миграция или генерация DDL — это отдельный инструмент
• Вопрос не про SQL (анализ данных, CSV, скрейпинг) — это другие скиллы

📦 Files

• SKILL.md — этот файл
• scripts/sql_helper.py — генератор SQL + EXPLAIN (Python 3 stdlib)
• references/canonical-patterns.md — канонические аналоги text-to-SQL и разбор недостающих техник

Canonical analogues

Полный разбор — в references/canonical-patterns.md. Ключевые каноны, на которые опирается дизайн скилла:

• Anthropic Cookbook capabilities/text_to_sql — эталон интроспекции схемы (sqlite_master + PRAGMA table_info) и execution-based валидации через promptfoo-ассерты.
• sqlsure / sql-semantic-check — семантические правила FANOUT/JOIN_KEY/ADDITIVITY и интроспекция PK/FK вместо эвристик join.
• Vanna.ai — контур train → retrieve (few-shot) → generate_sql → run_sql → verify.
• Spider / BIRD / Spider 2.0 — методология оценки: exact match, execution accuracy, validity + efficiency; schema linking как первый этап.
• sqlite-utils + SQLGlot — CLI-интроспекция (schema, analyze, memory) и квотинг идентификаторов (quote_identifiers).
• grok-sqlite-explain — построение дерева EXPLAIN по ссылкам parent, а не по id.

🧰 Usage

# Сгенерировать SQL по вопросу:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "select users by id"

# С планом выполнения:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "count orders by user" --explain

# JOIN двух таблиц:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "join users and orders"

# С лимитом и сортировкой:
python3 skills/sql-helper/scripts/sql_helper.py --ddl schema.sql --question "top 5 orders by date desc"

🔬 Проверка результата

• Скрипт выводит сгенерированный SQL в stdout и завершается с кодом 0.
• При --explain после SQL печатается секция --- query plan --- с планом.
• Пустой вопрос или невалидный DDL — сообщение в stderr и код выхода 1.

Boundaries

• Do not use for executing SQL against production or for schema migrations; review and run queries separately.

Evidence and completion gate

Run the documented command against the user’s actual input. Report the command, exit status, files changed or produced, and relevant stdout/stderr. Separate blocked or pre-existing failures from failures introduced by the current work. Do not call the result complete when the script was only described or when an artifact was not reopened and checked.