joelgilbert/NL2SQL

🤖 Natural Language to SQL Query System

Transform your questions into SQL queries using AI! This application uses a multi-agent architecture to understand natural language questions, generate SQL queries, execute them safely, and explain the results in plain English.

✨ Features

• —🧠 Multi-Agent AI System
• —Gatekeeper: Validates and classifies user intent
• —SQL Generator: Creates optimized queries using Cloudflare Workers AI
• —Explainer: Provides business-friendly result summaries

• —🔒 Enterprise-Grade Security
• —Read-only mode by default (SELECT queries only)
• —DBA mode with password protection for write operations
• —SQL injection prevention
• —Comprehensive audit logging

• —🚀 Smart Query Generation
• —Automatic error correction (up to 3 retries)
• —Semantic schema search using vector embeddings
• —Query optimization and validation

• —📊 Interactive Results
• —Clean table visualization
• —Natural language explanations
• —Query execution metrics
• —Session statistics

🎯 How to Use

Ask Questions in Plain English

Examples:

• —"How many customers do we have?"
• —"Show me total revenue by product category"
• —"Who are our top 5 customers by spending?"
• —"List orders from last week"
• —"What's the average order value?"

Two Modes

🟢 Read-Only Mode (Default)

• —Safe for business intelligence queries
• —SELECT queries only
• —No data modification

🔴 DBA Mode (Password Protected)

• —Full database access
• —INSERT, UPDATE, DELETE operations
• —Requires approval for destructive queries

🏗️ Architecture

User Question
     ↓
Agent 1: Gatekeeper (Groq/Llama-3.1)
  - Validates intent
  - Filters irrelevant questions
     ↓
Vector Search (Upstash Vector)
  - Finds relevant table schemas
  - Retrieves similar queries
     ↓
Agent 2: SQL Generator (Cloudflare/SQLCoder-7B-2)
  - Generates SQL query
  - Auto-corrects errors
  - Validates syntax
     ↓
Security Validator
  - Checks for SQL injection
  - Verifies permissions
  - Validates table access
     ↓
Query Executor (Neon PostgreSQL)
  - Executes query safely
  - Returns results
     ↓
Agent 3: Explainer (Groq/Llama-3.1)
  - Analyzes results
  - Generates insights
  - Creates human-friendly explanation

🛠️ Technology Stack

• —Frontend: Streamlit
• —Database: Neon Serverless PostgreSQL
• —Vector DB: Upstash Vector (with BAAI/bge-m3 embeddings)
• —LLMs:
• —Groq API (Llama-3.1-70b-versatile)
• —Cloudflare Workers AI (SQLCoder-7B-2)
• —Security: Custom query validation & audit logging

📊 Sample Database

The demo uses an e-commerce database with:

• —6 tables: regions, customers, categories, products, orders, order_items
• —200+ rows of realistic sample data
• —Full relationships: foreign keys and indexes

🔐 Security Features

Input Validation

• —SQL injection pattern detection
• —Multi-statement prevention
• —Destructive operation blocking

Access Control

• —Two-tier permission model
• —Password-based DBA access
• —Session timeout (1 hour)
• —Timing-attack resistant authentication

Audit Trail

• —All query attempts logged
• —Execution results tracked
• —Performance metrics recorded

💡 Use Cases

• —Business Intelligence: Non-technical users can query data
• —Data Exploration: Quick insights without writing SQL
• —Learning SQL: See how natural language maps to SQL
• —Data Analysis: Fast ad-hoc queries and reporting

🎓 Example Queries

Easy

• —"Count total orders"
• —"List all product categories"
• —"Show active customers"

Medium

• —"Total sales by region last month"
• —"Average order value per customer"
• —"Top 10 best-selling products"

Advanced

• —"Monthly revenue trend for last 6 months"
• —"Customer lifetime value analysis"
• —"Products with low stock (< 50 units)"

⚙️ Configuration

This app requires the following environment variables (set in Space Settings → Repository secrets):

• —NEON_READONLY_CONNECTION_STRING - Database connection (read-only)
• —NEON_DBA_CONNECTION_STRING - Database connection (full access)
• —GROQ_API_KEY - Groq API for LLM inference
• —CLOUDFLARE_ACCOUNT_ID - Cloudflare account
• —CLOUDFLARE_AUTH_TOKEN - Cloudflare authentication
• —UPSTASH_VECTOR_URL - Upstash Vector database URL
• —UPSTASH_VECTOR_TOKEN - Upstash authentication token
• —DBA_PASSWORD - Password for DBA mode

📝 License

MIT License - Feel free to use and modify!

🤝 Contributing

Built with ❤️ using open-source technologies. Contributions welcome!

🔗 Links

• —Documentation: Full README
• —Deployment Guide: DEPLOYMENT_CHECKLIST.md
• —Quick Start: QUICKSTART.md

Note: This is a demo application. For production use, ensure proper security review, API rate limiting, and cost monitoring.