We present SQL Query Engine, an open-source, self-hosted service that translates natural language questions into validated PostgreSQL queries through a two-stage LLM pipeline. The first stage performs automatic schema introspection and SQL generation; a multi-strategy response parser extracts SQL from any LLM output format (JSON, code blocks, or raw text) without requiring structured output APIs. The second stage executes the query against PostgreSQL and, upon failure or empty results, enters an iterative self-healing loop in which the LLM diagnoses the error using full SQLSTATE codes and PostgreSQL diagnostic messages. Two mechanisms prevent regressions: early-accept returns successful queries immediately without LLM re-evaluation, and best-result tracking preserves the best partial result across retries. Schema context is cached per session in Redis, progress events stream via Redis Pub/Sub and SSE, and an OpenAI-compatible /v1/chat/completions endpoint lets existing tools work without modification. All database connections are read-only at the driver level. We evaluate across five LLM backends on a synthetic benchmark (75 questions, three databases) where the self-healing loop yields up to +9.3pp accuracy gains with zero regressions on the best model (Llama 4 Scout 17B, 57.3%), and on BIRD (437 questions, 11 databases migrated from SQLite to PostgreSQL) where the full pipeline reaches 49.0% execution accuracy (GPT-OSS-120B, +4.6pp). Source code: https://github.com/codeadeel/sqlqueryengine.
Figures & tables
Figure 1: Synthetic benchmark: execution accuracy (bars, left axis) and average query latency (lines, right axis) before and after self-healing. Scout achieves the highest accuracy (57.3%, +9.3pp) with moderate latency increase (1.67s → 4.19s). The latency cost of self-healing scales with the number of repair iterations needed.
Figure 2: Detailed architecture of SQL Query Engine. Stage 1 introspects the schema, generates SQL via the LLM, and extracts it through a five-strategy response parser (with <think> tag stripping for reasoning models). Stage 2 executes queries with early-accept for immediate success and a self-healing loop with best-result tracking for failures. Redis provides both session caching and Pub/Sub-based SSE streaming (dashed arrow). All PostgreSQL connections are read-only at the driver level.
Module
Responsibility
engine.py
Orchestrates Stages 1 and 2; exposes run() , generate() , and evaluate() methods for full-pipeline, generation-only, and evaluation-only execution.
queryGenerator.py
Stage 1: introspects the database schema via dbHandler , generates a detailed schema description through the LLM, caches it in Redis, and produces an initial SQL query extracted via a multi-strategy response parser.
queryEvaluator.py
Stage 2: executes the query against PostgreSQL, captures errors, invokes the LLM evaluator, and iterates until success or retry exhaustion. Publishes progress to Redis Pub/Sub.
Redis-backed session store: serializes/deserializes LangChain [ 24 ] message objects, manages per-user context hashes, and maintains an auto-incrementing evaluation history counter.
openaiCompat.py
Implements the OpenAI-compatible /v1/chat/completions , /v1/completions , and /v1/models endpoints with SSE streaming and Bearer token authentication.
Table 1: Core modules of SQL Query Engine.
Figure 3: The self-healing evaluation loop. Key design choices are highlighted in teal : early-accept (line 6) prevents regressions by never re-evaluating successful queries; best-result tracking (line 7) ensures graceful degradation on retry exhaustion (line 12). The isValid self-assessment is ignored (line 8); only execution determines success.
Figure 4: Decision flow within the self-healing loop. The two key safety mechanisms are: early-accept (top right), which returns successful queries immediately without LLM re-evaluation; and best-result tracking (bottom right), which returns the best partial result when retries exhaust. Each iteration publishes progress to Redis Pub/Sub for real-time client visibility.
Model
C
B
A
Δ (C → A)
Regr.
GPT-OSS-20B
45.3
45.3
53.3
+8.0
0
Llama 3.3-70B
53.3
54.7
54.7
+1.4
2
GPT-OSS-120B
50.7
49.3
48.0
− 2.7
4
Llama 4 Scout-17B
48.0
50.7
57.3
+9.3
0
Qwen3-32B
48.0
42.7
46.7
− 1.3
6
Table 2: Synthetic benchmark: execution accuracy (%) across three configurations and five LLM backends (75 questions). Delta is the change from Config C to Config A. Regr. counts questions correct in Config C but incorrect in Config A.
Model
Easy
Medium
Hard
Extra Hard
GPT-OSS-20B
95.2
66.7
44.4
0.0
Llama 3.3-70B
100.0
77.8
27.8
5.6
GPT-OSS-120B
100.0
55.6
27.8
0.0
Llama 4 Scout-17B
100.0
77.8
44.4
0.0
Qwen3-32B
95.2
61.1
22.2
0.0
Table 3: Synthetic benchmark: accuracy by difficulty tier under Config A (%). Easy questions (21) are near-saturated; the self-healing loop has its largest effect on hard queries.
Model
C
B
A
Δ (C → A)
Regr.
GPT-OSS-20B
43.5
39.8
43.2
− 0.3
24
Llama 3.3-70B
43.7
38.0
46.5
+2.8
23
GPT-OSS-120B
44.4
42.6
49.0
+4.6
19
Llama 4 Scout-17B
37.1
34.3
40.5
+3.4
20
Qwen3-32B
40.7
41.6
39.4
− 1.3
17
Table 4: BIRD benchmark: execution accuracy (%) across three configurations and five LLM backends (437 questions after excluding 63 unconvertible queries). The self-healing loop yields up to +4.6pp improvement.
Model
Simple
Moderate
Challenging
GPT-OSS-20B
54.9
42.3
25.0
Llama 3.3-70B
55.6
47.9
26.2
GPT-OSS-120B
59.9
48.8
30.0
Llama 4 Scout-17B
49.3
41.4
22.5
Qwen3-32B
47.2
40.0
23.8
Table 5: BIRD benchmark: accuracy by difficulty tier under Config A (%). BIRD uses three tiers: simple (284 questions), moderate (113), and challenging (40).
Avg. Latency (s)
Throughput (QPM)
Latency p90 (s)
Model
C
A
C
A
C
A
Synthetic (75 questions)
GPT-OSS-20B
1.72
3.72
64.3
30.2
—
9.8
Llama 3.3-70B
2.44
4.12
44.7
27.2
—
10.0
GPT-OSS-120B
2.83
7.00
37.9
16.1
—
20.7
Scout-17B
1.67
4.19
63.8
27.0
—
9.2
Table 6: Latency and throughput cost of self-healing. Avg. latency in seconds; throughput in questions per minute (QPM); p90 latency for Config A in seconds.
Figure 5: Execution accuracy before (Config C) and after (Config A) the self-healing loop on both benchmarks. Scout leads on synthetic data (+9.3pp), GPT-OSS-120B leads on BIRD (+4.6pp).