Open source · Self-hosted · BSL 1.1 → Apache 2.0

Natural language.
Validated SQL.

NLQueries converts plain-English questions into SQL, validates it before it runs, and returns the answer. It also reads your documents and answers questions from both at once.

Star on GitHub Read the docs →
pip install nlqueries-core
nlqueries — zsh 
$ nlqueries connect postgres --host localhost --database mydb --user alice --alias prod

✓ Connection successful. Connector registered as 'postgres:localhost:mydb', alias 'prod'.

$ nlqueries process-history prod --days 30 --annotate && nlqueries export-kb prod

✓ Knowledge base written — 23 tables, 87 columns, 12 query capsules.

$ nlqueries query prod "how many orders placed last month by first-time customers?"

  ── Generated SQL ────────────────────────────────────────────
  SELECT COUNT(DISTINCT o.id)
  FROM   orders o
  JOIN   customers c ON o.customer_id = c.id
  WHERE  o.created_at >= date_trunc('month', now() - interval '1 month')
    AND  c.created_at >= date_trunc('month', now() - interval '1 month');
  ── Executed ──────────────────────────────────────────────────

→ 1,284

The difference

Different in the ways that matter.

Most text-to-SQL tools generate SQL and hope for the best. Here is what NLQueries does instead.

01

SQL is validated before it runs.

Use ask to generate and validate SQL without executing it, or query to run it directly. Either way, you always see the exact SQL that was produced.

02

The knowledge base learns from real queries.

NLQueries builds a YAML knowledge base from your actual query history, not just static schema introspection. It learns how your team refers to your data and which joins matter.

03

Documents and databases in one answer.

Ingest PDFs, Word docs, Excel sheets, Notion pages, or Confluence spaces alongside your database. Ask a question that spans both, and get one coherent answer.

04

It's a tool, not another chat UI.

NLQueries exposes a full MCP server. Point Claude Desktop, Cursor, or any MCP-compatible client at it and query your database from the assistant you already use.

Capabilities

What ships with Core.

Storage

Seven database connectors

PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, and DuckDB. Register once via nlqueries connect, then reference by alias.

Ingestion

Five document connectors

PDF, Word (.docx), Excel (.xlsx), Notion pages, and Confluence spaces. Documents and schema live in the same knowledge base.

Intelligence

Self-updating knowledge base

A YAML file that grows with real usage: schema, relationships, column descriptions, and common query patterns. Editable by hand or updated automatically.

Safety

Preview before you execute

nlqueries ask validates SQL without touching your database. nlqueries query executes it. You choose which one to run.

Performance

Semantic cache

Questions with cosine similarity of 0.97 or higher against a prior question skip the LLM and the database round-trip, typically answering in under 50ms.

Integration

MCP server

Exposes a full Model Context Protocol interface. Claude Desktop, Cursor, and any MCP-compatible client can query your database as a native tool call.

Observability

Coverage reporting

nlqueries kb-stats shows which tables and columns are well-represented in the knowledge base and which need enrichment.

Developer

CLI + Python library

nlqueries query "..." in the terminal. from nlqueries.orchestrator import MultiAgentOrchestrator in your code. Both first-class.

Get started

Three ways in.

Pick whichever fits your workflow. Full setup guide in the docs.

Full documentation →

Docker

Pulls the published image, no clone needed

RECOMMENDED 
$ curl -O https://raw.githubusercontent.com/nlqueries/nlqueries/main/docker-compose.yml
$ echo "ANTHROPIC_API_KEY=sk-..." > .env
$ docker compose up -d
$ docker exec -it nlqueries-core nlqueries health

pip

Python 3.11 or 3.12 · installs the CLI and library

$ pip install nlqueries-core
$ nlqueries connect postgres --host localhost --database mydb --user alice --alias dev
$ nlqueries process-history dev --annotate
$ nlqueries export-kb dev
$ nlqueries query dev "top 10 customers"

From source

For contributors and custom builds

$ git clone https://github.com/nlqueries/nlqueries.git
$ cd nlqueries
$ python -m venv .venv && source .venv/bin/activate
$ pip install -e ".[dev]"

License

BSL 1.1. Clear path
to Apache.

nlqueries-core is released under the Business Source License 1.1 (BSL 1.1). Here is exactly what that means:

BSL lets us develop the project sustainably while keeping the source fully readable and auditable from day one. Read the LICENSE file directly before relying on this summary for a production decision.

Read the full LICENSE → About BSL 1.1
✓

Source is public and readable now

You can read, audit, fork, and run the code for development and evaluation immediately.

✓

Production use is permitted, with one carve-out

You may run NLQueries in production. The one thing you can't do is offer it to third parties as a hosted or managed service. Individual and non-commercial self-hosted use is unrestricted.

→

Converts to Apache 2.0 on June 4, 2030

On the change date, or the fourth anniversary of a given version's release (whichever comes first), the license converts to Apache 2.0 automatically. No action required on your part.

Core vs. Enterprise

Core is a complete tool.

Enterprise adds team infrastructure on top of it, not features held back from Core.

Feature

Core

open source

Enterprise

proprietary

All 7 database connectors
✓
✓
Document connectors (5)
✓
✓
CLI + Python library
✓
✓
Self-updating knowledge base
✓
✓
SQL validation before execution
✓
✓
Semantic cache
✓
✓
MCP server
✓
✓
Coverage reporting
✓
✓

Enterprise only

Web UI
—
✓
Team auth / SSO
—
✓
Admin panel
—
✓
Audit logs
—
✓
Priority support
—
✓

Enterprise pricing on request. sales@nlqueries.com