🧠 Text-to-SQL Query App using Hugging Face API (DeepSeek Model)

A FastAPI-based application that converts natural language questions into SQL queries using the Hugging Face Inference API. This project uses the DeepSeek model to interpret user queries, generate SQL commands, execute them on a database, and return the results — all automatically.

---

🚀 Features

• Converts natural language questions into SQL queries
• Executes the generated SQL on a local SQLite database
• Uses Hugging Face Inference API (no local model load required)
• Lightweight and fast (no GPU dependency)
• Built with FastAPI + Uvicorn

---

🧩 Tech Stack

Component	Technology
Backend Framework	FastAPI
Language Model	DeepSeek (Hugging Face API)
Database	SQLite
Environment	Python 3.10+
Deployment	Uvicorn (for local or production runs)

---

📦 Installation & Setup

1️⃣ Clone the repository

git clone https://github.com/<your-username>/text-to-sql-huggingface.git
cd text-to-sql-huggingface

---

2️⃣ Create and activate a virtual environment

python3 -m venv venv
source venv/bin/activate       # For Linux/Mac
venv\Scripts\activate          # For Windows

---

3️⃣ Install dependencies

pip install -r requirements.txt

Your requirements.txt should include:

fastapi
uvicorn
sqlite-utils
python-dotenv
huggingface-hub

---

4️⃣ Create a .env file

Create a .env file in your project root:

HF_API_KEY=your_huggingface_api_key_here
HF_MODEL=deepseek-ai/DeepSeek-V3.2-Exp
DATABASE_PATH=./sample.db

🔑 You can get your Hugging Face API key from: https://huggingface.co/settings/tokens

---

5️⃣ Create a sample SQLite database (for testing)

You can create a simple SQLite database like this:

import sqlite3

conn = sqlite3.connect("sample.db")
cur = conn.cursor()

cur.execute("""
CREATE TABLE customers (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT,
    email TEXT,
    city TEXT,
    join_date TEXT
);
""")

cur.executemany("""
INSERT INTO customers (name, email, city, join_date)
VALUES (?, ?, ?, ?)
""", [
    ("John Doe", "john@example.com", "Delhi", "2023-01-01"),
    ("Jane Smith", "jane@example.com", "Mumbai", "2022-05-14"),
    ("Ravi Kumar", "ravi@example.com", "Delhi", "2021-11-11")
])

conn.commit()
conn.close()

---

⚙️ Project Structure

text-to-sql-huggingface/
│
├── main.py                 # FastAPI entrypoint
├── llm_utils.py            # Handles Hugging Face API calls
├── database.py             # SQLite helper functions
├── requirements.txt
├── .env
└── README.md

---

🧠 Core Logic Overview

🔸 Prompt Logic (llm_utils.py)

The DeepSeek model receives a minimal structured prompt:

You are a Text-to-SQL assistant.
Given a database schema and a user question, write a single SELECT query.

Return only the SQL query — no explanations or markdown.

Example query input:

{ "question": "List names and emails of customers from Delhi" }

Expected model output:

SELECT name, email FROM customers WHERE city = 'Delhi';

---

🧩 Running the Application

Start the FastAPI server:

uvicorn main:app --reload

Now open your browser or use cURL:

Test endpoint

curl -X POST "http://127.0.0.1:8000/query" \
     -H "Content-Type: application/json" \
     -d '{"question": "List names and emails of customers from Delhi"}'

Example JSON Response:

{
  "sql": "SELECT name, email FROM customers WHERE city = 'Delhi';",
  "result": [
    { "name": "John Doe", "email": "john@example.com" },
    { "name": "Ravi Kumar", "email": "ravi@example.com" }
  ]
}

---

⚡ Example Hugging Face API Test (Optional)

You can test your Hugging Face connection directly:

from huggingface_hub import InferenceClient
import os

client = InferenceClient(api_key=os.getenv("HF_API_KEY"))
response = client.chat.completions.create(
    model=os.getenv("HF_MODEL"),
    messages=[
        {"role": "system", "content": "Return only SQL query"},
        {"role": "user", "content": "Show customers from Delhi"}
    ]
)
print(response.choices[0].message.content)

---

🧩 Troubleshooting

Error	Reason	Fix
400: Only single SELECT queries allowed	Model returned multiple statements or explanations	Refine your prompt to ensure only one SELECT query
401 Unauthorized	Invalid Hugging Face API key	Check .env file and re-add token
Empty or invalid SQL output	Model response not formatted as SQL	Use improved prompt (see llm_utils.py)

---

🔮 Future Enhancements

• Support multiple databases (MySQL, PostgreSQL)
• Add web-based UI for interactive queries
• Integrate OpenAI or Ollama models as alternatives
• Include query optimization layer

---

📚 Reference Blog

For a detailed guide on the project concept, visit: 👉 Building Text-to-SQL Apps with Hugging Face API and FastAPI

---

🧑‍💻 Author

Bhai Tabahi 🎥 YouTube: CodeInfiltr4tor 💻 GitHub: github.com/CodeInfiltr4tor 🚀 Projects on FastAPI • Cybersecurity • AI Apps

---

🪪 License

This project is licensed under the MIT License — feel free to use and modify it.