Natural language to SQL for SQL Server

Connect SQL Server 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[mssql]"
$ nlqueries connect mssql --host my-server.database.windows.net --port 1433 --database mydb --user alice --alias sql-prod
$ nlqueries process-history sql-prod --annotate
$ nlqueries export-kb sql-prod
$ nlqueries query sql-prod "how many orders were placed last month by first-time customers?"

How NL2SQL works on SQL Server

Most text-to-SQL tools hand the LLM a schema dump and hope. NLQueries builds a YAML knowledge base from your SQL Server schema and from real query history, in this case sys.dm_exec_query_stats joined to sys.dm_exec_sql_text (needs VIEW SERVER STATE or VIEW DATABASE STATE), 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.

SQL Server-specific details

One connector covers on-premises SQL Server and Azure SQL, since the T-SQL dialect is identical. For Azure SQL with SQL authentication, pass the user as alice@my-server.

If the login lacks VIEW SERVER STATE or VIEW DATABASE STATE, process-history stops with an error that names the missing permission. Grant it, or build the knowledge base from the schema alone with export-kb. History is limited to plans compiled in the connected database.

Each query runs in a transaction that is never committed. T-SQL DDL is transactional, so a DROP is undone too. There is no per-query statement timeout: the timeout is applied as the driver's connection-wide query timeout.

The session is encrypted only when the connector's encryption setting is require. The default, request, leaves it unencrypted unless the server forces encryption. Set it by hand in the connector's entry in connectors.yaml; connect has no flag for it.

Full connector notes are in the connectors guide, and the read-only role to create is in database hardening. This connector covers Microsoft SQL Server and Azure SQL Database.

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.