Repository navigation
Frequently Asked Questions (FAQ)
A natural language interface for PostgreSQL databases that lets you ask questions in plain English and get instant answers. It uses local AI (Ollama) to convert your questions into SQL queries.
Yes, 100% free and open source! No API costs, no subscriptions. Everything runs locally on your machine.
No! Unlike other AI tools, this uses Ollama which runs entirely on your computer. No external API calls means no API keys needed (except optionally for embeddings).
Currently PostgreSQL 13+. Support for other databases (MySQL, MongoDB) is planned for future releases.
Minimum:
- 4GB RAM
- 10GB disk space
- Python 3.10+
- Node.js 18+
Recommended:
- 8GB+ RAM
- 20GB disk space (for Ollama models)
- SSD for faster performance
For most users: llama3.2 (2GB, fast, good accuracy)
Alternatives:
-
mistral- Good alternative to Llama -
gemma4- Larger, more capable (9.6GB) -
qwen3.6- Very capable but large (23GB)
Yes! Just update the connection settings in backend/.env to point to your database.
No! The application only executes SELECT queries (read-only). All dangerous operations (DROP, DELETE, INSERT, UPDATE) are blocked.
Simple queries:
- "Show me all employees"
- "What's the average salary?"
- "List all departments"
Complex queries:
- "Who are the top 5 highest paid employees in Finance?"
- "Which departments are over budget by more than 10%?"
- "Show me employees hired in the last 6 months with salaries above $80k"
Analytical questions:
- "What's the salary distribution by department?"
- "Compare performance ratings across teams"
- "Show me hiring trends over time"
For safety, only SELECT queries are allowed. Queries containing dangerous keywords (DROP, DELETE, INSERT, UPDATE, etc.) are automatically blocked.
All queries are automatically logged to the ai_query_history table in your database. You can query this table to see your history.
Accuracy depends on:
- Model used - Larger models (gemma4, qwen3.6) are more accurate
- Question clarity - More specific questions get better results
- Schema complexity - Simpler schemas are easier to understand
Typical accuracy: 85-95% for well-formed questions.
Typical response times:
- Simple queries: 1-3 seconds
- Complex queries: 3-8 seconds
- With embeddings: +1-2 seconds
Speed depends on:
- Ollama model size (smaller = faster)
- Database size
- Query complexity
- Hardware (CPU, RAM, SSD)
Yes!
-
Use smaller models:
llama3.2instead ofqwen3.6 - Optimize PostgreSQL: Add indexes, tune shared_buffers
- Use SSD: Much faster than HDD
- More RAM: Allows more database caching
There's no hard limit. For production use, consider:
- Rate limiting (10-20 queries/minute per user)
- Query caching
- Connection pooling
Yes! All processing happens locally. Your data never leaves your machine (unless you're using remote embeddings with OpenAI API).
No. Multiple safety layers:
- Keyword blocking (DROP, DELETE, etc.)
- Query validation
- Read-only database user (optional but recommended)
Yes, but add:
- Authentication (JWT, OAuth)
- Rate limiting
- HTTPS/SSL
- Database user with minimal permissions
- Logging and monitoring
See Deployment Guide for details.
"Database connection failed"
- Check credentials in
.env - Verify PostgreSQL is running:
psql -U postgres - Test connection:
psql -h localhost -U postgres -d dbname
"Could not connect to Ollama"
- Check Ollama is running:
ollama list - Start Ollama:
ollama serve - Pull model:
ollama pull llama3.2
"Port 8000 already in use"
# Find and kill process
lsof -ti:8000 | xargs kill -9- Open browser console (F12)
- Look for errors
- Common issues:
- Backend not running
- Wrong API URL in
App.jsx - CORS errors
"Unsafe query"
- Query contains blocked keywords
- Try rephrasing without DELETE, DROP, etc.
"Query execution failed"
- SQL syntax error (model made a mistake)
- Table/column doesn't exist
- Try rephrasing the question
- Check Ollama is using GPU:
ollama ps - Optimize PostgreSQL (see Performance Tuning)
- Try smaller model:
ollama pull llama3.2 - Add database indexes
Vector representations of text that enable semantic search - finding similar items by meaning, not just keywords.
No! The basic text-to-SQL works great without embeddings. Embeddings add semantic search capabilities but are optional.
- Get OpenAI API key
- Run
python generate_embeddings.py - See Embeddings Guide
Yes! You can use:
-
sentence-transformers(Python library) - Ollama embeddings API (experimental)
Yes! See CONTRIBUTING.md
- Fork the repository
- Create feature branch
- Make changes
- Add tests
- Submit pull request
Yes! Edit frontend/src/App.css to change colors, fonts, layout.
Yes! MIT License allows commercial use, modification, and distribution.
Not required, but appreciated! 😊
- Check Troubleshooting
- Search GitHub Issues
- Open a new issue
- Join Discussions