Documentation

Installation

Install SmartQL using pip:

pip install smartql

Or with uv:

uv pip install smartql

Quick Start

1. Create a configuration file

Create a smartql.yml file:

version: "1.0"

database:
  type: mysql
  connection:
    host: localhost
    database: myapp
    user: ${DB_USER}
    password: ${DB_PASSWORD}

llm:
  provider: groq
  groq:
    api_key: ${GROQ_API_KEY}
    model: llama-3.1-8b-instant

security:
  mode: read_only
  max_rows: 1000

2. Start asking questions

# Interactive shell
smartql shell -c smartql.yml

# Single query
smartql ask "How many users signed up this month?" -c smartql.yml

CLI

SmartQL provides a command-line interface for interacting with your database.

Commands

Shell Commands

When in interactive shell mode:

Python Library

Use SmartQL directly in your Python applications.

Basic Usage

from smartql import SmartQL

sql = SmartQL.from_yaml("smartql.yml")

# Generate SQL only
result = sql.ask("Show me all active users with orders")
print(result.sql)
print(result.explanation)

# Generate and execute
result = sql.ask("Top 10 customers by revenue", execute=True)
for row in result.rows:
    print(row)

Programmatic Configuration

from smartql import SmartQL

sql = SmartQL(
    database_url="mysql://user:pass@localhost/myapp",
    llm_provider="openai",
    llm_model="gpt-4o",
    api_key="your-api-key"
)

REST API

SmartQL can run as an HTTP server for language-agnostic access.

Start the server

smartql serve -c smartql.yml --port 8000

Endpoints

Example Request

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"question": "Show me top 5 customers by spending"}'

Example Response

{
  "sql": "SELECT c.name, SUM(o.total) AS spending FROM customers c JOIN orders o ON o.customer_id = c.id GROUP BY c.id ORDER BY spending DESC LIMIT 5",
  "explanation": "Joins customers with orders, calculates total spending per customer, and returns the top 5."
}

Configuration

SmartQL uses a YAML configuration file.

Database Configuration

database:
  type: mysql  # mysql, postgresql, sqlite, sqlserver
  connection:
    host: localhost
    port: 3306
    database: myapp
    user: ${DB_USER}
    password: ${DB_PASSWORD}

Or use a connection URL:

database:
  url: mysql://user:pass@localhost:3306/myapp

Supported Databases

• PostgreSQL
• MySQL / MariaDB
• SQLite
• SQL Server

Semantic Layer

The semantic layer adds business context to your database schema, improving query accuracy.

semantic_layer:
  entities:
    customers:
      table: users
      description: "Registered customers"
      aliases: ["users", "members", "clients"]
      columns:
        id:
          type: integer
          primary: true
        email:
          type: string
          description: "Customer email address"
        status:
          type: enum
          values: ["active", "inactive", "suspended"]

  relationships:
    - name: customer_orders
      type: one_to_many
      from: customers
      to: orders
      foreign_key: user_id

  business_rules:
    - name: active
      applies_to: [customers]
      definition: "status = 'active'"
      description: "Active customers only"

    - name: high_value
      applies_to: [orders]
      definition: "total >= 1000"
      description: "Orders over $1000"

Without a semantic layer, SmartQL auto-introspects your database schema.

Security

SmartQL uses sqlglot for AST-based SQL parsing and validation—not regex.

security:
  mode: read_only           # Only SELECT queries allowed

  allowed_tables:           # Whitelist tables
    - users
    - orders
    - products

  blocked_columns:          # Hide sensitive data
    - users.password
    - users.api_token
    - users.ssn

  max_rows: 1000           # Prevent large result sets
  timeout_seconds: 30      # Query timeout
  max_join_depth: 4        # Limit JOIN complexity

Security Modes

LLM Providers

SmartQL uses LiteLLM for unified access to 100+ models.

OpenAI

llm:
  provider: openai
  openai:
    api_key: ${OPENAI_API_KEY}
    model: gpt-4o

Anthropic Claude

llm:
  provider: anthropic
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    model: claude-sonnet-4-20250514

Google Gemini

llm:
  provider: google
  google:
    api_key: ${GEMINI_API_KEY}
    model: gemini-2.0-flash

Groq (Fast & Free Tier)

llm:
  provider: groq
  groq:
    api_key: ${GROQ_API_KEY}
    model: llama-3.1-8b-instant

Ollama (Local)

llm:
  provider: ollama
  ollama:
    model: llama3:8b
    api_base: http://localhost:11434