{"id":31078329,"url":"https://github.com/kelvinleandro/pagila-text-to-sql","last_synced_at":"2026-04-10T11:02:24.845Z","repository":{"id":314816243,"uuid":"1056851368","full_name":"kelvinleandro/pagila-text-to-sql","owner":"kelvinleandro","description":"An AI-powered application that lets you chat with your PostgreSQL database in natural language. Built with LangChain, FastAPI, and Streamlit.","archived":false,"fork":false,"pushed_at":"2025-09-14T23:33:37.000Z","size":744,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-09T22:35:13.872Z","etag":null,"topics":["chatbot","docker","docker-compose","fastapi","generative-ai","gpt","langchain","llm","natural-language-processing","nl-to-sql","openai","pagila-database","postgresql","python","python3","sql","sqlalchemy","streamlit","text-to-sql"],"latest_commit_sha":null,"homepage":"","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kelvinleandro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-14T23:32:38.000Z","updated_at":"2025-09-14T23:38:33.000Z","dependencies_parsed_at":"2025-09-15T01:17:17.056Z","dependency_job_id":"b1c6540e-8868-49f9-b5a7-67f7b0184edc","html_url":"https://github.com/kelvinleandro/pagila-text-to-sql","commit_stats":null,"previous_names":["kelvinleandro/pagila-text-to-sql"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kelvinleandro/pagila-text-to-sql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelvinleandro%2Fpagila-text-to-sql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelvinleandro%2Fpagila-text-to-sql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelvinleandro%2Fpagila-text-to-sql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelvinleandro%2Fpagila-text-to-sql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kelvinleandro","download_url":"https://codeload.github.com/kelvinleandro/pagila-text-to-sql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kelvinleandro%2Fpagila-text-to-sql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31639524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"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","docker","docker-compose","fastapi","generative-ai","gpt","langchain","llm","natural-language-processing","nl-to-sql","openai","pagila-database","postgresql","python","python3","sql","sqlalchemy","streamlit","text-to-sql"],"created_at":"2025-09-16T08:51:39.021Z","updated_at":"2026-04-10T11:02:24.827Z","avatar_url":"https://github.com/kelvinleandro.png","language":"PLpgSQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💬 Chat with Your Data (Pagila Database)\n\nThis project allows users to interact with a PostgreSQL database by asking questions. It leverages a Large Language Model (LLM) to translate natural language queries into SQL, execute them, and return human-readable answers.\n\nThe entire application is containerized using Docker, making it easy to set up and run with a single command.\n\n## 🏛️ Project Architecture\n\nThe application is built on a modern, decoupled architecture consisting of three main services orchestrated by Docker Compose:\n\n1. **Database** (db): A PostgreSQL container running the [**Pagila**](https://github.com/devrimgunduz/pagila) sample database. It is pre-configured with a read-only user for the backend to ensure data safety.\n\n2. **Backend** (backend): A **FastAPI** application that serves a single API endpoint (`/api/query`). It contains the core logic, using a **LangChain SQL Agent** to:\n\n   - Inspect the database schema.\n\n   - Generate SQL queries from user questions using an OpenAI LLM.\n\n   - Execute the query against the database.\n\n   - Synthesize a natural language response from the query results.\n\n3. **Frontend** (frontend): A **Streamlit** web application that provides a simple and interactive chat interface for the user. It communicates with the backend's API to send questions and display answers.\n\nAll services run on a shared Docker network, allowing them to communicate seamlessly using their service names.\n\n## ✨ Features\n\n- **Natural Language Querying**: Ask complex questions like \"Who are the top 5 customers by total spending?\"\n\n- **Secure by Design**: The backend connects to the database using a read-only user, preventing any possibility of data modification or deletion.\n\n- **Scalable Backend**: Built with FastAPI, the backend is asynchronous and ready for high performance.\n\n- **Interactive UI**: A clean and simple user interface built with Streamlit.\n\n- **Fully Containerized**: The entire stack is managed with Docker and Docker Compose for easy, one-command setup and deployment.\n\n## 💻 Tech Stack\n\n- **Backend**: Python, FastAPI, LangChain, OpenAI, SQLAlchemy\n\n- **Frontend**: Python, Streamlit, Requests\n\n- **Database**: PostgreSQL (with the Pagila sample dataset)\n\n- **DevOps**: Docker, Docker Compose\n\n## 🚀 Getting Started\n\nFollow these steps to get the entire application running on your local machine.\n\n### Prerequisites\n\n- Docker and Docker Compose must be installed on your system.\n\n- An OpenAI API Key.\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/kelvinleandro/pagila-text-to-sql.git\ncd pagila-text-to-sql\n```\n\n### 2. Create the Environment File\n\nThe application uses separate `.env` files for the backend and frontend. In both the `backend/` and `frontend/` directories, you will find a `.env.example` file. Make a copy of each and rename them to `.env`, then fill in your credentials.\n\n\u003e **Important**: When running with Docker, ensure the variables in your new `.env` files point to the correct service names (e.g., `db` for the database hostname and `http://backend:8000/api` for the API URL) and not `localhost`.\n\n### 3. Build and Run the Application\n\nWith Docker running, execute the following command from the project root:\n\n```bash\ndocker compose up --build\n```\n\nTo run the containers in the background (detached mode), use:\n\n```bash\ndocker compose up --build -d\n```\n\n### 4. Access the Services\n\nOnce everything is running, you can access the application:\n\n- **Streamlit Frontend**: Open your web browser and go to http://localhost:8501\n\n- **FastAPI Backend Docs**: To see the API documentation, go to http://localhost:8000/docs\n\n## 🔧 How to Use\n\n1. Navigate to http://localhost:8501.\n\n2. Type a question about the Pagila DVD rental database into the text input box.\n\n3. Click the send button.\n\n4. The answer will appear below.\n\n### Example Questions:\n\n- \"What are the 5 longest movies? Show me their titles and lengths.\"\n\n- \"Show me the total revenue for each store.\"\n\n- \"Which 3 actors have appeared in the most films?\"\n\n- \"How many films are in the 'Action' category?\"\n\n## 📜 License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkelvinleandro%2Fpagila-text-to-sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkelvinleandro%2Fpagila-text-to-sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkelvinleandro%2Fpagila-text-to-sql/lists"}