Text to SQL

Use when (1) user describes what data they want in plain English and asks for the corresponding SQL query. (2) user says "write SQL for this", "convert to query", "how do I select", or "give me the SQL". (3) user provides a database schema or table descriptions and asks a question answerable by SQL.

Core Position

This skill solves the specific problem of: non-technical users who know what data they want cannot translate their intent into SQL — they need a bridge from natural language to query.

This skill IS NOT:

• A SQL execution environment — it writes queries, does not run them
• A schema design tool — it works with existing schema the user provides
• A data analysis tool — it produces SQL, not results or insights

This skill IS activated ONLY when: natural language description + database schema + SQL request are all present.

Modes

/text-to-sql

Default mode. Converts natural language into a syntactically correct SQL query.

When to use: User describes data needs and provides schema — wants the query.

/text-to-sql/explain

Outputs the SQL query with inline comments explaining each clause.

When to use: User wants to understand the query while seeing it, for learning purposes.

/text-to-sql/alternatives

Provides 2-3 alternative query approaches (different JOINs, subqueries vs CTEs, etc.).

When to use: User is learning SQL or wants to compare query strategies.

Execution Steps

Step 1 — Confirm Schema

1. Receive natural language request and detect if schema is present
2. Schema may be provided as:
   • Table/column names explicitly in the request
   • A CREATE TABLE statement
   • A DESCRIBE output
   • Column names from a previous query
3. If schema is NOT provided, ask the user for it before proceeding — do not guess table or column names
4. Build a schema map: table_name → {column: type}

Step 2 — Translate Intent to SQL Clauses

Map natural language intent to SQL components:

Step 3 — Handle Joins and Relationships

If the request involves multiple tables:

1. Identify which tables contain the needed columns
2. Determine the join key (foreign key relationship)
3. Select join type: INNER JOIN (default), LEFT JOIN (if some side may be empty), RIGHT JOIN (rare)
4. Write join on the correct key pair

If schema doesn't include relationship info, ask user to clarify which column links the tables.

Step 4 — Generate and Validate

SELECT
  o.order_id,
  o.created_at,
  c.customer_name,
  SUM(o.total_amount) AS total_revenue
FROM orders o
INNER JOIN customers c ON o.customer_id = c.id
WHERE o.created_at >= '2024-01-01'
GROUP BY o.order_id, o.created_at, c.customer_name
ORDER BY total_revenue DESC
LIMIT 10;

Check:

• All columns referenced exist in the schema
• All table aliases are defined
• JOIN conditions are valid (same type, correct keys)
• No ambiguous column references (all tables have aliases)
• Aggregate queries have appropriate GROUP BY

Mandatory Rules

Do not

• Do not invent table names or column names not in the provided schema
• Do not use SQL keywords as column names without backtick quoting where needed
• Do not write SELECT * in production queries — list specific columns
• Do not assume which table a column belongs to — qualify all column references

Do

• Ask for schema information before writing the query if it wasn't provided
• Qualify all column references with table aliases (e.g., o.order_id)
• Use backtick or quoted identifiers if column names are SQL reserved words
• Provide both the query and a one-line plain English translation of what it does

Quality Bar

A good output:

• Query is syntactically correct for the stated dialect (PostgreSQL, MySQL, SQLite, etc.)
• All column and table names match the provided schema exactly
• JOIN conditions are valid and use the correct key types
• The query actually answers the stated question

A bad output:

• References a column not in the schema
• SELECT * without justification in a query that should return specific columns
• Missing GROUP BY for an aggregate query
• JOIN on mismatched types (string ID to integer ID)

Good vs. Bad Examples

References

• references/ — SQL dialect cheat sheet (PostgreSQL, MySQL, SQLite), JOIN types and when to use each, common intent-to-clause mapping