Skip to content

Getting Started

Jump to bottom
codeadeel edited this page Apr 7, 2026 · 3 revisions

This guide walks you through setting up SQL Query Engine from scratch — whether you're using Docker (recommended) or running locally.

Prerequisites

  • Docker and Docker Compose (for containerized deployment)
  • Python 3.10+ (for local development)
  • PostgreSQL database you want to query (the engine connects as read-only)
  • Redis server (used for session caching and real-time streaming)
  • LLM server exposing an OpenAI-compatible /v1/chat/completions endpoint (vLLM, Ollama, OpenAI, Groq, etc.)

Option 1: Docker Compose (Recommended)

The Docker Compose setup starts three services: the SQL Query Engine, Redis, and OpenWebUI (a chat interface).

1. Clone the Repository

git clone https://github.com/codeadeel/sqlqueryengine.git
cd sqlqueryengine

2. Configure Environment

Edit docker-compose.yml to set your connection details. The key environment variables are in the sql-query-engine service definition:

environment:
  # LLM Configuration — point to your model server
  - LLM_BASE_URL=http://host.docker.internal:8001/v1
  - LLM_MODEL=your-model-name
  - LLM_API_KEY=your-llm-api-key
  - LLM_TEMPERATURE=0.7

  # PostgreSQL — the database you want to query
  - POSTGRES_HOST=host.docker.internal
  - POSTGRES_PORT=5432
  - POSTGRES_DB=your_database
  - POSTGRES_USER=your_user
  - POSTGRES_PASSWORD=your_password

  # Redis — handled by the compose stack
  - REDIS_HOST=qeredis
  - REDIS_PORT=6379
  - REDIS_PASSWORD=sqlPass

  # API authentication for /v1/* endpoints
  - OPENAI_API_KEY=your-api-key

3. Start the Stack

docker compose up --build

This brings up:

Service Internal Port Exposed Port Description
sql-query-engine 8080 5181 The API server
qeredis 6379 6380 Redis (session store)
openwebui 8080 5182 Chat UI (optional)

4. Verify It's Running

curl -s http://localhost:5181/ping | jq .

Expected response:

{
  "code": 200,
  "status": "[ SQL Query Engine ]: Agent is alive and reachable.",
  "agent": "sqlQueryEngine",
  "scheme": "http",
  "host": "localhost",
  "port": "5181",
  "clientHost": "172.18.0.1",
  "clientPort": 54321
}

5. Ask Your First Question

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

6. Open the Chat UI (Optional)

Navigate to http://localhost:5182 in your browser. OpenWebUI is pre-configured to use the SQL Query Engine as its backend model.

Option 2: Local Development

1. Clone and Install Dependencies

git clone https://github.com/codeadeel/sqlqueryengine.git
cd sqlqueryengine

# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Set Environment Variables

Export all required environment variables (see the Configuration page for the full list):

export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_MODEL="qwen2.5-coder:7b"
export LLM_API_KEY="ollama"
export LLM_TEMPERATURE="0.7"

export POSTGRES_HOST="localhost"
export POSTGRES_PORT="5432"
export POSTGRES_DB="mydb"
export POSTGRES_USER="postgres"
export POSTGRES_PASSWORD="secret"

export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD=""
export REDIS_DB="0"

export SERVER_HOST="0.0.0.0"
export SERVER_PORT="8080"
export OPENAI_API_KEY="my-secret-key"

3. Start the Server

python run.py

The server starts on http://localhost:8080 by default.

4. Verify and Query

# Health check
curl -s http://localhost:8080/ping | jq .

# Ask a question
curl -s -X POST "http://localhost:8080/inference/sqlQueryEngine/my-first-session" \
  -H "Content-Type: application/json" \
  -d '{"basePrompt": "How many tables are in the database?"}' | jq .

Testing with Curl Commands

Once running, you can test all endpoints using the provided script:

bash curlCommands.sh

This script contains curl commands for every API endpoint, including:

  • Health checks (/ping)
  • Schema introspection (/schema)
  • Query generation and execution (/inference, /v1/chat/completions)
  • Session management
  • Real-time streaming

See the Usage Guide wiki page for detailed examples of each endpoint.

Using with Ollama (Local LLM)

If you want a fully local setup with no cloud dependencies, use Ollama:

# Install and start Ollama
ollama serve

# Pull a model
ollama pull qwen2.5-coder:7b

# Configure the engine to use Ollama
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_MODEL="qwen2.5-coder:7b"
export LLM_API_KEY="ollama"

Running the Evaluation Suite

The repository includes two evaluation pipelines for benchmarking the self-healing loop. Both use a 3-config ablation study tested across 5 LLM backends.

Synthetic Evaluation (Controlled Environment)

Tests against 3 PostgreSQL databases seeded with reproducible Faker data (120 gold-annotated questions). See Evaluation for full details.

# 1. Set LLM credentials in docker-compose-synthetic-evaluation.yml
#    Edit: LLM_BASE_URL, LLM_MODEL, LLM_API_KEY

# 2. Build and launch
docker compose -f docker-compose-synthetic-evaluation.yml build
docker compose -f docker-compose-synthetic-evaluation.yml up -d

# 3. Monitor progress
docker logs eval-runner --tail 10 -f

# 4. Results appear in evaluation/synthetic/results/

BIRD Benchmark (Real-World Databases)

Tests against the BIRD mini-dev set (500 questions across 11 real-world databases). Requires downloading the BIRD dataset first. See BIRD Benchmark for full details.

# 1. Download BIRD dataset into evaluation/bird/bird_data/
#    (mini_dev_sqlite.json + dev_databases/ folder)

# 2. Set LLM credentials in docker-compose-bird-evaluation.yml
#    Edit: LLM_BASE_URL, LLM_MODEL, LLM_API_KEY

# 3. Build and launch
docker compose -f docker-compose-bird-evaluation.yml build
docker compose -f docker-compose-bird-evaluation.yml up -d

# 4. Monitor progress
docker logs bird-runner --tail 10 -f

# 5. Results appear in evaluation/bird/bird_results/

What Gets Evaluated

Both pipelines test three configurations:

  • Config C: Generation only (baseline, no execution or healing)
  • Config B: Single-shot (full pipeline with retryCount=1)
  • Config A: Full self-healing (full pipeline with retryCount=5)

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

What's Next?

📄 Paper: arXiv:2604.16511 | 📊 Dataset: Hugging Face | 💻 Source: GitHub

SQL Query Engine

Design

Setup

API

Internals

Evaluation

Help

Clone this wiki locally