NL2SQL Handbook: a living survey and guide to Text-to-SQL in the LLM era

What the NL2SQL Handbook is

Translating natural language into SQL, Text-to-SQL or NL2SQL, moves quickly, and keeping track of the techniques is itself a task. The NL2SQL Handbook is a continuously updated repository that does that tracking: it is the official home of a Text-to-SQL survey published in TKDE and a tutorial presented at VLDB, and it collects the latest research, benchmark evaluations and practical guidance in one place. The audience is researchers who need a current map of the field and practitioners deciding how to build a Text-to-SQL system. It is explicitly a handbook, a curated knowledge resource rather than a software library, so what it offers is organized understanding: a survey of where the field is and where it is going, in-depth papers, and comparisons, aimed at helping readers keep up with a fast-moving literature rather than shipping code you import.

Survey, tutorial and benchmarks in one place

The value is in the organization. The repository pairs a comprehensive survey with a conference tutorial and a curated, awesome-list style index of the Text-to-SQL literature, so a reader can move from a high-level overview to specific papers on a subtopic. It includes benchmark evaluations, which matter because Text-to-SQL progress is measured on shared datasets and a handbook that gathers those comparisons helps a practitioner judge methods rather than take claims at face value. The materials span the shift from earlier approaches to the LLM era, reflecting how large language models changed the field, and the repository carries slides and reports alongside the papers. Because it is continuously updated, its intent is to stay current as new methods appear, which is the whole point of a living handbook versus a single static survey that ages the moment it is published.

Using the handbook

There is nothing to install, because this is a reading and reference resource rather than a package. You browse the repository's chapters and the curated paper index, read the survey and the tutorial materials, and consult the benchmark comparisons when choosing or evaluating a method. The linked survey on arXiv is the entry point for the field overview, and the chapter and report directories organize the deeper material. For citing the work in your own research, the README provides the reference, and reproducing it verbatim is how you attribute the survey:

@article{liu2025survey,
  title={A Survey of Text-to-SQL in the Era of LLMs: Where are we, and where are we going?},
  journal={IEEE Transactions on Knowledge and Data Engineering},
  year={2025},
  publisher={IEEE}
}

The first real use is reading the survey to orient yourself, then following the curated index into the subtopics relevant to your work.

Where a handbook stops

The limitations follow from what it is. It is knowledge, not software, so it will not build a Text-to-SQL system for you; it helps you understand the options and then you implement or adopt one separately. A curated survey reflects its maintainers' selection and emphasis, and even a continuously updated one lags the very newest preprints, so it is a strong map rather than an exhaustive, real-time record. The benchmark comparisons it gathers are as current as its updates and as sound as the underlying evaluations, which in Text-to-SQL are themselves debated. And there is a licensing note: the repository ships no license file, so while the papers and materials are for reading, you have no explicit grant to redistribute the contents, which matters if you want to reuse figures or text rather than cite them. Treat it as a guide to inform decisions, not a source you repackage.

The handbook versus reading papers or building directly

The alternatives are reading the primary literature yourself or going straight to building with a tool like LangChain's SQL utilities. Reading papers directly gives you the unfiltered source but leaves you to find, order and compare them, which is exactly the labor the handbook saves by curating and surveying. Jumping straight to a Text-to-SQL library gets you a working prototype fastest, but without the grounding to know its limits, when it fails, on schema complexity, ambiguity or dialect, and how it compares to alternatives. The handbook's role is the middle: it gives you the map before you build, so your implementation choices are informed by the field's findings and benchmarks. Use it to decide what to build and what to expect, then reach for the papers for depth and for a tool or your own code to actually implement a system.

No license, and continuous updates

The status to hold in mind is that the NL2SQL Handbook is a living, continuously updated resource backed by peer-reviewed work, a TKDE survey and a VLDB tutorial, which gives its content academic grounding, but it ships no license file, so treat the materials as citable references rather than content you may freely redistribute. The last push was on 2026-08-31, consistent with its promise of ongoing updates, and it centers on the LLM era of Text-to-SQL, which is where the field is most active. Use it when you need to understand the current state of Text-to-SQL before designing or evaluating a system, start from the linked survey, follow the curated index into your subtopics, cite the work using the reference the README provides, and pair it with an implementation tool or your own code when you move from understanding to building.

Editorial conclusion

Use the NL2SQL Handbook if you research or build Text-to-SQL systems and want a current, curated map of the field, its survey, tutorial, papers and benchmark comparisons, before you design or evaluate a solution. Do not expect runnable software or a right to redistribute its contents, since it is a knowledge resource that ships no license file. Start from the linked TKDE survey, follow the curated index into your subtopics, cite the work with the reference the README gives, and pair it with an implementation tool when you move to building.

Frequently asked questions

Official sources

1. HKUSTDial/NL2SQL_Handbook on GitHub
2. Issues
3. Project website
4. README