Querva is an AI-powered SQL assistant that converts natural-language questions into accurate, executable SQL queries using your database schema. Upload a schema (SQL, JSON, or CSV), name a conversation, and chat to generate and explain queries.
We have a public demo deployed on EC2: http://98.93.163.183/
Use the demo to evaluate functionality before running the app locally.
- Schema support: SQL (CREATE TABLE), structured JSON, and CSV
- AI query generation and explanation via Groq
- JWT-based authentication and per-user conversation storage (up to 5 saved conversations)
- Dockerized (docker-compose) local and production workflows
- Frontend: React 18 + Vite, TailwindCSS
- Backend: Node.js 18 + Express
- Database: PostgreSQL 15
- AI: Groq API
- DevOps: Docker Compose, optional EC2/Jenkins deployment
The easiest way to run Querva locally is with Docker Compose — this starts the frontend, backend, and a Postgres database.
Docker (recommended)
# Build and start services
docker-compose up -d --build
# Follow logs (optional)
docker-compose logs -f
# Stop and remove services
docker-compose downIf you prefer running services on your host machine:
Prerequisites:
- Node.js 18+
- PostgreSQL 15+ (or use the Docker Compose Postgres service)
# Clone
git clone https://github.com/NitinMoturu72/Querva.git
cd Querva
# Frontend
npm install
npm run dev
# Backend (another terminal)
cd backend
npm install
cp .env.example .env
# Edit .env with your DB and API keys (see Required API Keys below)
npm run devquerva/
├── src/ # Frontend
├── backend/ # Backend (Express)
├── docker-compose.yml
├── DEPLOYMENT.md # Full deployment guide
└── README.md
Copy .env.example to .env and set the following values before running the backend. Keep secrets out of source control.
DB_HOST— database host (postgresfor Docker Compose,localhostfor host runs)DB_PORT— database port (default5432)DB_NAME— database name (defaultQuerva)DB_USER— database user (defaultpostgres)DB_PASSWORD— database passwordJWT_SECRET— used to sign JWTs (set a strong random value)GROQ_API_KEY— Groq AI API key (required for AI-powered query generation)VITE_API_URL— frontend API base (defaulthttp://localhost:5000/api)
Example .env (local):
DB_HOST=localhost
DB_PORT=5432
DB_NAME=Querva
DB_USER=postgres
DB_PASSWORD=postgres
JWT_SECRET=replace_with_a_strong_secret
GROQ_API_KEY=your_groq_api_key_here
VITE_API_URL=http://localhost:5000/apiRun the backend tests:
cd backend
npm testPOST /api/auth/register— create accountPOST /api/auth/login— login and receive JWTGET /api/auth/me— get authenticated userPOST /api/conversations— create a saved conversation (requires auth)GET /api/conversations— list saved conversations (requires auth)POST /api/query— generate SQL from questionPOST /api/explain— explain a SQL query
A production demo is available at: http://98.93.163.183/
For most use cases the Docker Compose workflow above is sufficient for local testing and development.
- Keep
JWT_SECRETandGROQ_API_KEYprivate and rotate them as needed. - The app stores conversations and schema in Postgres; use
docker-compose down -vto remove volumes when you want a fresh database. - If you'd like, I can add a short annotated GIF showing: upload schema → name conversation → start chat, and example
.envfiles for Docker vs local runs.
Open an issue or send a PR with suggested improvements. If you want me to add the GIF or an example .env.docker file, tell me which one and I will add it.
- Delete conversations to free up slots
- Full schema and message history persisted
- User isolation enforced at database level
Push to main → Jenkins automatically:
- ✅ Installs dependencies
- ✅ Runs all tests
- ✅ Builds Docker images
- ✅ Pushes to registry (optional)
- ✅ Deploys to EC2
- ✅ Health checks
PRs can't merge without passing pipeline! 🔒
- 💾 PostgreSQL query optimization with indexes
- 🔄 Conversation history limited to 5 messages for context
- 📦 Rate limiting prevents abuse
- 🔐 Password hashing with bcrypt
- 🎫 JWT token-based auth
- 🚫 Rate limiting on API endpoints
- 👤 User isolation on database queries
- 🔑 Environment variable secrets
- 📝 SQL prepared statements (parameterized queries)
# Check PostgreSQL is running
docker-compose ps
# Check connection in logs
docker-compose logs backend# Make sure test database exists
docker-compose up postgres -d
# Run tests with verbose output
cd backend && npm test -- --verbose# Check backend is running
curl http://localhost:5000/health
# Check Nginx logs
sudo tail -f /var/log/nginx/error.logSee DEPLOYMENT.md Troubleshooting for more.
- Fork repository
- Create feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open Pull Request
Pull requests require:
- ✅ Tests passing (Jest)
- ✅ Linting pass
- ✅ Code review approval
- ✅ Branch protection enforced
# Start local development
npm run dev # Frontend (port 5173)
cd backend && npm run dev # Backend (port 5000)
# Run tests
cd backend && npm test
# Run tests in watch mode
cd backend && npm run test:watch
# Build for production
npm run build
# Build Docker images
docker-compose build
# Deploy to AWS
# Push to main, Jenkins handles rest
git push origin main- Frontend: http://localhost:5173
- Backend: http://localhost:5000/health
- Database: postgres:5432
- HTTPS/SSL with Let's Encrypt
- User profiles and preferences
- Query history and favorites
- Real-time collaboration
- Database connection testing
- Advanced query suggestions
- Slack bot integration
- API documentation (Swagger)
- Performance analytics
MIT License - see LICENSE file
- 🧪 Testing Guide
- 💬 Open an issue for bugs
- 🚀 Discussions for features
Built with ❤️ by the Querva team
Latest commit: git log -1 --oneline
Docker ready • Tested • Production-grade CI/CD