TESH-Query (Text to Executable SQL Handler) lets you query any relational database using plain English. Powered by Google Gemini or Azure OpenAI, it analyzes your database schema, generates SQL, validates it for safety, and returns results — all from a single command or a few lines of Python.

Table of Contents

• Features
• Installation
• Quick Start
• CLI Reference
• Python SDK
• How It Works
• Contributing
• License

Features

• Natural Language Querying — Ask questions in plain English, get SQL and results back instantly.
• Google Gemini & Azure OpenAI — Choose your preferred LLM provider at configuration time.
• Broad Database Support — PostgreSQL, MySQL, SQLite, MSSQL, MariaDB, and Oracle via SQLAlchemy.
• Safe Execution — All generated SQL is AST-validated before execution. Destructive commands (DROP, DELETE, ALTER, TRUNCATE) are blocked by default.
• Flexible Exports — Save results to CSV, Excel (.xlsx), or SQLite with a single flag.
• Dry Run & Explain Modes — Inspect generated SQL before it touches your database.
• Python SDK — Integrate NL-to-SQL into your own applications.
• Token & Cost Analytics — Track LLM usage and estimated costs per query.

Installation

Requires Python 3.10 or higher.

pip install teshq

With database driver extras:

# PostgreSQL
pip install "teshq[postgres]"

# MySQL / MariaDB
pip install "teshq[mysql]"

# Microsoft SQL Server
pip install "teshq[mssql]"

# Everything (no system dependencies required)
pip install "teshq[all]"

Quick Start

Step 1 — Configure your database and LLM provider

# Interactive database setup
teshq config --db

# Set up your LLM provider (choose one)
teshq config --gemini     # Google Gemini
teshq config --azure      # Azure OpenAI

All credentials are stored securely at ~/.teshq/ and are transmitted only to the configured provider endpoint when authenticating requests.

Step 2 — Introspect your database schema

This step analyzes your tables, columns, and relationships. It only needs to be run once, or whenever your schema changes.

teshq introspect

Step 3 — Start querying

teshq query "Show me the top 10 customers by total revenue this year"
teshq query "Which products are running low on inventory?"
teshq query "Monthly sales breakdown for Q1 2024"

CLI Reference

teshq query

Run a natural language query against your database.

teshq query [OPTIONS] "Your question in plain English"

Examples:

# Basic query
teshq query "Find all users who registered in the last 7 days"

# Inspect generated SQL without running it
teshq query "Total orders by country" --dry-run

# Save output to Excel
teshq query "Monthly revenue trend" --save-excel revenue_report

# Limit results
teshq query "Recent orders" --limit 50

Other Commands

Python SDK

TESH-Query can be used directly in Python applications for building AI-powered data tools.

import teshq

# Connect with Google Gemini
client = teshq.TeshQuery(
    db_url="postgresql://user:pass@localhost:5432/mydb",
    gemini_api_key="your-api-key"
)

# Or connect with Azure OpenAI
client = teshq.TeshQuery(
    db_url="postgresql://user:pass@localhost:5432/mydb",
    provider="azure",
    azure_api_key="your-azure-key",
    azure_endpoint="https://your-resource.openai.azure.com/",
    azure_deployment="gpt-4o",
)

# Introspect the database schema once
client.introspect_database()

# Ask a natural language question
result = client.query("Show the top 5 customers by lifetime value")

# Access results as a Pandas DataFrame
print(result.dataframe)

# Or get raw rows
print(result.rows)

# Generate SQL without executing it
sql_info = client.generate_sql("Count all active users")
print(sql_info["query"])

How It Works

TESH-Query processes every query through a structured pipeline designed for accuracy and safety:

User Query (natural language)
        │
        ▼
┌───────────────────┐
│  Schema Retrieval │  Loads your compressed schema from the local cache
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│   AI Planning     │  Identifies the relevant tables and joins needed
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│  SQL Generation   │  Produces dialect-specific SQL via structured LLM output
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│    Validation     │  AST scan: blocks DROP, DELETE, ALTER, TRUNCATE
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│    Execution      │  Runs SQL via SQLAlchemy, returns DataFrame or table
└───────────────────┘

Contributing

We welcome contributions — bug fixes, new database support, and documentation improvements are all appreciated.

# 1. Fork and clone the repository
git clone https://github.com/theshashank1/TESH-Query.git
cd TESH-Query

# 2. Install development dependencies
pip install -e ".[dev]"

# 3. Run the test suite before making changes
pytest tests/unit/

# 4. Create a feature branch and submit a Pull Request
git checkout -b feature/your-feature-name

Please read CONTRIBUTING.md for our code of conduct and contribution process.

License

MIT License. See LICENSE for details.