Natural language to SQL for PostgreSQL

Connect Postgres and ask your first question

Install the package, register the connection once, build the knowledge base, and query. Leave out --password and it is prompted for without echoing, then stored in your OS keychain rather than the connectors file. Only where no keychain is available does it go into the stored connection URL, with a warning.

$ pip install nlqueries-core
$ nlqueries connect postgres --host db.example.com --port 5432 --database prod --user alice --alias prod
$ nlqueries process-history prod --annotate
$ nlqueries export-kb prod
$ nlqueries query prod "how many orders were placed last month by first-time customers?"

How NL2SQL works on Postgres

Most text-to-SQL tools hand the LLM a schema dump and hope. NLQueries builds a YAML knowledge base from your Postgres schema and from real query history, in this case the pg_stat_statements extension, so it learns which joins your team actually uses and what your columns mean. That knowledge base is what the model sees when it writes SQL.

Every generated statement is parsed with sqlglot and refused unless it is a single read-only query, and its columns are checked against the schema in the knowledge base. It then runs read-only where the engine allows it, with a statement timeout; what each connector enforces has the details per engine. Use nlqueries ask to see the SQL without running it, or nlqueries query to run it. A semantic cache answers repeated questions without another LLM call, and runs the stored SQL again so the rows are current.

Postgres-specific details

Query-history capture needs pg_stat_statements. Managed PostgreSQL (AWS RDS, Google Cloud SQL, Supabase, Neon, Azure Database for PostgreSQL) pre-loads the library, so CREATE EXTENSION IF NOT EXISTS pg_stat_statements; is the only step. Self-hosted servers need shared_preload_libraries = 'pg_stat_statements' in postgresql.conf and a restart. Without the extension, process-history stops and says so; export-kb still builds the knowledge base from the schema.

Only this database's SELECT and WITH statements are read. A login that is neither a superuser nor a member of pg_read_all_stats sees only its own statements; GRANT pg_read_all_stats to include everyone's. pg_stat_statements keeps no per-query timestamps, so --days has no effect here.

Column and table comments from pg_description are pulled straight into the knowledge base, so documenting your schema in Postgres directly improves the SQL that gets generated.

TLS is required by default (ssl_mode require), so a server that offers no TLS is refused. connect has no TLS flags: certificate settings such as ssl_ca_cert are added by hand to the connector's entry in connectors.yaml, and a CA certificate with no explicit mode selects verify-full. See transport security.

Full connector notes are in the connectors guide, and the read-only role to create is in database hardening. This connector covers Postgres, AWS RDS for PostgreSQL, Supabase, Neon, Cloud SQL and Azure Database for PostgreSQL.

Use it from Claude, Cursor or any MCP client

Run nlqueries mcp-server start and point Claude Desktop, Cursor, or any Model Context Protocol client at it. Its query tool generates SQL through the same pipeline, runs it read-only and returns the rows. Over stdio, the transport desktop clients use, there is nothing to configure. A network transport will not start without authentication, by OIDC or a pre-shared token, and grants per agent and action decide who may run SQL. See MCP authentication.