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

Ask in any language

SmartQL does not assume your question is in English. The question is passed straight to the language model, so you can ask in any language the model understands, and SmartQL returns SQL against the same schema. Same validation, same semantic layer, same security rules apply regardless of the input language.

# Spanish
smartql ask "¿Cuántos clientes se registraron este mes?" -c smartql.yml

# French
smartql ask "Top 10 des clients par chiffre d'affaires" -c smartql.yml

# Arabic
smartql ask "أظهر أعلى 5 منتجات مبيعًا" -c smartql.yml

Coverage depends on the model you configure. Large hosted models (OpenAI, Claude, Gemini) handle dozens of languages well; smaller local models vary. For best results on a specific language, name it in a custom system prompt or add a few translated examples to your config.

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