https://github.com/iamvikash28/nl2sql
Ask your database questions in plain English. Get back real SQL, a safety check, and a results table.
https://github.com/iamvikash28/nl2sql
chatbot data-analysis database gemini gemini-api google-genai llm llm-apps nl2sql nlp pandas python sql sql-generator sqlite streamlit text-to-sql
Last synced: about 6 hours ago
JSON representation
Ask your database questions in plain English. Get back real SQL, a safety check, and a results table.
- Host: GitHub
- URL: https://github.com/iamvikash28/nl2sql
- Owner: iamvikash28
- Created: 2026-07-05T19:01:28.000Z (1 day ago)
- Default Branch: main
- Last Pushed: 2026-07-05T19:49:58.000Z (1 day ago)
- Last Synced: 2026-07-05T21:04:55.956Z (about 24 hours ago)
- Topics: chatbot, data-analysis, database, gemini, gemini-api, google-genai, llm, llm-apps, nl2sql, nlp, pandas, python, sql, sql-generator, sqlite, streamlit, text-to-sql
- Language: Python
- Homepage: https://nl-2sql.streamlit.app/
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Natural Language to SQL Chatbot
NL2SQL Chatbot lets anyone query a database by just asking a question — no SQL knowledge needed. Behind the scenes, Gemini generates the query grounded in the real database schema, and a safety layer blocks anything that isn't a read-only SELECT before it can touch the data. Built with Streamlit, SQLite, and the Gemini API.
---
## Project files
```
nl2sql-chatbot/
├── create_database.py # generates the sample SQLite database (shop.db)
├── utils.py # schema reader + SQL safety guard
├── nl_to_sql.py # prompt engineering + Gemini API call
├── app.py # Streamlit chat UI (the actual app)
├── requirements.txt
└── README.md
```
## Setup
**Step 1 — Install dependencies**
```bash
pip install -r requirements.txt
```
**Step 2 — Get a free Gemini API key**
Go to https://aistudio.google.com/apikey, sign in with a Google account,
and click "Create API key". It's free for moderate usage.
**Step 3 — Build the sample database**
```bash
python create_database.py
```
This creates `shop.db` with three tables: `customers`, `products`, `orders`
(60 customers, 48 products, 800 orders — realistic enough to ask interesting
questions).
**Step 4 — Run the app**
```bash
streamlit run app.py
```
Your browser opens automatically. Paste your Gemini API key into the
sidebar, and start asking questions like:
- "Show top 10 customers by revenue"
- "Which product category sells the most?"
- "Total sales by city"
- "How many orders were placed in 2024?"
---
## Skills
| SQL | Reading/writing SELECT, JOIN, GROUP BY, aggregate functions |
| Prompt engineering | `nl_to_sql.py` — schema grounding, output constraints |
| Database querying | `sqlite3`, `pandas.read_sql_query()` |
| AI integration | Calling the Gemini API via `google-genai` SDK |
| App security | Validating untrusted LLM output before executing it |
| Streamlit | Chat UI, session state, sidebar, dataframes |
## Live demo
[nl-2sql.streamlit.app](https://nl-2sql.streamlit.app)
## 👤 Author
**Vikash Verma**
Aspiring Data Analyst | Excel · SQL · Power BI · Python | E-mail- vikashverma566@gmail.com
---