https://github.com/cskwork/rag-mysql
https://github.com/cskwork/rag-mysql
Last synced: 20 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/cskwork/rag-mysql
- Owner: cskwork
- Created: 2025-07-18T02:10:53.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-10-19T23:54:09.000Z (8 months ago)
- Last Synced: 2025-10-20T05:18:59.017Z (8 months ago)
- Language: Python
- Size: 48.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# RAG with MySQL, Ollama, and ChromaDB
This project demonstrates how to use the `vanna` library to generate SQL queries for a MySQL database using a Retrieval-Augmented Generation (RAG) approach. It leverages a local Large Language Model (LLM) via Ollama and uses ChromaDB as the vector store for the training data.
The application provides a web interface using Flask, allowing users to ask questions in natural language, which are then converted into SQL queries and executed against the database.
For a detailed explanation of the project's components and workflow, please see the [**Project Architecture Documentation**](.docs/architecture.md).
## Features
- **Natural Language to SQL**: Ask questions in plain English and get SQL queries in return.
- **Local LLM**: Uses a locally running Ollama instance, ensuring data privacy and cost-effectiveness.
- **Vector Store**: Employs ChromaDB to store and retrieve training data (DDL, documentation, and sample queries).
- **Web Interface**: A user-friendly web UI built with Flask for easy interaction.
- **Multiple Training Options**: Train from database schema or DDL files in `input/` folder.
- **Configuration-driven**: Easy to set up and configure using environment variables.
## Prerequisites
- Python 3.8+
- [Ollama](https://ollama.com/) installed and running.
- A MySQL database.
## Setup
Follow these steps to get the project up and running:
### 1. Clone the Repository
```bash
git clone
cd rag-mysql
```
### 2. Create and Activate a Virtual Environment
It is recommended to use a virtual environment to manage project dependencies.
```bash
python3 -m venv venv
source venv/bin/activate
```
### 3. Install Dependencies
Install the required Python packages from the `requirements.txt` file.
```bash
pip install -r requirements.txt
```
### 4. Configure Environment Variables
Create a `.env` file by copying the example file:
```bash
cp .env.example .env
```
Now, open the `.env` file and fill in your configuration details, especially your MySQL database credentials.
```ini
# --- Database Configuration ---
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USER=your-mysql-user
DB_PASSWORD=your-mysql-password
DB_NAME=your-mysql-database
# --- Ollama Configuration ---
# See https://ollama.com/library
OLLAMA_MODEL="gemma3n:latest"
# --- Vanna.ai Configuration ---
# You can get a free API key from https://vanna.ai
# This is optional and only used if you want to use the Vanna.ai hosted vector store.
# VANNA_API_KEY=""
# You can create a model name at https://vanna.ai/models
# VANNA_MODEL="my-model" # Your model name from Vanna.ai
# --- Application Configuration ---
FLASK_PORT=8084
```
### 5. Train the Model
Before you can ask questions, you need to "train" the Vanna instance on your database schema. Choose one of these training methods:
**Option A: Train from Database Schema (Recommended)**
```bash
python app.py --train
```
**Option B: Train from DDL Files**
1. Place your `.sql` DDL files in the `input/` folder
2. Run:
```bash
python app.py --train-ddl
```
Both methods store the schema information in ChromaDB for the LLM to use as context.
## Usage
After the training is complete, you can start the Flask web application:
```bash
python app.py
```
The application will be running on `http://localhost:8084` by default. Open this URL in your web browser to access the Vanna UI and start asking questions.
### Production Usage
For a production environment, it is recommended to use a more robust web server like Gunicorn. A `run.sh` script is provided to make this easy.
First, make sure the script is executable:
```bash
chmod +x run.sh
```
Then, run the script to start the application with Gunicorn:
```bash
./run.sh
```
This will start the server on the configured host and port with a default of 4 worker processes. You can adjust the number of workers by setting the `GUNICORN_WORKERS` environment variable in your `.env` file.
## Glossary
- **RAG (Retrieval-Augmented Generation)**: A technique that combines a retrieval system (like a vector database) with a generative model (like an LLM). It first retrieves relevant information and then uses that information as context to generate a more accurate and informed response.
- **LLM (Large Language Model)**: A type of artificial intelligence model trained on vast amounts of text data to understand and generate human-like text.
- **Ollama**: A tool that allows you to run open-source LLMs, such as Llama 2, locally on your own machine.
- **ChromaDB**: An open-source vector database that makes it easy to store and search embeddings (numerical representations) of your data.
- **Vanna**: A Python library that helps you build AI-powered SQL generation applications. It connects to your database, "learns" from your schema and data, and allows you to ask questions that it translates into SQL.
- **Flask**: A lightweight web framework for Python used here to create the user interface for the application.
- **Gunicorn**: A Python WSGI HTTP Server for UNIX. It's a pre-fork worker model, meaning it's a production-ready server that is much more robust than the default Flask development server.
---
*This file was generated by an AI assistant.*