Home

SQL Query Engine

A two-stage LLM-powered pipeline that converts natural language questions into validated PostgreSQL queries.

SQL Query Engine takes a plain-English question, generates a SQL query using a large language model, executes it against your PostgreSQL database, and — if the query fails — automatically repairs it through an iterative LLM-driven feedback loop. It exposes both a native REST API and a fully OpenAI-compatible API, making it usable with OpenWebUI, LangChain, the OpenAI Python/JS SDKs, or plain curl.

How It Works

flowchart TD
    A["Natural Language Question"] --> B["Stage 1: Generate<br/>(QueryGenerator)"]
    B --> |"Schema introspection → LLM generates SQL"| C["Stage 2: Evaluate<br/>(QueryEvaluator)"]
    C --> |"Execute query → if error, LLM repairs → retry"| D["Validated Results"]

Loading

Stage 1 — Generation: The engine introspects your PostgreSQL schema (tables, columns, sample rows), asks the LLM to describe it, then generates a SQL query from your natural language prompt.

Stage 2 — Evaluation & Repair: The generated query is executed. If it fails or returns no rows, the engine feeds the error back to the LLM, which diagnoses the issue and produces a corrected query. This loop repeats up to a configurable number of retries until a valid result is obtained. Queries that return rows are accepted immediately without an LLM call, preventing regressions. If all retries are exhausted, the best result seen across all attempts is returned.

Key Features

• Natural language to SQL — Ask questions in plain English, get executed query results
• Self-healing queries — Automatic LLM-driven repair loop with early-accept and best-result tracking
• OpenAI-compatible API — Drop-in replacement for /v1/chat/completions and /v1/models
• Streaming support — Server-Sent Events (SSE) for real-time progress and thinking traces
• Schema caching — Schema descriptions cached in Redis per session, eliminating redundant introspection
• Multi-turn conversations — Context preserved across requests using chatID / chat_id
• Read-only safety — PostgreSQL connections enforced as read-only; impossible to modify your data
• Configurable LLM backend — Works with any OpenAI-compatible model server (vLLM, Ollama, OpenAI, etc.)
• OpenWebUI integration — Pre-configured Docker Compose setup with OpenWebUI chat interface
• Evaluation suite — 3-config ablation study across synthetic databases (120 questions) and the BIRD benchmark (500 real-world questions across 11 databases), tested on 5 LLM backends

Tech Stack

Component	Technology
API Framework	FastAPI + Uvicorn
LLM Integration	LangChain (langchain-openai)
Database	PostgreSQL (psycopg3, read-only)
Session Store	Redis (hash store + Pub/Sub)
Response Parsing	Multi-strategy extraction (JSON → code block → SELECT regex → raw text) with Pydantic validation
Streaming	Server-Sent Events (SSE)
Containerization	Docker + Docker Compose

Wiki Pages

#	Page	Description
1	SQL Query Engine	This page — project overview and navigation
2	Architecture	System design, pipeline stages, data flow diagrams
3	Getting Started	Installation, Docker setup, first query
4	Configuration	All environment variables and connection parameters
5	API Reference	Complete endpoint documentation with request/response schemas
6	Usage Guide	Curl commands, SDK examples, multi-turn sessions
7	OpenAI Compatibility	Using the engine with OpenAI SDKs, LangChain, and OpenWebUI
8	Session Management	Redis architecture, schema caching, Pub/Sub streaming
9	Module Reference	Internal code documentation for contributors
10	Evaluation	Ablation study, synthetic benchmark results, evaluation pipeline
11	BIRD Benchmark	BIRD evaluation, SQLite→PostgreSQL migration, real-world results
12	Troubleshooting	Common issues, debugging tips, FAQ
13	Contributing	Development setup, code style, PR guidelines

Quick Start

# Clone the repository
git clone https://github.com/codeadeel/sqlqueryengine.git
cd sqlqueryengine

# Start all services (engine + Redis + OpenWebUI)
docker compose up --build

# Ask your first question
curl -s -X POST "http://localhost:5181/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meow123" \
  -d '{
    "model": "SQLBot",
    "messages": [{"role": "user", "content": "How many tables are in the database?"}],
    "stream": false
  }' | jq .

Evaluation

SQL Query Engine includes two independent evaluation pipelines, both using a 3-config ablation study to measure the impact of the self-healing loop:

• Synthetic Evaluation — 120 gold-annotated questions across 3 controlled PostgreSQL databases (e-commerce, hospital, university), seeded with reproducible Faker data
• BIRD Benchmark — 500 real-world questions from the BIRD mini-dev set across 11 databases, with automatic SQLite-to-PostgreSQL migration at runtime

Both pipelines test three configurations (Config C: generation only, Config B: single-shot, Config A: full self-healing with retryCount=5) across 5 LLM backends. On the BIRD benchmark, the self-healing loop provides up to +4.6 percentage points of improvement, with GPT-OSS 120B achieving 49.0% execution accuracy. On synthetic data, Llama 4 Scout 17B achieves 57.3% with a +9.3pp healing delta and zero regressions.

See Evaluation for synthetic results and BIRD Benchmark for real-world benchmark results.

License

This project is open source. See the repository root for license details.