HumanQL

Complete HumanQL Guide

Everything you need to know for effective usage

Quick Start

Get your connection string

The connection string looks like this:

postgresql://user:password@host:5432/database

Find it in your hosting dashboard (Supabase, Neon, Railway, etc.)

Connect

Paste the string and click Connect. We'll fetch your database schema.

Ask a question

Write what you want to know in plain language. AI will generate SQL.

Query Examples

From simple to complex

Basic

"Show all users"

SELECT * FROM users LIMIT 100

"How many orders?"

SELECT COUNT(*) FROM orders

"Last 10 products"

SELECT * FROM products ORDER BY created_at DESC LIMIT 10

Filtering

"Active users"

SELECT * FROM users WHERE is_active = true

"Orders over 1000"

SELECT * FROM orders WHERE total > 1000

"Users with gmail"

SELECT * FROM users WHERE email ILIKE '%@gmail.com'

JOIN queries

"Orders with customer names"

SELECT o.*, u.name FROM orders o JOIN users u ON o.user_id = u.id

"Products never ordered"

SELECT p.* FROM products p LEFT JOIN order_items oi ON p.id = oi.product_id WHERE oi.id IS NULL

Aggregation

"Sales by month"

SELECT DATE_TRUNC('month', created_at) as month, SUM(total) FROM orders GROUP BY month

"Average order by status"

SELECT status, AVG(total) FROM orders GROUP BY status

"Top 5 customers"

SELECT user_id, SUM(total) as spent FROM orders GROUP BY user_id ORDER BY spent DESC LIMIT 5

Dates

"Orders from last week"

SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '7 days'

"Registrations this month"

SELECT * FROM users WHERE created_at >= DATE_TRUNC('month', CURRENT_DATE)

Security

Read-only by default

Only SELECT queries allowed. INSERT, UPDATE, DELETE are blocked.

SQL validation

Every query is validated before execution. DROP, TRUNCATE, ALTER are impossible.

Privacy Mode

Enable to prevent data from being sent to AI for summary generation.

Schema anonymization

Enable so AI sees table_1, col_1 instead of real names.

Self-hosted mode

Deploy with Ollama — data never leaves your server.

Tips

Be specific

Instead of "show data" write "show user names and emails"

Use table names

AI works better when you mention actual names from the schema

Specify limits

"Top 10 by sales" is better than just "who sold the most"

Include time periods

"last month" or "in 2024" helps AI write the correct filter

Connection Formats

PostgreSQL

postgresql://user:password@host:5432/database

SupabaseNeonRailwayRenderHeroku

MySQL

mysql://user:password@host:3306/database

PlanetScaleAWS RDSDigitalOcean

We recommend creating a read-only user for maximum security.

Self-hosted Mode

For maximum privacy, deploy everything locally:

$git clone https://github.com/manikosto/no-sql

$cd no-sql

$docker-compose up

Ollama will download the model (~4GB) on first run. After that, all queries are processed locally.

Ready to start?

Open HumanQL