Txt2SQL is an intelligent command-line tool that converts your natural language questions into SQL queries and executes them on your SQLite database. No need to remember complex SQL syntax—just ask in plain English!
- 📊 Quick database queries without writing SQL
- 🎓 Learning SQL by seeing generated queries
- 🔍 Data exploration and analysis
- 🛠️ Rapid prototyping and testing
|
Uses fine-tuned T5 transformer model for accurate SQL generation All processing happens on your machine—no API calls, no data sharing Efficient inference designed for everyday computers |
Interactive interface with colors, autocomplete, and command history Warns before executing dangerous operations like DELETE or DROP Automatically reads and understands your database structure |
- Python 3.8 or higher
- 2GB+ RAM recommended
- SQLite database
git clone https://github.com/yourusername/Txt2SQL.git
cd Txt2SQLpip install -r requirements.txtDownload the pre-trained model from HuggingFace:
# Using git-lfs
git lfs install
git clone https://huggingface.co/mrm8488/t5-small-finetuned-wikiSQLOr download manually from: HuggingFace Model Hub
cp .env.example .envEdit .env and set your model path:
WIKISQL_MODEL=/path/to/t5-small-finetuned-wikiSQLSimply run:
python txt2sql.pyThe program will:
- ✅ Load the AI model
- 📂 Ask you to select a database
- 🎯 Start the interactive session
╔══════════════════════════════════════════════════════════════════╗
║ ║
║ ████████╗██╗ ██╗████████╗██████╗ ███████╗ ██████╗ ██╗ ║
║ ╚══██╔══╝╚██╗██╔╝╚══██╔══╝╚════██╗██╔════╝██╔═══██╗██║ ║
║ ██║ ╚███╔╝ ██║ █████╔╝███████╗██║ ██║██║ ║
║ ██║ ██╔██╗ ██║ ██╔═══╝ ╚════██║██║▄▄ ██║██║ ║
║ ██║ ██╔╝ ██╗ ██║ ███████╗███████║╚██████╔╝███████╗ ║
║ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚══════╝ ╚══▀▀═╝ ╚══════╝ ║
║ ║
║ Natural Language to SQL Query Converter ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
✓ Model loaded
✓ Database: mydb.db
✓ Tables: customers, orders, products
❯ show me all customers from California
| Command | Description |
|---|---|
? or help |
Show help message |
schema |
Display database schema |
tables |
List all tables |
clear |
Clear the screen |
exit or quit |
Exit the program |
- ↑↓ Arrow Keys: Navigate command history
- Tab: Autocomplete commands
- Ctrl+R: Search command history (if prompt-toolkit installed)
❯ show all customers
Generated SQL:
SELECT * FROM customers
│ id │ name │ email │ state │
─────────────────────────────────────────────────────────────
│ 1 │ John Doe │ john@example.com │ California │
│ 2 │ Jane Smith │ jane@example.com │ New York │
│ 3 │ Bob Johnson │ bob@example.com │ Texas │
(3 rows)
❯ how many customers are from California?
Generated SQL:
SELECT COUNT(*) FROM customers WHERE state = 'California'
│ COUNT(*) │
────────────
│ 15 │
(1 row)
❯ show customer names and their order counts
Generated SQL:
SELECT customers.name, COUNT(orders.id)
FROM customers
LEFT JOIN orders ON customers.id = orders.customer_id
GROUP BY customers.name
│ name │ COUNT(orders.id) │
────────────────────────────────────
│ John Doe │ 5 │
│ Jane Smith │ 3 │
│ Bob Johnson │ 7 │
(3 rows)
Txt2SQL/
├── 📄 config.py # Configuration management
├── 📄 database.py # Database operations
├── 📄 generator.py # SQL generation with T5
├── 📄 cli.py # Interactive CLI interface
├── 📄 utils.py # Utility functions
├── 📄 txt2sql.py # Main entry point
│
├── 📋 requirements.txt # Python dependencies
├── 📋 requirements-dev.txt # Development dependencies
├── 🧪 test_basic.py # Unit tests
│
├── 📝 .env.example # Environment template
├── 📝 .gitignore # Git ignore rules
├── 📝 LICENSE # License file
└── 📝 README.md # This file
| Feature | Description |
|---|---|
| Prompts confirmation before DELETE, DROP, TRUNCATE, ALTER | |
| ✅ Input Validation | Validates all user inputs and SQL queries |
| 🔍 Query Preview | Shows generated SQL before execution |
| 📝 Error Messages | Clear, helpful error messages |
Only one required variable in .env:
WIKISQL_MODEL=/path/to/modelYou can adjust these in config.py:
self.max_length = 128 # Maximum SQL length
self.num_beams = 2 # Beam search beams
self.torch_threads = 2 # CPU threadspip install -r requirements-dev.txtpytest test_basic.py -vblack *.py
ruff check *.pyContributions are welcome! Here's how you can help:
- 🍴 Fork the repository
- 🔧 Create a feature branch (
git checkout -b feature/amazing-feature) - 💾 Commit your changes (
git commit -m 'Add amazing feature') - 📤 Push to the branch (
git push origin feature/amazing-feature) - 🎉 Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Google Research - T5 Transformer Model
- Salesforce - WikiSQL Dataset
- Hugging Face - Transformers Library
- Manuel Romero - Fine-tuned WikiSQL Model
Found a bug? Open an issue
Have a question? Start a discussion
Love the project? Give it a ⭐ on GitHub!