{"id":23454858,"url":"https://github.com/samuelepignone/easynql","last_synced_at":"2026-05-09T14:11:59.352Z","repository":{"id":269353540,"uuid":"907143675","full_name":"SamuelePignone/EasyNQL","owner":"SamuelePignone","description":"EasyNQL converts natural language questions into SQL queries via Ollama and can optionally connect to a database for execution with automatic error correction.","archived":false,"fork":false,"pushed_at":"2024-12-22T23:59:13.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T01:54:30.426Z","etag":null,"topics":["database","llm","nlp","ollama","sql","sql-generation"],"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/SamuelePignone.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}},"created_at":"2024-12-22T23:30:20.000Z","updated_at":"2024-12-26T15:22:00.000Z","dependencies_parsed_at":"2024-12-23T00:33:56.695Z","dependency_job_id":"c1f2feed-a257-40bb-be26-329f9c16fad0","html_url":"https://github.com/SamuelePignone/EasyNQL","commit_stats":null,"previous_names":["samuelepignone/easynql"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelePignone%2FEasyNQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelePignone%2FEasyNQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelePignone%2FEasyNQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelePignone%2FEasyNQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamuelePignone","download_url":"https://codeload.github.com/SamuelePignone/EasyNQL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248328109,"owners_count":21085258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["database","llm","nlp","ollama","sql","sql-generation"],"created_at":"2024-12-24T03:14:50.788Z","updated_at":"2026-05-09T14:11:59.302Z","avatar_url":"https://github.com/SamuelePignone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EasyNQL (Natural Query Language)\n\nEasyNQL is a Python-based tool that transforms natural language questions into SQL queries using Large Language Models (LLMs) via [Ollama](https://ollama.com/). With EasyNQL, you can:\n\n- Generate **SQL SELECT queries** from plain language.\n- Optionally **connect to a database** to execute the generated queries and retrieve results.\n- **Automate error correction** for queries, thanks to LLM-powered corrections.\n- Extract a **database schema** using a dedicated script.\n\n---\n\n## Table of Contents\n1. [Features](#features)  \n2. [Requirements](#requirements)  \n3. [Installation](#installation)  \n4. [Usage Examples](#usage-examples)  \n5. [Extracting the Schema](#extracting-the-schema)  \n6. [Documentation](#documentation)\n7. [Known Issues and Future Improvements](#known-issues-and-future-improvements)\n8. [Contributing](#contributing)\n\n## Features\n\n- **Natural Language to SQL**  \n  Convert plain English questions into SQL `SELECT` queries without writing SQL directly.\n\n- **Schema Extraction \u0026 Awareness**  \n  Use the provided `extract_schema.py` script to generate a schema file from your database. EasyNQL uses this schema to produce accurate queries tailored to the schema’s tables and columns.\n\n- **Automatic Error Correction**  \n  If the generated query fails, EasyNQL tries to correct it using the LLM, retrying multiple times if necessary (`max_retries` parameter).\n\n- **Supported Databases**  \n  PostgreSQL, MySQL, SQLite (easily extendable to other SQL databases supported by SQLAlchemy).\n\n- **Integration with Ollama**  \n  Seamlessly integrates with Ollama to list available models and use them for query generation and correction.\n\n## Requirements\n\n- Python 3.9+  \n- [Ollama](https://ollama.com/) installed and configured.  \n- SQLAlchemy for database connectivity:\n  ```bash\n  pip install sqlalchemy\n  ```\n- A compatible database server and a valid connection URL (e.g., PostgreSQL, MySQL, or SQLite).\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/SamuelePignone/EasyNQL.git\ncd EasyNQL\n```\n\n2. Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n3. Extract the Database Schema (Optional):\nTo generate a schema file from an existing database:\n\n```bash\npython extract_schema.py \u003cdatabase_url\u003e schema.txt\n```\nThis will create a .txt file describing your database’s tables, columns, and constraints.\n\n4. Configure Ollama model:\nThe choice of Ollama model can significantly impact the performance and accuracy of the generated SQL queries.\nEnsure that the Ollama model you want to use (e.g., qwen2.5-coder:1.5b) is available. Refer to [Ollama’s Library](https://ollama.com/library) to manage models.\nQwen 2.5 coder 1.5b is a good trade-off between performance and resource consumption.\n\n## Usage Examples\n\n1. Generate SQL Only\nIf you just want to generate SQL from natural language (without executing it), you only need the schema file and the model:\n\n```python\nfrom easy_nql import EasyNQL\n\n# Initialize EasyNQL with the schema file and the model\neasy_nql = EasyNQL(db_schema_file=\"schema.txt\", model=\"qwen2.5-coder:1.5b\", logs=True)\n\n# Generate SQL from a natural language question\nsql_query = easy_nql.generate_sql(\"Show me the names of all customers who bought 'Product X'\")\nprint(\"Generated SQL Query:\", sql_query)\n```\n\n2. Generating and Executing SQL\nIf you also want to execute the generated queries and retrieve results:\n\n```python\nfrom easy_nql import EasyNQL\n\neasy_nql = EasyNQL(db_schema_file=\"schema.txt\", model=\"qwen2.5-coder:1.5b\", logs=True)\neasy_nql.connect(\"postgresql://user:password@localhost:5432/mydatabase\")\n\nresponse = easy_nql.chat(\"List all orders placed in the last 30 days\")\n\nprint(\"Generated SQL Query:\", response[\"query\"])\nprint(\"Results:\", response[\"results\"])\nprint(\"Execution Time (s):\", response[\"execution_time\"])\nprint(\"Retries used:\", response[\"retries\"])\n```\n\n3. Human-Readable Responses \nIf you prefer a human-friendly answer instead of raw query results, set `human_response=True`:\n\n```python\nresponse = easy_nql.chat(\"How many customers have ordered more than 5 times?\", human_response=True)\n\nprint(\"Generated SQL Query:\", response[\"query\"])\nprint(\"Results:\", response[\"result\"])\nprint(\"Human-friendly Answer:\", response[\"answer\"])\nprint(\"Execution Time (s):\", response[\"execution_time\"])\nprint(\"Retries used:\", response[\"retries\"])\n```\n\n4. Listing Available Models\n```python\navailable_models = easy_nql.list_available_models()\nprint(\"Available Models:\", available_models)\n```\n\n## Extracting the Schema\nUse extract_schema.py to generate a schema file. For example:\n\n```bash\npython extract_schema.py postgresql://user:password@localhost:5432/mydatabase schema.txt\n```\nThe generated schema.txt can be fed into NQL:\n\n```python\nnql = EasyNQL(db_schema_file=\"schema.txt\", model=\"qwen2.5-coder:1.5b\")\n```\n\nNQL will then use this schema information to produce SQL queries aligned with your database structure.\n\n## Documentation\n\n### Class `EasyNQL`\n\nParameters:\n\n- **db_schema** or **db_schema_file**: The source of the database schema to guide SQL generation.\n- **model**: The name of the Ollama model to use.\n- **database_type**: The type of database (e.g., postgresql, mysql, sqlite).\n- **logs**: Boolean indicating whether to enable logging.\n- **log_level**: Logging level (e.g., `DEBUG`, `INFO`).\n- **log_file**: Path for the log file (if logs are enabled).\n\nKey Methods:\n\n- **connect(database_url: str) -\u003e None**: Connect to the given database.\n- **generate_sql(natural_language_question: str) -\u003e str**: Convert a natural language question into a SQL `SELECT` query.\n- **chat(natural_language_question: str, max_retries: int = 3, human_response: bool = False) -\u003e dict**: Generate and optionally execute SQL query. If human_response is True, returns a human-friendly answer.\n- **list_available_models() -\u003e List[str]**: List all models available in Ollama.\n\nHelper Methods:\n\n- **fix_error_message(error: str, question: str = None, sql_query: str = None) -\u003e str**: Attempt to correct SQL errors using the LLM.\n- **generate_human_response(query_results: str, question: str = None) -\u003e str**: Given query results, produce a human-like summary.\n\n## Known Issues and Future Improvements\nRight now EasyNQL is in its early stages, it doesn't consider if some columns are sensitive or not, so it's important to be careful with the questions you ask and don't use it with sensitive data.\n\n## Contributing\nContributions are welcome! If you have suggestions, improvements, or feature requests, please open an issue or submit a pull request.\n\n### Thank you for choosing EasyNQL! 🎉\n\u003e Made with ❤️ by [Samuele Pignone](https://github.com/SamuelePignone)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelepignone%2Feasynql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelepignone%2Feasynql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelepignone%2Feasynql/lists"}