Natural Language to SQL (NL2SQL) has become a cornerstone technology for data-driven enterprises in 2026, enabling analysts, PMs, and operational teams to query databases directly using conversational language. With the rise of large language models (LLMs), few-shot prompting, and schema grounding, it’s possible to create intelligent NL2SQL agents that understand database structures, maintain correctness, and generate executable SQL queries.

This tutorial walks through building a schema-aware NL2SQL agent, using best practices in prompt engineering, few-shot learning, and integration with LLMs.

Why Schema-Grounded NL2SQL Matters

Traditional Challenges:

• Ambiguity in natural language
• Risk of invalid SQL due to missing schema context
• Complexity with joins and nested queries

Advantages of Schema-Grounded Approach:

• Database-awareness: Agent knows table names, columns, relationships
• Reduced errors: Generates syntactically correct and semantically valid queries
• Dynamic prompting: Few-shot examples teach the model correct SQL patterns

Step 1 — Prepare Your Database Schema

Before querying, the agent must understand the database schema:

1. Extract metadata:

-- Example: Postgres tables and columns
SELECT table_name, column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'public';

2. Structure schema context as JSON for the LLM:

{
  "tables": {
    "users": ["id", "name", "email", "created_at"],
    "orders": ["id", "user_id", "amount", "order_date"]
  },
  "relationships": [
    {"from": "orders.user_id", "to": "users.id"}
  ]
}

This schema JSON will be passed to the agent to ground SQL generation.

Step 2 — Design Few-Shot Prompts

Few-shot prompting teaches the LLM how to map natural language queries to SQL.

Prompt Structure:

1. Instruction: “Convert the user’s question into SQL using this schema.”
2. Schema context: JSON representation of tables, columns, relationships
3. Examples: 3–5 question → SQL pairs
4. User query placeholder: {user_query}

Example Prompt:

Instruction: Convert the user question into SQL.
Schema: {"tables": {"users": ["id","name","email"], "orders": ["id","user_id","amount"]}}
Examples:
Q: How many orders did each user place?
SQL: SELECT user_id, COUNT(*) FROM orders GROUP BY user_id;

Q: List all users with their emails.
SQL: SELECT name, email FROM users;

User Question: {user_query}
SQL:

This ensures LLM output aligns with schema, reduces hallucination, and allows generalization.

Step 3 — Implement NL2SQL Agent

1. Choose LLM backend: OpenAI GPT-5, Claude 3, or self-hosted LLaMA derivatives.
2. Load schema context dynamically: Pull table/column info at runtime.
3. Inject few-shot examples dynamically depending on question type.
4. Send prompt to LLM and parse the output.

Python Example:

import openai

prompt = f"""
Instruction: Convert the user question into SQL.
Schema: {schema_json}
Examples:
{few_shot_examples}
User Question: {user_question}
SQL:
"""

response = openai.ChatCompletion.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": prompt}],
    temperature=0
)

sql_query = response.choices[0].message.content.strip()

Step 4 — Validate Generated SQL

Always validate SQL before execution:

• Check table & column existence
• Optionally run EXPLAIN plan to detect syntax issues
• Restrict queries for read-only access in production

try:
    cursor.execute(sql_query)
    results = cursor.fetchall()
except Exception as e:
    results = f"Error: {e}"

Validation avoids runtime errors and ensures enterprise safety.

Step 5 — Handle Complex Queries

Schema-grounded agents can support:

• Joins across multiple tables
• Aggregations and grouping
• Nested subqueries
• Filters and conditions extracted from natural language

Few-shot examples should include these patterns to improve generalization.

Step 6 — Optional: Feedback Loop and Memory

Enhance agent over time:

• Store user query → SQL → result in a vector database
• Use RAG (Retrieval-Augmented Generation) to reference past queries for suggestions or corrections
• Enable auto-tuning few-shot examples based on historical performance