Configuration

SQL Query Engine is configured through environment variables. When an environment variable is set, the corresponding query parameter becomes optional on native /inference/* endpoints. When it is not set, the query parameter becomes required.

Environment Variables

LLM Configuration

Variable	Default	Description
LLM_BASE_URL	"" (empty)	Base URL of your OpenAI-compatible LLM server. Required.
LLM_MODEL	"" (empty)	Model name to use for SQL generation and evaluation. Required.
LLM_API_KEY	"" (empty)	API key for the LLM server. Required.
LLM_TEMPERATURE	not set	Temperature for LLM generation (0.0 = deterministic, 1.0 = creative). Required.

The engine works with any server that implements the OpenAI /v1/chat/completions API: vLLM, Ollama, OpenAI, Azure OpenAI, Together AI, Groq, etc.

PostgreSQL Configuration

Variable	Default	Description
POSTGRES_HOST	"" (empty)	PostgreSQL server hostname. Required.
POSTGRES_PORT	not set	PostgreSQL server port. Required.
POSTGRES_DB	"" (empty)	Database name to connect to. Required.
POSTGRES_USER	"" (empty)	Database username. Required.
POSTGRES_PASSWORD	not set	Database password. Required.

Important: The engine always connects in read-only mode via conn.set_read_only(True). Your database credentials only need SELECT privileges.

Redis Configuration

Variable	Default	Description
REDIS_HOST	"" (empty)	Redis server hostname. Required.
REDIS_PORT	not set	Redis server port. Required.
REDIS_PASSWORD	not set	Redis password. Required (use empty string "" for no auth).
REDIS_DB	not set	Redis database number (0–15). Required.

Redis is used for two purposes: session caching (schema descriptions, chat histories) and real-time Pub/Sub streaming.

Server Configuration

Variable	Default	Description
SERVER_HOST	0.0.0.0	Bind address for the Uvicorn server
SERVER_PORT	8080	Port for the Uvicorn server
SERVER_WORKERS	1	Number of Uvicorn worker processes

Bot & Feature Configuration

Variable	Default	Description
BOT_NAME	SQLBot	Display name used in LLM system prompts
SPLIT_IDENTIFIER	<|-/|-/>	Delimiter between Pub/Sub message tags and content
OPENAI_API_KEY	(empty)	Bearer token(s) for /v1/* endpoint authentication. Comma-separated for multiple keys. If empty, authentication is disabled.
COMPLETIONS_MODEL_NAME	value of BOT_NAME	Model name returned by GET /v1/models and echoed in completion responses

Pipeline Defaults (OpenAI-Compatible Routes)

These defaults apply to the /v1/chat/completions and /v1/completions routes, which don't have query parameter overrides:

Variable	Default	Description
DEFAULT_RETRY_COUNT	5	Default number of repair loop iterations
DEFAULT_SCHEMA_EXAMPLES	5	Default number of sample rows per table during schema introspection
DEFAULT_FEEDBACK_EXAMPLES	3	Default number of result rows fed back to the LLM evaluator

Synthetic Evaluation Configuration

These variables are used by docker-compose-synthetic-evaluation.yml:

Variable	Default	Description
EVAL_MAX_WORKERS	3	Number of parallel question workers (1–6, depends on rate limits)
QUESTIONS_PER_DB	25	Questions per database (25 for quick runs, 40 for full evaluation)

BIRD Benchmark Configuration

These variables are used by docker-compose-bird-evaluation.yml:

Variable	Default	Description
BIRD_DATA_DIR	/app/bird_data	Path to BIRD dataset (SQLite files + questions JSON)
BIRD_RESULTS_DIR	/app/bird_results	Output directory for BIRD results
BIRD_DATASET	mini	Which BIRD subset: mini (500 questions) or full (1,534 questions)
BIRD_USE_EVIDENCE	true	Prepend BIRD evidence hints to prompts. Set to false for zero-shot evaluation.
EVAL_MAX_WORKERS	4	Number of parallel question workers (tune based on LLM rate limits)
TIMEOUT_SECONDS	180	Per-request timeout in seconds

Per-Request Query Parameter Overrides

The native /inference/* endpoints accept query parameters that override the environment variables for that single request. This is useful for testing against different databases or LLM models without restarting the server.

Note: The OpenAI-compatible /v1/* endpoints do not support query parameter overrides — they read exclusively from environment variables.

Connection Override Parameters

Parameter	Overrides
llmBaseURL	LLM_BASE_URL
llmModel	LLM_MODEL
llmAPIKey	LLM_API_KEY
llmTemperature	LLM_TEMPERATURE
postgreHost	POSTGRES_HOST
postgrePort	POSTGRES_PORT
postgreDBName	POSTGRES_DB
postgreUser	POSTGRES_USER
postgrePassword	POSTGRES_PASSWORD
redisHost	REDIS_HOST
redisPort	REDIS_PORT
redisPassword	REDIS_PASSWORD
redisDB	REDIS_DB

Example: Override All Connection Params

curl -s -X POST "http://localhost:5181/inference/sqlQueryEngine/my-session\
?llmBaseURL=http://localhost:11434/v1\
&llmModel=qwen2.5-coder:7b\
&llmAPIKey=ollama\
&llmTemperature=0.1\
&postgreHost=localhost\
&postgrePort=5432\
&postgreDBName=mydb\
&postgreUser=postgres\
&postgrePassword=secret\
&redisHost=localhost\
&redisPort=6379\
&redisPassword=\
&redisDB=0" \
  -H "Content-Type: application/json" \
  -d '{"basePrompt": "How many records are in each table?"}' | jq .

Pipeline Parameters (Request Body)

These parameters control the pipeline behavior and are passed in the JSON request body of native /inference/* endpoints:

Parameter	Type	Default	Description
basePrompt	string	(required)	The natural language question
retryCount	int	5	Max repair loop iterations in Stage 2
schemaExamples	int	5	Number of sample rows per table during introspection
feedbackExamples	int	3	Number of result rows fed back to the LLM evaluator
schemaDescriptionKey	string	"dbSchemaDescription"	Redis hash field key for cached schema. Change this to force a fresh schema generation.
extraPayload	object	null	Arbitrary JSON passed through to the response untouched

Docker Compose Port Mapping

The default docker-compose.yml maps ports as follows:

Service	Container Port	Host Port
sql-query-engine	8080	5181
qeredis (Redis)	6379	6380
openwebui	8080	5182

To change exposed ports, edit the ports section in docker-compose.yml:

ports:
  - "YOUR_PORT:8080"  # host:container

Authentication

API Key Setup

Set OPENAI_API_KEY to enable Bearer token authentication on all /v1/* endpoints:

# Single key
export OPENAI_API_KEY="my-secret-key"

# Multiple keys (comma-separated)
export OPENAI_API_KEY="key1,key2,key3"

When set, all requests to /v1/* must include the header:

Authorization: Bearer my-secret-key

When OPENAI_API_KEY is empty or unset, authentication is completely disabled (useful for development).

Native Endpoints

The /inference/* endpoints do not require authentication. If you need to restrict access, use a reverse proxy (nginx, Caddy, etc.) in front of the engine.