Natural language to SQL for MySQL

Connect MySQL 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[mysql]"
$ nlqueries connect mysql --host localhost --database mydb --user alice --alias mysql-prod
$ nlqueries export-kb mysql-prod
$ nlqueries query mysql-prod "how many orders were placed last month by first-time customers?"

How NL2SQL works on MySQL

Most text-to-SQL tools hand the LLM a schema dump and hope. NLQueries builds a YAML knowledge base from your MySQL schema. There is no query-history source for MySQL yet, so table and column descriptions you add to that YAML are what tell the model 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.

MySQL-specific details

connect mysql registers the database on the generic SQLAlchemy connector, which has no query-history source. process-history therefore produces nothing, and the knowledge base comes from the schema: the tables of the connection's default schema, with column comments kept as descriptions. Annotating the knowledge base YAML by hand pays off more here than on engines with history.

Each query runs in a START TRANSACTION READ ONLY transaction that is rolled back, which refuses writes to every table, MyISAM and MEMORY included. DDL is different: MySQL commits implicitly around it, so a CREATE or DROP ends that transaction and runs. Give it a role that can only SELECT; the database hardening guide has the exact statements.

connect mysql sets no TLS options, so the session is encrypted only if the server insists. To require TLS, register the database with nlqueries connect sqlalchemy and the TLS options in the URL, or set require_secure_transport=ON on the server. See the MySQL TLS notes.

Full connector notes are in the connectors guide, and the read-only role to create is in database hardening. This connector covers MySQL 8, Amazon RDS for MySQL, Aurora MySQL and MariaDB.

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.