{"id":28816740,"url":"https://github.com/thomasjerard/chatsql","last_synced_at":"2026-04-29T14:04:14.941Z","repository":{"id":299578876,"uuid":"1003069822","full_name":"thomasjerard/ChatSQL","owner":"thomasjerard","description":"🔍 Convert natural language into PostgreSQL queries using Google Gemini and FastMCP’s Model Context Protocol. 💬 Ask database questions in plain English — get valid SQL instantly.","archived":false,"fork":false,"pushed_at":"2025-06-17T08:19:30.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-17T09:19:30.780Z","etag":null,"topics":["chatbot","chatsql","fastmcp","gemini-api","gemini-flash-2","modelcontextprotocol","nlp","postgresql"],"latest_commit_sha":null,"homepage":"","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/thomasjerard.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}},"created_at":"2025-06-16T15:17:18.000Z","updated_at":"2025-06-17T08:25:49.000Z","dependencies_parsed_at":"2025-06-17T09:30:47.473Z","dependency_job_id":null,"html_url":"https://github.com/thomasjerard/ChatSQL","commit_stats":null,"previous_names":["thomasjerard/chatsql"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thomasjerard/ChatSQL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasjerard%2FChatSQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasjerard%2FChatSQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasjerard%2FChatSQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasjerard%2FChatSQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomasjerard","download_url":"https://codeload.github.com/thomasjerard/ChatSQL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasjerard%2FChatSQL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32428622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["chatbot","chatsql","fastmcp","gemini-api","gemini-flash-2","modelcontextprotocol","nlp","postgresql"],"created_at":"2025-06-18T17:06:45.307Z","updated_at":"2026-04-29T14:04:14.936Z","avatar_url":"https://github.com/thomasjerard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💬 ChatSQL — Natural Language to SQL using Gemini \u0026 FastMCP\n\nChatSQL is a command-line tool that lets you query a PostgreSQL database using natural language.\nIt uses **Google Gemini** to convert your questions into SQL, and **FastMCP** to execute them against your database.\n\n---\n\n## 🚀 Tech Stack\n\n* Python 3.11+\n* PostgreSQL (via `psycopg2`)\n* FastMCP (Modular Composable Protocol)\n* Google Gemini (for Natural Language to SQL conversion)\n* Rich (for pretty command-line interface output)\n* python-dotenv (for environment variable configuration)\n\n---\n\n## 🧠 Use Case\n\nYou ask a question in plain English, and ChatSQL generates and executes the SQL, then displays the results.\n\n\u003e **Input:**\n\u003e \"Get all employees earning more than 50000\"\n\n\u003e **Generated SQL:**\n\u003e `SELECT * FROM employees WHERE salary \u003e 50000;`\n\n\u003e **Output:**  \n\n\u003e +----+---------+--------+------------+-----------+------------+\n\n\u003e | id | name | salary | phone_no | address | department |\n\n\u003e +----+---------+--------+------------+-----------+------------+\n\n\u003e | 1 | Alice | 75000 | 9876543210 | New York | HR |\n\n\u003e | 2 | Bob | 65000 | 1234567890 | Chicago | Finance |\n\n\u003e +----+---------+--------+------------+-----------+------------+\n\n\n---\n\n## ⚙️ Setup Instructions\n\n### ✅ 1. Clone the Repository \u0026 Configure Environment\n\n```bash\n\u003e git clone https://github.com/thomasjerard/ChatSQL.git\n\u003e cd chatSQL\n```\n\n### ✅ 2. Prerequisites\n\n* Bash shell is required (default on macOS/Linux).\n* Python 3.11+ must be installed and accessible via your terminal. \nIf not installed, \n\nFor macOS:\n```bash\nbrew install python@3.11\n```\nFor Linux:\n```bash\nsudo apt install python3.11 python3.11-venv\n```\n\n\n### ✅ 3. Create a .env file in the root folder with the following content:\n\n```bash\nDB_NAME=chattosql\nDB_USER=postgres\nDB_PASS=yourpassword\nDB_HOST=localhost\nDB_PORT=5432\nGEMINI_API_KEY=your-gemini-api-key\n```\n\n### ✅ 3. Run the Application\nYou’ll need two separate terminals:\n\n🖥️ Terminal 1 — Start the Server\n```bash\n./run_server.sh\n```\n\n💬Terminal 2 — Start the Client\n```bash\n./run_client.sh\n```\nOnce the client starts, you'll see a prompt like:\n\n💬 ChatSQL (Gemini + FastMCP)\n🗨️ Ask (NL):\n\n### 🔧 What Happens Internally\n\n1. Each script (run_server.sh / run_client.sh) performs the following:\n\n2. Deletes any existing virtual environment and creates a fresh one.\n\n3. Loads environment variables from the .env file.\n\n4. Installs required Python dependencies from requirements.txt.\n\n5. Sets up PostgreSQL:\n\n6. Creates the database (chattosql)\n\n7. Adds the user (postgres)\n\n8. Creates a sample employees table\n\n9. Starts the FastMCP server or the ChatSQL CLI client, depending on the script.\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasjerard%2Fchatsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasjerard%2Fchatsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasjerard%2Fchatsql/lists"}