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

Open source natural language to SQL.
Validated before it runs.

NLQueries is a self-hosted NL2SQL engine. It converts plain-English questions into SQL, checks that SQL against your real schema 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 — 12 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 and NL-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

Database connectors

Eight dedicated connectors: PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, DuckDB, and SQLite, plus a generic SQLAlchemy connector for MariaDB, Oracle, and any other SQL database from a connection URL. 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 to 3.14 · 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

Database connectors (8 dedicated + generic SQLAlchemy)
✓
✓
Document connectors (5)
✓
✓
CLI + Python library
✓
✓
Self-updating knowledge base
✓
✓
dbt import
✓
✓
SQL validation and read-only policy
✓
✓
Hybrid SQL + document answers
✓
✓
Conversational follow-ups
✓
✓
Semantic cache
✓
✓
MCP server with OIDC authentication
✓
✓
Coverage reporting and eval regression gate
✓
✓
OpenTelemetry tracing
✓
✓

Enterprise only

Web UI: chat, agent dashboards, knowledge base editor
—
✓
Nexus Semantic Fabric and Copilot
—
✓
SQL Console
—
✓
Table-scoped agents and row-level filters
—
✓
Pinboards and scheduled chats
—
✓
SSO (SAML), SCIM, MFA and API keys
—
✓
Admin panel and organisation settings
—
✓
Audit log UI and retention policies
—
✓
LLM cost tracking, quotas and billing
—
✓
Embedded / white-label analytics and theming
—
✓
REST API and webhooks
—
✓
Signed releases, installer and support bundles
—
✓
Priority support
—
✓

Enterprise pricing on request. [email protected]

FAQ

Natural language to SQL, answered.

What is NLQueries?

NLQueries is an open source, self-hosted natural language to SQL (NL2SQL) engine. It converts plain-English questions into SQL, validates that SQL against your real database schema before it runs, executes it read-only, and returns the answer. It runs as a CLI, a Python library, and an MCP server.

Is NLQueries a text-to-SQL or NL2SQL tool?

Yes. Natural language to SQL, NL2SQL, NL-to-SQL and text-to-SQL all describe the same task, and NLQueries does it with one difference from most tools: generated SQL is parsed and checked column-by-column against the live schema with sqlglot before anything executes, and you can preview the SQL with nlqueries ask without touching the database.

Which databases does NLQueries support?

Dedicated connectors for PostgreSQL, MySQL, Snowflake, BigQuery, Amazon Redshift, SQL Server and Azure SQL, DuckDB, and SQLite, plus a generic SQLAlchemy connector for MariaDB, Oracle and any other database reachable by connection URL.

How is NLQueries different from Vanna, nl2sql-studio or a ChatGPT prompt?

Three things. It builds its knowledge base from your real query history, not just a schema dump, so it learns the joins and naming your team actually uses. It validates SQL against the live schema and runs it read-only with a timeout. And it exposes everything as an MCP server, so Claude Desktop, Cursor and other assistants can query your database as a native tool instead of you pasting SQL between windows.

Can I use NLQueries with Claude Desktop or Cursor?

Yes. Run nlqueries mcp-server and point any Model Context Protocol client at it. The assistant gets validated SQL results as tool calls, with OIDC authentication and per-tool authorization available for network transports.

Is NLQueries free and open source?

The core is free to use and its source is public on GitHub under the Business Source License 1.1, which permits production and self-hosted use but not offering it as a hosted service to third parties. Every version converts to Apache 2.0 four years after release, and the whole project converts on June 4, 2030. Enterprise adds a web UI, SSO, admin and audit tooling on top of the same core.

Does NLQueries send my data to an LLM?

The question and the relevant slice of the knowledge base (schema, column descriptions, example queries) are sent to the LLM you configure so it can write SQL. Query results are returned to you from your database directly. It is self-hosted, so you choose the model provider and what leaves your network.

Per-database setup for PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server, DuckDB and SQLite.