How dadiya-harsh-wappnet/sql-tool works
Project Type and Purpose
• This is a Python-based utility library (open-source tool) named SQL Agent Tool.
• Purpose: Safely connect to and execute read-only SQL queries on PostgreSQL via SQLAlchemy, with optional Groq API integration for natural-language query generation.
File Structure
• Top level:
• setup.py, pyproject.toml, requirements.txt – packaging and dependencies
• README.md, LICENSE, .gitignore – documentation
• sql_agent_tool/ – core library
• tests/ – pytest suite
• In sql_agent_tool/:
• core.py – main class (SQLAgentTool)
• models.py – pydantic DatabaseConfig model
• exceptions.py – custom error classes
• utils.py – any helper functions (e.g., env loading, parameter sanitization)
• Tests use pytest fixtures (tests/test_postgresql.py) and temporary tables to validate behavior.
Key README Insights
• Uses SQLAlchemy + psycopg2-binary for DB connection
• Pydantic for config validation
• Groq API key for optional NLP layer
• Schema reflection, safe parameter binding, and robust error handling
Main Components
• User Application (your code that imports/instantiates SQLAgentTool)
• SQLAgentTool (core component)
• DatabaseConfig (model)
• Exception Layer (custom exception classes)
• Utility Module (utils.py)
• SQLAlchemy + psycopg2-binary (library block, green)
1. User Application → DatabaseConfig: supplies connection parameters
2. DatabaseConfig → SQLAgentTool: injected at instantiation
3. SQLAgentTool → SQLAlchemy Engine: creates connection
4. SQLAgentTool → PostgreSQL:
• Schema Reflection (introspects tables)
• Query Execution (read-only SELECT with parameter binding)
5. SQLAgentTool ↔ Groq API (optional path):
• Send prompt → Groq returns generated SQL
6. SQLAgentTool → Exception Layer:
• Throws SchemaReflectionError, QueryValidationError, or ExecutionError on failure
7. SQLAgentTool → User Application: returns Result object with .data
Architectural Patterns & Principles
• Layered Design:
• Presentation Layer (User code)
• Application Layer (SQLAgentTool)
• Domain Layer (DatabaseConfig, models.py)
• Infrastructure Layer (SQLAlchemy + PostgreSQL, Groq API)
• Single Responsibility: each module has one concern (core logic vs. config vs. exceptions)
• Dependency Injection: DatabaseConfig + optional groq_api_key passed into SQLAgentTool
• Error Handling: custom exceptions for each failure domain
Putting It All Together
• SQLAgentTool in the center inside the “sql_agent_tool” boundary.
• Under it, group DatabaseConfig, exceptions.py, utils.py, models.py.