🧠 SQL Agent – Natural Language to SQL Query Executor

sql-agent allows you to query your SQL Server database using plain English.
It leverages two LLMs for natural language → SQL translation:

• 🌐 Google Gemini (gemini-2.0-flash) – Cloud-hosted LLM.
• 💻 Ollama (Alwaleed98/walphi-sql) – Locally hosted SQL-tuned model.

⚡ Ideal for analytics, debugging, and quick insights without writing raw SQL.

---

🏗️ Architecture

The SQL Agent is built as a conversational pipeline that combines two LLMs and three specialized tools to transform natural language into safe, executable SQL queries.

🔄 Flow

1. User Query → A plain English question is sent to the API.
2. Gemini LLM (Core Orchestrator) → Interprets the question and coordinates tools.
3. DB Inspector Tool → Inspects the connected SQL Server database to fetch:
   • Table names
   • Column names
   • Data types
4. SQL Generator Tool (via SQL-tuned LLM, e.g. Ollama walphi-sql) → Uses the schema + user query context to generate a valid SQL statement.
5. SQL Executor Tool → Executes the generated SQL on the database (read-only mode recommended).
6. Gemini LLM → Wraps and refines the response into a conversational answer.
7. Response Returned → JSON output with final result.

---

🔧 Tools

• DB Inspector Tool

  Helps in getting the list of table names, column names, and data types of the SQL Server database.
  Used by Gemini to understand schema and context.

• SQL Generator Tool

  Generates SQL using schema metadata + user question.
  Ensures correct tables/columns are referenced.

• SQL Executor Tool

  Runs the generated SQL query on the target database and returns results.

---

📐 High-Level Diagram

sequenceDiagram
    participant U as User
    participant G as Gemini LLM (Orchestrator)
    participant I as DBInspector Tool
    participant S as SQL Generator Tool (Ollama LLM)
    participant E as SQL Executor Tool
    participant DB as SQL Server Database

    U->>G: Send natural language query
    G->>I: Fetch schema (tables, columns, data types)
    I-->>G: Return schema metadata
    G->>S: Generate SQL using query + schema
    S-->>G: Return SQL query
    G->>E: Send SQL query for execution
    E->>DB: Run SQL query
    DB-->>E: Return query results
    E-->>G: Results returned
    G-->>U: Conversational answer with results

Loading

🚀 Features

• 🔍 Natural Language to SQL – Ask questions in English, get valid SQL queries.
• 🗄️ Works with SQL Server – Supports connection via DSN string.
• ✅ Read-Only Mode – Recommended for safe SELECT queries.
• 📦 REST API – Simple endpoint for query execution.

---

🛠️ Installation & Setup

Clone the repository

git clone https://github.com/ksdkamesh99/sql-agent.git
cd sql-agent

Export Environment Variables

# SQL Server Connection (Read-Only)
export DATABASE_DSN_STRING=sqlserver://<user>:<password>@<host>:<port>?database=<DB_NAME>&sendStringParametersAsUnicode=false&ApplicationIntent=ReadOnly

# Gemini API Key
export GEMINI_API_KEY=your_gemini_api_key

Start the service

go run main.go

The API will be available at:

http://localhost:8080

🔑 Usage

Example Request

curl --location 'http://localhost:8080/query' \
--header 'Content-Type: application/json' \
--data '{
    "question": "what is the top 10 client ids who placed more number of orders today"
}'

Response

{
    "result": {
        "output": "The top 10 client ids who placed more number of orders today are: S60192979, SB0603, S59054059, S834210, C91239, S57566454, AAAI927921, S833402, CHIEF, and T59505150."
    }
}