QueryMind

The SQL agent for your whole team — ask your database in plain English.

---

QueryMind is an AI-powered database operations workspace that lets teams query connected MySQL and PostgreSQL databases in plain English. The AI writes the SQL, validates it against your live schema, guards every write behind confirmation — and answers with tables, charts, and PDF reports. From the web, or from WhatsApp.

_{Live demo — plain-English question → validated SQL → answer, straight from a connected MySQL database.}

✨ Features

🔍 Validated SQL	Every statement is parsed and checked against your live schema before it runs — no guesswork queries.
✋ Confirm-before-write	INSERT, UPDATE, DELETE always pause for explicit approval. Reads are instant, writes are guarded.
📊 AI-chosen charts	Ask for a trend or a total — QueryMind picks the right visualization and renders it instantly.
📄 PDF reports	Export any answer as a polished PDF report your team can share in one click.
💬 WhatsApp built in	Pair your number and query from your phone — answers and charts come back as images.
🔐 Encrypted credentials	Database passwords sealed with Fernet encryption before they ever touch storage.

See it in action

Ask in plain English — AI-written SQL, checked against your live schema, answered with a table.	AI-chosen charts — trends and totals rendered automatically from the answer.
Confirm-before-write — data changes pause for explicit approval, with a duplicate-key pre-check.	Workspace dashboard — connections, recent activity, and schema insights at a glance.

Plus: role-based member management (admin/member), email verification with password reset, a 3D schema constellation with AI-readiness scoring, full audit logging, and multi-database support per workspace.

🛠 Tech Stack

Layer	Technology
Backend	FastAPI, SQLAlchemy, Alembic, Python 3.12
Frontend	React 19, TypeScript, Tailwind CSS, Vite
Database	Supabase PostgreSQL (platform) · MySQL / PostgreSQL (user data)
AI	Google Gemini · OpenAI · Ollama (local fallback)
Email	Resend (verification, password reset)
Auth	JWT with email verification, Fernet-encrypted credentials
Deploy	Frontend on Vercel · Backend API on Render · 169 passing tests

🚀 Quick Start

Backend

Requires Python 3.10+ (3.12 recommended).

# 1. Clone and enter the backend
git clone https://github.com/aswin6373/db_qu.git
cd db_qu/backend

# 2. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
#    edit .env — at minimum set DATABASE_URL and JWT_SECRET_KEY

# 5. Run migrations
alembic upgrade head

# 6. Start the API
uvicorn app.main:app --reload

The API is now live at http://localhost:8000 — check http://localhost:8000/health or /health/readiness.

Frontend

Requires Node 18+ and pnpm.

# 1. Enter the frontend
cd frontend

# 2. Install dependencies
pnpm install

# 3. Point it at the backend (optional — defaults to same origin)
echo "VITE_API_URL=http://localhost:8000" > .env.local

# 4. Start the dev server
pnpm run dev

Open the local URL Vite prints (default http://localhost:5173).

Without a RESEND_API_KEY, verification and password-reset links are printed to the backend log instead of emailed — so local sign-up flows work offline.

🧭 How It Works

 1. Connect          2. Ask                    3. Review & run
┌──────────────┐   ┌──────────────┐        ┌─────────────────────┐
│ Add MySQL or │   │ "Revenue by  │        │ Reads run instantly │
│ PostgreSQL   │ → │ region last  │   →    │ Writes pause for    │
│ credentials  │   │ quarter?"    │        │ your confirmation   │
└──────────────┘   └──────────────┘        └─────────────────────┘

1. Connect — add your host and credentials. QueryMind tests the connection and maps your full schema (3D constellation + AI-readiness score).
2. Ask — type what you want to know. The AI writes one precise SQL statement for your schema.
3. Review & run — reads execute instantly; writes wait for your explicit confirmation, and every change lands in the audit log.

🔐 Security

• SQL injection guarded, multi-statement blocked
• Schema/admin operations (DROP, ALTER, TRUNCATE, GRANT, REVOKE) rejected
• UPDATE/DELETE must carry a WHERE clause
• Confirm-before-write with expiring confirmation windows
• Organization-level data isolation (every row scoped by org)
• Fernet-encrypted credentials at rest
• Full audit log of executed queries and changes
• Email verification + single-use hashed password-reset tokens

See PRODUCTION_CHECKLIST.md for the full list.

📁 Project Structure

backend/
  app/api/          Route modules (auth, connections, query, chat, orgs, WhatsApp)
  app/core/         Config, security, JWT
  app/connectors/   MySQL and PostgreSQL connector abstraction
  app/db/           SQLAlchemy session setup
  app/models/       Platform database models
  app/schemas/      Request and response DTOs
  app/services/     AI agents, email, crypto, SQL validation, insights
  alembic/          Platform schema migrations
  tests/            169 regression and integration tests
frontend/
  src/components/   Reusable UI
  src/pages/        Screen-level components
  src/lib/          API client helpers
  src/types/        TypeScript types

📚 Documentation

Doc	Contents
PROJECT_PLAN.md	Architecture, API surface, roles, safety rules
PRODUCTION_CHECKLIST.md	Production hardening and maintenance
VERCEL_DEPLOYMENT.md	Render + Vercel deployment walkthrough
SUPABASE_SETUP.md	Platform database setup
WHATSAPP_SETUP.md	WhatsApp bot configuration

🧪 Development

# Backend tests (169 tests — migrations, auth, SQL safety, connectors)
cd backend && source .venv/bin/activate
python -m pytest tests/ -q

# Frontend type-check + production build
cd frontend
npx tsc -b
npm run build

---

_{Built with FastAPI, React, and too much coffee ☕}