🧠 NaturalSQL

AI-Powered Natural Language to SQL Engine

Ask questions in plain English — get PostgreSQL queries instantly.

---

✨ What is NaturalSQL?

NaturalSQL bridges the gap between human language and database queries. Powered by Defog's SQLCoder-7b-2 — a fine-tuned LLM purpose-built for text-to-SQL — it lets you query your PostgreSQL database using everyday English.

Example:
💬 "What was our revenue by product in the New York region last month?"
➜ Returns a fully-formed, executable PostgreSQL query and the results.

---

🏗️ Architecture

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│  Natural Language │────▶│  SQLCoder-7b-2   │────▶│  PostgreSQL Query    │
│  Question         │     │  (HuggingFace)   │     │  (auto-generated)    │
└──────────────────┘     └──────────────────┘     └─────────┬────────────┘
                                                            │
                                                            ▼
                                                  ┌──────────────────────┐
                                                  │  Google Cloud SQL    │
                                                  │  (PostgreSQL)        │
                                                  └─────────┬────────────┘
                                                            │
                                                            ▼
                                                  ┌──────────────────────┐
                                                  │  Tabular Results     │
                                                  │  (pandas DataFrame)  │
                                                  └──────────────────────┘

---

🛠️ Tech Stack

Component	Technology
LLM	SQLCoder-7b-2 (Defog)
Framework	PyTorch + HuggingFace Transformers
Database	Google Cloud SQL (PostgreSQL)
Connector	Cloud SQL Python Connector + pg8000
Data	pandas DataFrames

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• CUDA GPU (recommended — min 8 GB VRAM for 8-bit, 15 GB+ for float16)
• A Google Cloud SQL PostgreSQL instance with the sales schema

1. Clone & Install

git clone https://github.com/your-username/NaturalSQL.git
cd NaturalSQL

pip install torch transformers bitsandbytes accelerate sqlparse \
            cloud-sql-python-connector "cloud-sql-python-connector[pymysql]" \
            pg8000 pandas python-dotenv

2. Configure Environment

cp .env.template .env

Edit .env with your credentials:

CLOUD_SQL_INSTANCE=your-project:your-region:your-instance
DB_USER=postgres
DB_PASSWORD=your-secure-password
DB_NAME=sales_db
MODEL_NAME=defog/sqlcoder-7b-2

Caution

Never commit the .env file. It is already listed in .gitignore.

3. Run

python sqlcoder.py

---

💬 Example Usage

============================================================
  NaturalSQL — Ask questions in plain English
  Type 'quit' or 'exit' to stop.
============================================================

❓ Your question: Show me all products with their stock quantities.

🔄 Generating SQL …

📝 Generated SQL:
SELECT p.name,
       i.stock_level
FROM products p
JOIN inventory i ON p.product_id = i.product_id;

Execute this query? [Y/n]: y

⏳ Running query …

✅ Results (5 rows):

       name  stock_level
  Product A          100
  Product B          200
  Product C          150
  Product D           75
  Product E          300

---

📂 Project Structure

NaturalSQL/
├── sqlcoder.py                          # Main application
├── final_defog_sqlcoder_colab.ipynb     # Original Colab notebook
├── .env.template                        # Environment variable template
├── .gitignore                           # Git ignore rules
└── README.md                            # This file

---

📊 Database Schema

The application works with the following PostgreSQL tables:

Table	Description
products	Product catalog with pricing & stock
customers	Customer names and addresses
salespeople	Sales team with regional assignments
sales	Individual sale transactions
product_suppliers	Supplier pricing per product
product_categories	Product category taxonomy
orders	Customer orders with totals
inventory	Real-time stock levels
payments	Payment records per order
reviews	Customer product ratings

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ❤️ using Defog SQLCoder & Google Cloud SQL