---
name: sql-query-writer
description: Turn natural-language questions into validated, safe SQL against a known schema — with dry-run support.
title: SQL Query Writer
category: code-development
difficulty: intermediate
license: Apache-2.0
author: admin
source_url: "https://github.com/defog-ai/sqlcoder"
icon: 🗃️
input: text
output: structured-json
phase: transform
domain: code
tags: sql,text-to-sql,schema-aware,query-validation,dry-run,llm,postgres,mysql,sqlite,explain-plan,natural-language,database
best_for:
  - Converting natural-language questions to validated SQL queries
  - Preventing hallucinated column names and incorrect joins
  - Multi-dialect SQL generation with safety guardrails
  - Self-correcting LLM loops using query plan feedback
---

## Description

Packaged skill for text-to-SQL that enforces schema awareness. Fetches table definitions, injects them as few-shot context, and always EXPLAINs before executing. Includes a dialect adapter for Postgres, MySQL, and SQLite.

## Why it works

LLMs hallucinate column names and join keys when they don't see the schema, and silently produce queries that run but return wrong results. Forcing schema injection + an EXPLAIN-first validation step catches the two dominant failure modes (wrong columns, missing joins) before the query touches the database. The EXPLAIN output is also cheap feedback the LLM can self-correct against, turning a one-shot prompt into a verifiable loop.

## How it works

1) Connect, pull `information_schema.columns` + foreign-key graph, cache per-session. 2) Pick the top-k tables by fuzzy token match against the user question; inject their DDL as skill context. 3) Generate SQL in the target dialect with a system prompt that requires CTEs over subqueries. 4) Run `EXPLAIN` (Postgres) or `EXPLAIN QUERY PLAN` (SQLite); parse row-estimate + missing-index warnings. 5) If a LIMIT is missing and the estimate exceeds 10k, auto-append `LIMIT 1000`. 6) Return `{sql, plan_summary, est_rows}` — the model can read the plan and refine.