{"id":31939503,"url":"https://github.com/cyprianfusi/chat-with-sql-dbs","last_synced_at":"2026-07-18T12:10:53.852Z","repository":{"id":315135363,"uuid":"1058255479","full_name":"CyprianFusi/chat-with-sql-dbs","owner":"CyprianFusi","description":"A Streamlit web application that allows you to chat with SQL databases using natural language queries powered by LangChain and Groq's LLM API.","archived":false,"fork":false,"pushed_at":"2025-09-20T06:41:04.000Z","size":3070,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-23T06:38:34.242Z","etag":null,"topics":["agentic-ai","database","generative-ai","langchain","sql","sqlalchemy","sqlite3","streamlit"],"latest_commit_sha":null,"homepage":"https://binati-ai.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CyprianFusi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-16T20:55:03.000Z","updated_at":"2025-09-20T06:41:07.000Z","dependencies_parsed_at":"2025-09-16T23:48:23.112Z","dependency_job_id":"b9cc7685-b355-4178-8745-d859df5c59b6","html_url":"https://github.com/CyprianFusi/chat-with-sql-dbs","commit_stats":null,"previous_names":["cyprianfusi/chat-with-sql-dbs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CyprianFusi/chat-with-sql-dbs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyprianFusi%2Fchat-with-sql-dbs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyprianFusi%2Fchat-with-sql-dbs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyprianFusi%2Fchat-with-sql-dbs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyprianFusi%2Fchat-with-sql-dbs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CyprianFusi","download_url":"https://codeload.github.com/CyprianFusi/chat-with-sql-dbs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyprianFusi%2Fchat-with-sql-dbs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35617031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","database","generative-ai","langchain","sql","sqlalchemy","sqlite3","streamlit"],"created_at":"2025-10-14T08:28:01.046Z","updated_at":"2026-07-18T12:10:53.847Z","avatar_url":"https://github.com/CyprianFusi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/CyprianFusi/chat-with-sql-dbs/main/assets/binati_logo.png\" alt=\"BINATI AI Logo\" width=\"75\"/\u003e\u003cstrong\u003e\u003c/strong\u003e\n\n  # 🛢️ Chat with SQL Databases\n\n  _By **BINATI AInalytics**_\n\u003c/div\u003e\n\n\nA Streamlit web application that allows you to chat with SQL databases using natural language queries powered by LangChain and Groq's LLM API.\n\nSee deployment demo at https://chat-with-sql-dbs-6ffixmdjypdlglejfomjwb.streamlit.app/\n# Demo\n![DB Demo](assets/ui_1.png)\n![DB Demo](assets/ui_2.png)\n![DB Demo](assets/ui_3.png)\n![DB Demo](assets/ui_4.png)\n![DB Demo](assets/ui_5.png)\n![DB Demo](assets/ui_6.png)\n![DB Demo](assets/ui_7.png)\n\n## ✨ Features\n\n- **Multi-Database Support**: Connect to SQLite, MySQL, or PostgreSQL databases\n- **Natural Language Queries**: Ask questions about your data in plain English\n- **Real-time Streaming**: Get responses as they're generated\n- **Interactive Chat Interface**: Conversation-style interaction with your database\n- **Secure Connections**: Password-protected database credentials\n- **Local SQLite Support**: Includes a local `coursework.db` for quick testing\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Python 3.7+\n- pip package manager\n\n### Installation\n\n1. **Clone the repository** (or download the files)\n   ```bash\n   git clone https://github.com/CyprianFusi/chat-with-sql-dbs.git\n   cd chat-with-sql-dbs\n   ```\n\n2. **Install required packages**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up environment variables** (optional)\n   Create a `.env` file in the project root:\n   ```env\n   GROQ_API_KEY=your_groq_api_key_here\n   ```\n\n4. **Prepare your database** (if using local SQLite)\n   - Ensure `coursework.db` exists in the project directory\n   - Or modify the code to point to your SQLite database\n\n### Running the Application\n\n```bash\nstreamlit run app.py\n```\n\nThe application will open in your default web browser at `http://localhost:8501`\n\n## 🔧 Configuration\n\n### Database Options\n\nThe application supports three types of databases:\n\n#### 1. **SQLite (Local)**\n- **File**: `coursework.db` (must be in the same directory as `app.py`)\n- **Use case**: Testing, small datasets, local development\n- **Setup**: No additional configuration required\n\n#### 2. **MySQL Database**\n- **Required fields**:\n  - Host (e.g., `localhost` or `your-mysql-host.com`)\n  - Username\n  - Password\n  - Database name\n- **Use case**: Production applications, shared databases\n\n#### 3. **PostgreSQL Database**\n- **Required fields**:\n  - Host (e.g., `localhost` or `your-postgres-host.com`)\n  - Username\n  - Password\n  - Database name\n  - Port (default: 5432)\n- **Use case**: Enterprise applications, complex queries\n\n### API Configuration\n\n1. **Get a Groq API key**:\n   - Visit [Groq Cloud](https://console.groq.com)\n   - Sign up for an account\n   - Generate an API key\n\n2. **Enter the API key**:\n   - Use the sidebar input field in the application\n   - Or add it to your `.env` file as `GROQ_API_KEY`\n\n## 💡 Usage Examples\n\nOnce the application is running, you can ask natural language questions about your database:\n\n- **Data Exploration**:\n  - \"Show me all tables in the database\"\n  - \"What columns are in the users table?\"\n  - \"How many records are in the orders table?\"\n\n- **Business Queries**:\n  - \"What are the top 5 customers by total purchase amount?\"\n  - \"Show me sales trends for the last quarter\"\n  - \"Which products have the highest ratings?\"\n\n- **Analytical Questions**:\n  - \"What's the average order value by customer segment?\"\n  - \"Find customers who haven't made a purchase in the last 90 days\"\n  - \"Compare revenue between different product categories\"\n\n## 🏗️ Project Structure\n\n```\nproject-directory/\n│\n├── app.py              # Main Streamlit application\n├── coursework.db       # Sample SQLite database (if using local option)\n├── .env               # Environment variables (optional)\n├── README.md          # This file\n└── requirements.txt   # Python dependencies (optional)\n```\n\n## 📦 Dependencies\n\n- **streamlit**: Web application framework\n- **langchain-community**: LangChain community integrations\n- **langchain-groq**: Groq LLM integration\n- **python-dotenv**: Environment variable management\n- **sqlalchemy**: Database toolkit\n- **mysql-connector-python**: MySQL database connector\n- **psycopg2-binary**: PostgreSQL adapter\n\n## 🛠️ Technical Details\n\n### Architecture\n\n- **Frontend**: Streamlit for the web interface\n- **LLM**: Groq's Llama-3.1-8b-instant model for natural language processing\n- **Framework**: LangChain for SQL agent creation and database interaction\n- **Database Layer**: SQLAlchemy for database connections and queries\n\n### Key Components\n\n- **SQL Agent**: Uses LangChain's `create_sql_agent` with tool-calling capabilities\n- **Database Abstraction**: `SQLDatabase` wrapper for different database types\n- **Streaming**: Real-time response streaming with `StreamlitCallbackHandler`\n- **Caching**: Database connections cached for 2 hours for performance\n\n## 🔒 Security Considerations\n\n- API keys and database passwords are handled securely through Streamlit's input widgets\n- Database connections use proper SQLAlchemy engines with appropriate drivers\n- SQLite connections include thread safety configurations\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **\"Please provide all connection details\" error**\n   - Ensure all required database fields are filled in the sidebar\n\n2. **\"Please enter the groq api key\" message**\n   - Add your Groq API key in the sidebar input field\n\n3. **Database connection errors**\n   - Verify your database credentials and network connectivity\n   - For local SQLite, ensure `coursework.db` exists in the project directory\n\n4. **Package import errors**\n   - Install all required dependencies: `pip install -r requirements.txt`\n\n### Performance Tips\n\n- Use the \"Clear message history\" button to reset the conversation\n- Database connections are cached, but may need refreshing after 2 hours\n- For large databases, consider adding specific table/column filters\n\n## 🤝 Contributing\n\nFeel free to contribute by:\n- Adding support for additional database types\n- Improving the UI/UX\n- Adding more sophisticated query capabilities\n- Enhancing error handling and validation\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://raw.githubusercontent.com/Dogfalo/materialize/master/LICENSE) file for details.\n\n## 🔗 Resources\n\n- [Streamlit Documentation](https://docs.streamlit.io)\n- [LangChain Documentation](https://python.langchain.com)\n- [Groq API Documentation](https://console.groq.com/docs)\n- [SQLAlchemy Documentation](https://docs.sqlalchemy.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyprianfusi%2Fchat-with-sql-dbs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyprianfusi%2Fchat-with-sql-dbs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyprianfusi%2Fchat-with-sql-dbs/lists"}