SQL Query Copilot

Overview

Use this skill to turn plain-language requests into executable SQL with a predictable, low-risk workflow. Default to read-only execution and validate every query against schema before running.

Quick Start

Set SQL_DSN first (or pass --dsn each time).

# PowerShell
$env:SQL_DSN="mysql://user:password@127.0.0.1:3306/stock_monitor"
$env:SQL_DSN="postgres://user:password@127.0.0.1:5432/stock_monitor"
$env:SQL_DSN="sqlite:///d:/data/demo.db"

# Windows CMD
set SQL_DSN=mysql://user:password@127.0.0.1:3306/stock_monitor
set SQL_DSN=postgres://user:password@127.0.0.1:5432/stock_monitor
set SQL_DSN=sqlite:///d:/data/demo.db

# Bash / Zsh
export SQL_DSN="mysql://user:password@127.0.0.1:3306/stock_monitor"
export SQL_DSN="postgres://user:password@127.0.0.1:5432/stock_monitor"
export SQL_DSN="sqlite:///d:/data/demo.db"

Core commands:

python scripts/sql_easy.py tables
python scripts/sql_easy.py describe daily_kline
python scripts/sql_easy.py lint --sql "SELECT * FROM daily_kline"
python scripts/sql_easy.py explain --sql "SELECT code, close FROM daily_kline WHERE trade_date >= '2026-01-01'"
python scripts/sql_easy.py query --sql "SELECT code, close FROM daily_kline ORDER BY trade_date DESC" --limit 50
python scripts/sql_easy.py query --sql "SELECT code, close FROM daily_kline" --summary
python scripts/sql_easy.py ask --q "show symbols with old sell signals older than 20 days" --summary
python scripts/sql_easy.py profile

Set OPENAI_API_KEY (or pass --api-key) to use ask.

v0.2 Highlights

• Multi-engine support: MySQL, PostgreSQL, SQLite.
• SQL lint engine: catches high-risk patterns before execution.
• Explain mode: quickly inspect query plan (EXPLAIN / EXPLAIN QUERY PLAN).
• Natural-language mode: ask generates SQL from user intent.
• Query summary: auto profile returned columns (null ratio, distinct count, min/max/avg).
• Slow query warning: highlights expensive queries using --slow-ms.
• Audit log: write command metadata to JSONL via --audit-log or SQL_EASY_AUDIT_LOG.

Workflow

1. Clarify the metric and grain. Ask for time window, dimensions, and output columns before writing SQL.

2. Discover schema first. Run tables, describe <table>, and profile before any complex SQL.

3. Draft SQL in read-only mode. Use SELECT or WITH; keep columns explicit and add time filters.

4. Execute with guardrails. Run via scripts/sql_easy.py query, keep --limit unless full export is explicitly needed.

5. Validate results. Cross-check row count, null ratio, and edge dates; adjust query and rerun.

Guardrails

• Default to read-only SQL.
• Reject destructive statements (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, etc.).
• Prefer explicit columns over SELECT * for production/report queries.
• Run lint before heavy or scheduled queries.
• Run explain before approving complex joins/window queries.
• Always quote identifiers when table/column names are uncertain.
• For business decisions, provide both SQL and a short interpretation of returned data.

Query Patterns

Read references/query_patterns.md when creating:

• Top-N and ranking queries
• Time-window aggregation
• Dedup with window functions
• Funnel-style conditional counts
• Data quality checks (null/duplicate/outlier)

Read references/chanquant_templates.md for Chanquant-specific query templates.