The most powerful AI-driven SQL assistant — review queries, analyze schemas, generate SQL from plain English, and connect to live databases with a full agentic AI pipeline featuring self-reflection and RAG-powered intelligence.

🚀 Quick Start · ☁️ Deploy · ✨ Features · 🏗️ Architecture · 🤖 AI Pipeline · 🛠️ Tech Stack

---

✨ Features

🔍 Query Review Paste any SQL query and get an instant AI-powered deep analysis — performance bottlenecks, security vulnerabilities, readability score, and concrete optimization suggestions with severity tags.	🗂️ Schema Review Upload your DDL or paste a schema and receive a comprehensive evaluation of design choices, normalization gaps, missing indexes, and foreign key recommendations.
💬 Natural Language → SQL Describe what you want in plain English. The AI understands your intent, picks the right dialect (MySQL / PostgreSQL), and returns a clean, optimized query with explanation.	🔌 Live Database Connection Connect directly to your MySQL or PostgreSQL instance (read-only, session-based). Explore the live schema, run queries or NL prompts, and get EXPLAIN plan analysis — all in one place.
🖼️ Schema Builder Upload a schema diagram image and the AI reverse-engineers it into complete SQL DDL — table definitions, constraints, indexes, and relationships included.	📜 Analysis History Every analysis is saved. Search, filter by type, date, or database dialect, and revisit any past result with full detail view and re-analysis option.

Live Database — Bonus Capabilities

Capability	Detail
🔌 Secure Connection	Read-only, session-scoped — never modifies your data
📊 Schema Explorer	Toggle panel with table count, expandable column details
💬 Dual Query Mode	Switch between raw SQL and natural language on the fly
🎙️ Voice Input	Speech-to-text for NL mode — just speak your question
🤖 Smart Context	Agent automatically injects relevant schema context
📋 EXPLAIN Plans	Run and visualize query execution plans instantly

---

🏗️ System Architecture

╔══════════════════════════════════════════════════════════════╗
║                  React Frontend  (Vite + React 18)           ║
║   Dashboard │ Query Review │ Schema │ NL→SQL │ Live DB │ History ║
╚══════════════════════════╦═══════════════════════════════════╝
                           ║  REST API (HTTP/JSON)
                           ▼
╔══════════════════════════════════════════════════════════════╗
║                    FastAPI Backend                           ║
║  /api/review-query   /api/review-schema   /api/nl-to-query   ║
║  /api/connect-db     /api/history         /api/schema-build  ║
╚═══════════════╦══════════════════════╦═══════════════════════╝
                ║                      ║
                ▼                      ▼
╔══════════════════════╗  ╔══════════════════════════════════╗
║      AI Agent        ║  ║       Live DB Connection         ║
║  ┌────────────────┐  ║  ║  ┌───────────┐  ┌────────────┐  ║
║  │ Static Analysis│  ║  ║  │   MySQL   │  │ PostgreSQL │  ║
║  │ RAG Retrieval  │  ║  ║  │ (PyMySQL) │  │(Psycopg2)  │  ║
║  │ Tool Calling   │  ║  ║  └───────────┘  └────────────┘  ║
║  │ LLM Reasoning  │  ║  ║       Read-Only │ Session-Scoped ║
║  │ Self-Reflection│  ║  ╚══════════════════════════════════╝
║  │ Evaluation     │  ║
║  └───────┬────────┘  ║
╚══════════╬═══════════╝
           ║
     ╔═════╩══════╗
     ▼            ▼
╔═════════╗  ╔══════════╗
║ChromaDB ║  ║ Supabase ║
║  (RAG)  ║  ║(History) ║
╚═════════╝  ╚══════════╝

---

🤖 AI Agent Pipeline

Every analysis runs through a fully agentic loop — not a simple one-shot prompt:

┌─────────────────────────────────────────────────────────────┐
│                     AGENTIC LOOP                            │
│                                                             │
│  📥 Input                                                   │
│      │                                                      │
│      ▼                                                      │
│  [1] 🔎 Static Analysis ──── Pattern-based issue detection  │
│      │                                                      │
│      ▼                                                      │
│  [2] 📚 RAG Retrieval ─────── ChromaDB knowledge search     │
│      │                                                      │
│      ▼                                                      │
│  [3] 🔧 Tool Calling ──────── Specialized analysis modules  │
│      │                                                      │
│      ▼                                                      │
│  [4] 🧠 LLM Reasoning ─────── Multi-model inference         │
│      │                                                      │
│      ▼                                                      │
│  [5] 🪞 Self-Reflection ───── Quality check (up to 3x)      │
│      │                                                      │
│      ▼                                                      │
│  [6] 📊 Evaluation ────────── Score: Perf│Sec│Read│Complex  │
│      │                                                      │
│      ▼                                                      │
│  📤 Final Response                                          │
└─────────────────────────────────────────────────────────────┘

🔀 Multi-LLM Fallback Chain

The agent automatically cascades through providers — zero downtime if one fails:

#	Provider	Model	Speed	Notes
1️⃣	Google Gemini	gemini-2.5-pro	Fast	Primary — best quality
2️⃣	Google Gemini	gemini-2.5-flash	Faster	Flash fallback
3️⃣	Groq	llama-3.1-8b-instant	Ultra-fast	Low latency fallback
4️⃣	OpenRouter	gemma-3-4b (free)	Medium	Free tier fallback
5️⃣	OpenRouter	llama-3.3-70b (free)	Medium	Final free fallback

---

🚀 Quick Start

Prerequisites

Step 1 — Clone & Setup Backend

git clone https://github.com/your-username/ai-query-master.git
cd "AI Query Master/backend"

# Create & activate virtual environment
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate    # Linux / macOS

# Install all dependencies
pip install -r requirements.txt

Step 2 — Configure Environment

Create backend/.env and fill in your keys:

# ── AI Providers ──────────────────────────────────────
GEMINI_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key
OPENROUTER_KEY_1=your_openrouter_key
OPENROUTER_KEY_2=your_openrouter_key_optional   # optional second key

# ── Supabase (Auth + History storage) ─────────────────
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_supabase_service_role_key

Step 3 — Setup Supabase

Run migration.sql in your Supabase SQL Editor to create all required tables.

Step 4 — Add Knowledge Base (optional but recommended)

Drop PDF documents into the RAG knowledge folders to supercharge analysis quality:

RAG_Knowledge/
├── Mysql/          ← MySQL best practices, docs, guides
└── PostgreSQL/     ← PostgreSQL best practices, docs, guides

Step 5 — Launch

Terminal 1 — Backend:

cd backend
venv\Scripts\activate
python main.py
# ✅ API running at http://localhost:8000
# ✅ Docs available at http://localhost:8000/docs

Terminal 2 — Frontend:

cd frontend
npm install
npm run dev
# ✅ App running at http://localhost:5173

Open http://localhost:5173 and start querying! 🎉

---

Deploy: Render + Supabase pgvector

Use this production setup to avoid Render free-tier memory issues from local embedding models.

1. Create a new Supabase project and run migration.sql in SQL Editor.
2. Create a Render Web Service for backend:
   • Root Directory: backend
   • Build Command: pip install -r requirements.txt
   • Start Command: uvicorn main:app --host 0.0.0.0 --port $PORT
3. Set backend environment variables in Render:

# App
FRONTEND_URL=https://your-frontend.vercel.app
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_supabase_service_role_key

# LLMs
GEMINI_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key
OPENROUTER_KEY_1=your_openrouter_key

# RAG (Supabase pgvector)
RAG_ENABLED=true
RAG_BACKEND=supabase
RAG_EMBEDDING_PROVIDER=gemini
RAG_EMBEDDING_DIM=384
RAG_PRELOAD_ON_STARTUP=false
RAG_AUTO_INDEX=false

4. Deploy backend, then call POST /api/index once to build embeddings and vectors.
5. Verify GET /api/health shows rag_pipeline.backend = supabase and non-zero chunks.
6. Ensure frontend points to your Render backend API URL (replace localhost in frontend/src/api.js for production).

---

🛠️ Tech Stack

Layer	Technology	Purpose
Frontend	React 18 + Vite + React Router	SPA with fast HMR dev experience
Backend	FastAPI + Python 3.12	Async REST API with auto-docs
AI / LLM	Gemini · Groq · OpenRouter	Multi-provider fallback inference
RAG	ChromaDB or Supabase pgvector · LangChain · Gemini Embeddings	Persistent vector search over knowledge base
Auth & Storage	Supabase	Auth, user management, history DB
Live Database	PyMySQL · Psycopg2	Read-only live DB connections

---

📁 Project Structure

AI Query Master/
│
├── 📂 backend/
│   ├── main.py                  ← FastAPI app entry point
│   ├── requirements.txt
│   ├── 📂 agent/
│   │   ├── agent.py             ← Agentic orchestration loop
│   │   ├── llm_provider.py      ← Multi-LLM fallback chain
│   │   ├── rag_pipeline.py      ← ChromaDB/Supabase pgvector RAG retrieval
│   │   ├── tools.py             ← Specialized analysis tools
│   │   ├── reflection.py        ← Self-reflection module
│   │   └── evaluator.py         ← Scoring: Perf/Sec/Read/Complex
│   ├── 📂 api/
│   │   ├── auth.py              ← Supabase auth endpoints
│   │   ├── nl_to_query.py       ← NL → SQL endpoint
│   │   ├── query_review.py      ← Query analysis endpoint
│   │   ├── schema_review.py     ← Schema analysis endpoint
│   │   ├── schema_builder.py    ← Image → DDL endpoint
│   │   ├── live_db.py           ← Live DB connection endpoint
│   │   └── history.py           ← Analysis history endpoint
│   └── 📂 db/
│       ├── mysql_connector.py   ← MySQL live connection
│       ├── postgres_connector.py← PostgreSQL live connection
│       └── supabase_client.py   ← Supabase client
│
├── 📂 frontend/
│   ├── 📂 src/
│   │   ├── 📂 pages/            ← Full-page route components
│   │   ├── 📂 components/       ← Reusable UI components
│   │   ├── 📂 context/          ← Auth & Theme context
│   │   └── api.js               ← Centralized API client
│   └── package.json
│
├── 📂 RAG_Knowledge/
│   ├── Mysql/                   ← MySQL knowledge documents
│   └── PostgreSQL/              ← PostgreSQL knowledge documents
│
└── migration.sql                ← Supabase schema setup

---

🔐 Security Model

• Live DB connections are strictly read-only and session-scoped — no write operations, no persistent credentials stored
• All API keys are loaded from environment variables — never hardcoded
• Authentication handled by Supabase with JWT tokens
• RAG supports local (ChromaDB) or hosted (Supabase pgvector) storage for indexed chunks

---

⭐ If this project helps you, give it a star!