# Sql Helper

> Генерация SQL по текстовому вопросу и DDL-схеме. Скрипт sql_helper.py читает DDL-файл, строит in-memory схему в sqlite3, распознаёт слова вопроса по таблицам/колонкам и собирает SQL по шаблонам интентов (select, join, where, group, order, count, limit). Каждый кандидат проверяется через EXPLAIN, при --explain выводится читаемый план запроса. Триггеры: 'sql helper', 'sql генерация', 'сгенерируй sq…

- **Type:** Skill
- **Install:** `agentstack add skill-bestdeejay-design-agent-skills-sql-helper`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bestdeejay-design](https://agentstack.voostack.com/s/bestdeejay-design)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** https://github.com/bestdeejay-design/agent-skills/tree/main/skills/sql-helper
- **Website:** https://bestdeejay-design.github.io/agent-skills/

## Install

```sh
agentstack add skill-bestdeejay-design-agent-skills-sql-helper
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
# Сгенерировать 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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** [bestdeejay-design/agent-skills](https://github.com/bestdeejay-design/agent-skills)
- **License:** MIT
- **Homepage:** https://bestdeejay-design.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bestdeejay-design-agent-skills-sql-helper
- Seller: https://agentstack.voostack.com/s/bestdeejay-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.