{"id":29637807,"url":"https://github.com/celestialtaha/psql-query-builder","last_synced_at":"2026-03-07T12:02:56.009Z","repository":{"id":294043971,"uuid":"985845371","full_name":"celestialtaha/psql-query-builder","owner":"celestialtaha","description":"Generate \u0026 Run PostgreSQL queries by only providing natural language inputs using AI | langchain compatible","archived":false,"fork":false,"pushed_at":"2025-05-18T17:28:41.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-02T17:41:53.843Z","etag":null,"topics":["ai-agent","ai-agent-tools","database","langchain","nlp","nlp-machine-learning","openai-api","postgresql","python","query-builder","sql","sql-generator"],"latest_commit_sha":null,"homepage":"","language":"Python","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/celestialtaha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2025-05-18T16:38:04.000Z","updated_at":"2025-05-20T20:49:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"1dc6f128-7bac-486b-ac88-dd8473dfa9f9","html_url":"https://github.com/celestialtaha/psql-query-builder","commit_stats":null,"previous_names":["celestialtaha/psql-query-builder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/celestialtaha/psql-query-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celestialtaha%2Fpsql-query-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celestialtaha%2Fpsql-query-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celestialtaha%2Fpsql-query-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celestialtaha%2Fpsql-query-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/celestialtaha","download_url":"https://codeload.github.com/celestialtaha/psql-query-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celestialtaha%2Fpsql-query-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30212490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"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":["ai-agent","ai-agent-tools","database","langchain","nlp","nlp-machine-learning","openai-api","postgresql","python","query-builder","sql","sql-generator"],"created_at":"2025-07-21T19:01:50.000Z","updated_at":"2026-03-07T12:02:55.969Z","avatar_url":"https://github.com/celestialtaha.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔍 PSQL Query Builder\n\n\u003ch3\u003eTransform natural language into optimized PostgreSQL queries with AI\u003c/h3\u003e\n\n[![PyPI version](https://badge.fury.io/py/psql-query-builder.svg)](https://badge.fury.io/py/psql-query-builder)\n[![Python Versions](https://img.shields.io/pypi/pyversions/psql-query-builder.svg)](https://pypi.org/project/psql-query-builder/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://static.pepy.tech/badge/psql-query-builder)](https://pepy.tech/project/psql-query-builder)\n\n\u003c/div\u003e\n\n## ✨ Overview\n\nPSQL Query Builder is a powerful Python tool that transforms natural language into optimized PostgreSQL queries using AI. It bridges the gap between human language and SQL, making database interaction accessible to everyone - not just SQL experts.\n\nBuilt on OpenAI's advanced language models, this tool analyzes your database schema and generates precise, efficient SQL queries based on plain English descriptions. Whether you're a data analyst without SQL expertise, a developer looking to speed up query writing, or a database administrator seeking to simplify access for your team, PSQL Query Builder streamlines your workflow.\n\n## ✅ Features\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003e🤖 AI-Powered SQL Generation\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003eTransform natural language to optimized SQL\u003c/li\u003e\n        \u003cli\u003eContext-aware query generation\u003c/li\u003e\n        \u003cli\u003eSupport for complex queries and joins\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003e⚡ Smart Schema Caching\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003eAutomatic database schema analysis\u003c/li\u003e\n        \u003cli\u003eConfigurable cache TTL\u003c/li\u003e\n        \u003cli\u003eSignificant performance improvement\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003e🛠️ Flexible Configuration\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003eEnvironment variables support\u003c/li\u003e\n        \u003cli\u003eCommand-line arguments\u003c/li\u003e\n        \u003cli\u003eMultiple output formats (table, JSON, CSV)\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003e🔧 Intelligent Error Handling\u003c/h3\u003e\n      \u003cul\u003e\n        \u003cli\u003eAutomatic fix suggestions\u003c/li\u003e\n        \u003cli\u003eDetailed error messages\u003c/li\u003e\n        \u003cli\u003eInteractive query correction\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## 🎯 Use Cases\n\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n      \u003ch3\u003e📊 Data Analysts\u003c/h3\u003e\n      \u003cp\u003eGenerate complex SQL queries without deep SQL knowledge\u003c/p\u003e\n      \u003cp\u003eQuickly explore database structures and relationships\u003c/p\u003e\n      \u003cp\u003ePrototype queries in natural language before refinement\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n      \u003ch3\u003e👨‍💻 Developers\u003c/h3\u003e\n      \u003cp\u003eSpeed up database query development\u003c/p\u003e\n      \u003cp\u003eReduce time spent debugging complex SQL syntax\u003c/p\u003e\n      \u003cp\u003eGenerate queries for unfamiliar database schemas\u003c/p\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n      \u003ch3\u003e🛡️ Database Admins\u003c/h3\u003e\n      \u003cp\u003eProvide simplified access to non-technical team members\u003c/p\u003e\n      \u003cp\u003eQuickly generate queries for common reporting needs\u003c/p\u003e\n      \u003cp\u003eValidate schema design through natural language\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\npip install psql-query-builder\n```\n\n### Basic Usage\n\n```bash\n# Using environment variables for connection\nexport PSQL_CONNECTION_STRING=\"postgresql://username:password@localhost:5432/database\"\nexport OPENAI_API_KEY=\"your-openai-api-key\"\n\n# Run a query\npsql-query-builder --query \"Find all active users who registered last month\"\n```\n\n### Python API\n\n```python\nfrom psql_query_builder import QueryBuilder\n\n# Initialize the query builder\nbuilder = QueryBuilder(\n    connection_string=\"postgresql://username:password@localhost:5432/database\",\n    openai_api_key=\"your-openai-api-key\"\n)\n\n# Generate and execute a query\nresults = builder.run_query(\n    \"Find all products with more than 100 units in stock and price less than $50\",\n    execute=True\n)\n\n# Print the results\nprint(results)\n```\n\n### LangChain Integration\n\nPSQL Query Builder can be easily integrated with LangChain to enable natural language database queries in your AI applications:\n\n```python\n# Using the @tool decorator approach\nfrom langchain_core.tools import tool\n\n@tool\ndef query_database(query: str, connection_string: str = \"postgresql://user:pass@localhost/db\"):\n    \"\"\"Execute a natural language query against a PostgreSQL database.\"\"\"\n    from psql_query_builder import QueryBuilder\n    \n    builder = QueryBuilder(connection_string=connection_string)\n    return builder.run_query(query, execute=True)\n\n# Use with LangChain\nfrom langchain_openai import ChatOpenAI\nfrom langchain.agents import create_openai_tools_agent, AgentExecutor\n\nllm = ChatOpenAI(model=\"gpt-4-turbo\")\ntools = [query_database]\nagent = create_openai_tools_agent(llm, tools, prompt=None)\nagent_executor = AgentExecutor(agent=agent, tools=tools)\n\n# Run the agent\nresponse = agent_executor.invoke({\"input\": \"Find all users who registered last month\"})\nprint(response[\"output\"])\n```\n\nFor more advanced integration options, see the full documentation.\n\n## ⚙️ Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eEnvironment Variables\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Full connection string\nexport PSQL_CONNECTION_STRING=\"postgresql://username:password@localhost:5432/database\"\n\n# Or individual connection parameters\nexport PSQL_HOST=\"localhost\"\nexport PSQL_PORT=\"5432\"\nexport PSQL_USER=\"username\"\nexport PSQL_PASSWORD=\"password\"\nexport PSQL_DATABASE=\"database\"\n\n# OpenAI API key\nexport OPENAI_API_KEY=\"your-openai-api-key\"\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCommand-line Arguments\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npsql-query-builder \\\n  --host localhost \\\n  --port 5432 \\\n  --user username \\\n  --password password \\\n  --database database \\\n  --api-key your-openai-api-key \\\n  --query \"Find all products with more than 100 units in stock\" \\\n  --dry-run  # Optional: generate SQL without executing\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDry Run Mode\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Generate SQL only, don't execute (useful for reviewing queries before running on production databases)\npsql-query-builder --query \"Find all inactive users who haven't logged in for 3 months\" --dry-run\n\n# Output:\n# Generated SQL query (dry run mode):\n# --------------------------------------------------\n# SELECT u.id, u.username, u.email, u.last_login\n# FROM users u\n# WHERE u.last_login \u003c NOW() - INTERVAL '3 months'\n# ORDER BY u.last_login ASC;\n# --------------------------------------------------\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSchema Caching\u003c/b\u003e\u003c/summary\u003e\n\nFor better performance with repeated queries, enable schema caching:\n\n```bash\n# Enable schema caching with default settings\npsql-query-builder --query \"Find all users who placed orders in the last week\" --cache\n\n# Specify cache path and TTL (time-to-live in seconds)\npsql-query-builder --query \"Find all users who placed orders in the last week\" \\\n  --cache \\\n  --cache-path \"/tmp/schema_cache\" \\\n  --cache-ttl 3600\n\n# Force refresh the cache\npsql-query-builder --query \"Find all users who placed orders in the last week\" \\\n  --cache \\\n  --force-refresh\n```\n\u003c/details\u003e\n\n## 📘 Advanced Usage\n\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003ch3\u003e💬 Interactive Mode\u003c/h3\u003e\n      \u003cp\u003eStart an interactive session for multiple queries:\u003c/p\u003e\n      \u003cpre\u003e\u003ccode\u003epsql-query-builder\u003c/code\u003e\u003c/pre\u003e\n      \u003cp\u003eThen enter queries at the prompt:\u003c/p\u003e\n      \u003cpre\u003e\u003ccode\u003e\u003e Find all customers in California\n\u003e Show revenue by product category\n\u003e exit\u003c/code\u003e\u003c/pre\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003ch3\u003e🔍 Single Query Mode\u003c/h3\u003e\n      \u003cp\u003eExecute a single query and exit:\u003c/p\u003e\n      \u003cpre\u003e\u003ccode\u003epsql-query-builder --query \"Find all users \nwho registered in the last month\"\u003c/code\u003e\u003c/pre\u003e\n      \u003cp\u003ePerfect for scripts and automation\u003c/p\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\n\n## 📚 API Reference\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePython API\u003c/b\u003e\u003c/summary\u003e\n\n```python\nfrom psql_query_builder import QueryBuilder\n\n# Initialize with connection string\nbuilder = QueryBuilder(\n    connection_string=\"postgresql://username:password@localhost:5432/database\",\n    openai_api_key=\"your-openai-api-key\"\n)\n\n# Or with individual parameters\nbuilder = QueryBuilder(\n    host=\"localhost\",\n    port=5432,\n    database=\"mydatabase\",\n    user=\"myuser\",\n    password=\"mypassword\",\n    openai_api_key=\"your-openai-api-key\"\n)\n\n# Generate SQL without executing\nsql = builder.generate_query(\"Find all users who registered last month\")\nprint(sql)\n\n# Generate and execute query\nresults = builder.run_query(\n    \"Find all products with more than 100 units in stock\",\n    execute=True\n)\nprint(results)\n```\n\u003c/details\u003e\n\n## 🚩 Roadmap\n\nFuture development plans for PSQL Query Builder include:\n\n- [ ] Support for more database systems (MySQL, SQLite, SQL Server)\n- [ ] Interactive SQL editing and refinement\n- [ ] Query history management and reuse\n- [ ] Integration with popular database tools and ORMs\n- [ ] Web interface for non-CLI usage\n- [ ] Query optimization suggestions\n- [ ] Support for database migrations and schema changes\n\nFeel free to contribute to any of these features or suggest new ones!\n\n## 👨‍💻 Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Report bugs or request features**: Open an issue describing what you found or what you'd like to see\n2. **Submit improvements**: Fork the repository, make your changes, and submit a pull request\n3. **Improve documentation**: Help clarify or expand the documentation\n4. **Share your use cases**: Let us know how you're using PSQL Query Builder\n\n## 📜 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelestialtaha%2Fpsql-query-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelestialtaha%2Fpsql-query-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelestialtaha%2Fpsql-query-builder/lists"}