Text-to-SQL turns a plain-language question into a SQL query, runs it against your database, and summarizes the rows back in prose. A shippable implementation has five stages \u2014 schema injection, SQL generation, validation, execution, and result summarization \u2014 and enforces read-only access at the database layer rather than trusting the prompt.<\/p>\n\n\n\n
That last clause is the whole article. Most text-to-SQL demos work on a three-table toy schema and fail the moment a real user types “delete the stale rows and show me the rest.”<\/em> Below is the pipeline, the schema-representation choices that decide your accuracy ceiling, and the guards that decide whether you are allowed to ship.<\/p>\n\n\n\n Text-to-SQL is not retrieval-augmented generation with a database bolted on. RAG retrieves documents<\/em> and answers from their text; text-to-SQL compiles a question into an executable program<\/em> and answers from a computed result set. That distinction matters because the failure modes are completely different: RAG fails by retrieving the wrong passage, text-to-SQL fails by producing a query that runs and returns a confidently wrong number.<\/p>\n\n\n\n Three product shapes justify the engineering cost:<\/p>\n\n\n\n The decision criterion is the shape of the answer. If the answer is a number, a small table, or a time series computed from structured columns, text-to-SQL wins. If the answer is prose synthesized from unstructured text, you want embeddings and retrieval instead. And if the question space is genuinely open \u2014 an undocumented 400-table warehouse where nobody agrees on what a “customer” is \u2014 no prompt will save you; fix the schema first.<\/p>\n\n\n\n One more boundary: latency. A text-to-SQL turn costs at least one generation round trip, often two when the first query errors. Do not put it on a path that must answer in under 100 ms.<\/p>\n\n\n\n The naive mental model is a straight line. The correct model is a loop with a feedback edge, because the database itself is the best validator you have:<\/p>\n\n\n\n Four implementation details carry most of the value:<\/p>\n\n\n\n Schema representation is the single highest-leverage decision in the whole system, and it is decided before the model sees anything. Build it in three layers:<\/p>\n\n\n\n For small databases you can paste all three layers into every prompt. Past roughly 50 tables that stops working, and you need pruning. These are the techniques worth knowing, in the order you should reach for them:<\/p>\n\n\n\nWhat text-to-SQL is and where it fits<\/h2>\n\n\n\n
\n
The pipeline, stage by stage<\/h2>\n\n\n\n
user question\n |\n v\n (1) SCHEMA INJECTION prompt = rules + DDL + column descriptions + few-shot pairs\n |\n v\n (2) GENERATE model returns JSON: { sql, tables_used, assumptions, confidence }\n |\n v\n (3) VALIDATE parse AST -> single statement? SELECT only? known tables? LIMIT?\n | | fail\n | +--> back to (2) with the validation error, max 2 retries\n v pass\n (4) EXECUTE read-only role + statement_timeout + row cap, on a replica\n | | DB error\n | +--> back to (2) with the raw driver error text\n v rows\n (5) SUMMARIZE model turns question + SQL + capped rows into prose + chart hint<\/code><\/pre>\n\n\n\n\n
column users.signup_date does not exist<\/code> tells the model exactly what to fix; “your SQL was wrong” does not.<\/li>\nsql<\/code>, tables_used<\/code>, assumptions<\/code>, and confidence<\/code> fields. You get a parseable query, an audit trail, and a routing signal for free \u2014 the mechanics are covered in our guide to structured outputs<\/a>.<\/li>\n<\/ul>\n\n\n\nSchema representation: the accuracy ceiling you set before you prompt<\/h2>\n\n\n\n
\n
CREATE TABLE<\/code> statements, including primary keys, foreign keys, and nullability. This gives the model types and join paths without you describing them.<\/li>\nstatus = 'churned'<\/code> (no login for 90 days) lives in someone’s head, not in the DDL.<\/li>\n