joelgilbert/NL2SQL

1# Quick Start Guide - NL2SQL System2 3Get your NL2SQL system up and running in 10 minutes!4 5## Prerequisites6 7✅ Python 3.10+  8✅ PostgreSQL database (Neon recommended)  9✅ API keys ready (see below)10 11## Step 1: Clone & Setup (2 min)12 13```bash14# Clone the repository15git clone <your-repo-url>16cd nl2sql-project17 18# Create virtual environment19python -m venv venv20 21# Activate virtual environment22# On Mac/Linux:23source venv/bin/activate24# On Windows:25venv\Scripts\activate26 27# Install dependencies28pip install -r requirements.txt29```30 31## Step 2: Get API Keys (3 min)32 33### Groq API (FREE)341. Visit [console.groq.com](https://console.groq.com)352. Sign up with Google/GitHub363. Create API Key → Copy it374. Free tier: 30 requests/min38 39### Cloudflare Workers AI (FREE)401. Visit [dash.cloudflare.com](https://dash.cloudflare.com)412. Go to AI → Workers AI423. Get Account ID from overview434. Create API Token → Copy it445. Free tier: 10,000 requests/day45 46### Upstash Vector (FREE)471. Visit [console.upstash.com](https://console.upstash.com)482. Create Vector Index493. Dimension: 384 (for text embeddings)504. Copy URL and Token515. Free tier: 10,000 queries/day52 53### Neon PostgreSQL (FREE)541. Visit [neon.tech](https://neon.tech)552. Create new project563. Copy connection string574. Create read-only user:58```sql59CREATE USER readonly_user WITH PASSWORD 'your_password';60GRANT CONNECT ON DATABASE your_db TO readonly_user;61GRANT USAGE ON SCHEMA public TO readonly_user;62GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;63```64 65## Step 3: Configure Environment (2 min)66 67```bash68# Copy example env file69cp .env.example .env70 71# Edit .env with your values72nano .env  # or use your favorite editor73```74 75**Minimal .env configuration:**76```env77# Database (use same for both if you don't have separate users)78NEON_READONLY_CONNECTION_STRING=postgresql://user:pass@host/db?sslmode=require79NEON_DBA_CONNECTION_STRING=postgresql://user:pass@host/db?sslmode=require80 81# API Keys (paste the ones you got)82GROQ_API_KEY=gsk_xxxxxxxxxxxxx83CLOUDFLARE_ACCOUNT_ID=xxxxxxxxxxxxx84CLOUDFLARE_AUTH_TOKEN=xxxxxxxxxxxxx85 86# Upstash Vector87UPSTASH_VECTOR_URL=https://xxxxx.upstash.io88UPSTASH_VECTOR_TOKEN=xxxxxxxxxxxxx89 90# Security91DBA_PASSWORD=choose_a_strong_password92 93# App Settings94APP_ENV=development95LOG_LEVEL=INFO96```97 98## Step 4: Initialize Vector Store (2 min)99 100```bash101# This populates Upstash with your database schema102python scripts/init_vector_store.py103```104 105You should see:106```107✅ Database connection successful108✅ Upstash Vector initialized109✅ Found X tables110✅ Successfully stored X schemas111✅ Search test successful!112```113 114## Step 5: Run the App (1 min)115 116```bash117streamlit run app.py118```119 120The app will open at `http://localhost:8501`121 122## 🎉 You're Ready!123 124Try these example queries:125 126**Simple:**127- "How many users do we have?"128- "Show me all active customers"129 130**Aggregated:**131- "Total sales by region"132- "Average order value per customer"133 134**Time-based:**135- "Sales in the last 7 days"136- "New users this month"137 138## 🔧 Troubleshooting139 140### Can't connect to database?141```bash142# Test your connection string143psql "postgresql://user:pass@host/db?sslmode=require"144```145 146### Vector store initialization fails?147- Check Upstash credentials in .env148- Verify database has tables149- Run with debug: `LOG_LEVEL=DEBUG python scripts/init_vector_store.py`150 151### Streamlit won't start?152```bash153# Verify all dependencies154pip install -r requirements.txt --upgrade155 156# Check for Python errors157python app.py158```159 160### API rate limits?161- Free tiers have limits162- Groq: 30 req/min163- Cloudflare: 10,000 req/day164- Upstash: 10,000 queries/day165 166### Nothing happens when I ask a question?167- Check browser console (F12) for errors168- Check terminal for Python errors169- Verify API keys are correct170- Check LOG_LEVEL=DEBUG in .env for detailed logs171 172## 🚀 Next Steps173 1741. ✅ **Test DBA Mode** - Login with your DBA_PASSWORD1752. ✅ **Check Audit Logs** - View in sidebar statistics1763. ✅ **Customize Prompts** - Edit `config/prompts.py`1774. ✅ **Add More Examples** - Update `EXAMPLE_QUERIES` in `config/prompts.py`1785. ✅ **Deploy to Production** - See `DEPLOYMENT_CHECKLIST.md`179 180## 📚 More Documentation181 182- Full setup: `README.md`183- Deployment: `DEPLOYMENT_CHECKLIST.md`184- Architecture: See `README.md` → Architecture section185 186## 💡 Tips187 188**For better results:**189- Be specific in your questions190- Mention table names if you know them191- Include time ranges explicitly192- Use natural language, not SQL keywords193 194**For development:**195- Set `LOG_LEVEL=DEBUG` to see detailed logs196- Check `audit_logs/` folder for query history197- Use DBA mode to test write operations198- Run tests: `pytest tests/ -v`199 200## ❓ Need Help?201 202- Check logs in terminal203- Review audit logs in sidebar204- See `DEPLOYMENT_CHECKLIST.md` for common issues205- Check README.md troubleshooting section206 207---208 209**Happy querying! 🔍**210