Build a LangChain SQL Agent for Natural Language Queries on MySQL

Company data tends to sit behind a technical wall. Getting anything out of it has meant writing SQL or learning a rigid point-and-click tool. A natural language interface removes that middle layer, so the person making the decision can ask the question directly and intent, not technical skill, drives the analysis. A SQL agent built on LangChain is one practical way to get there. Below you'll find what the agent does, how to set up the environment and a MySQL test database, how to wire up the executor, and which safeguards you need before it touches anything real.

How data access got easier

Each generation of tooling hid more of the underlying complexity:

1. Command-line clients demanded exact syntax and a solid grasp of relational algebra.
2. Visual query builders helped, but you still had to understand joins and table relationships.
3. Dashboards were easy to read yet stuck with whatever views someone had built in advance.
4. Natural language interfaces interpret meaning, so nobody needs to know the schema or a query language.

An AI SQL agent brings several concrete advantages:

• It reads the schema on its own and finds the relevant tables, primary and foreign keys, and join paths.
• It maps plain wording to database entities, then writes and runs complex queries with nobody stepping in.
• It fetches the schema only for tables that matter, which cuts token use and cost while helping performance.
• It turns vague questions such as "How were sales last month?" into deterministic SQL by inferring context and matching entities.

That only works reliably with the right plumbing around it, namely an orchestration framework and an isolated environment.

What a LangChain SQL agent consists of

A language model talking to a structured database needs middleware, and LangChain supplies the connective tissue: reasoning, tool choice and execution cycles that turn a prompt into a safe database operation. Its agents differ by reasoning style and which models they support.

At the center is the ReAct loop, short for reasoning plus acting:

1. Select: the agent reads the prompt and chooses a tool, such as a SQL executor.
2. Act: it runs that tool, for example by executing the generated query.
3. Review: it checks the output and decides whether that's enough or another pass is needed.
4. Repeat: the cycle continues until it has a final, validated answer.

You'll also choose between two designs. A one-shot system handles each question on its own, with lower latency and easier optimization. A conversational one tracks state and manages dialogue, so people can refine a search through follow-up questions and settle ambiguity over several turns, a kind of dialogue with the data.

Environment and dependencies

For anything headed toward production, isolate the environment and pin versions, so a library update can't quietly break the pipeline. Create and activate a virtual environment:

pip install virtualenv
virtualenv my_env
source my_env/bin/activate

Then install this stack at exactly these versions:

• ibm-watsonx-ai==1.0.4 handles foundation model inference.
• ibm-watson-machine-learning==1.0.357 brings in the enterprise LLM models.
• langchain==0.2.1 is the core orchestration framework for the agent logic.
• langchain-ibm==0.1.7 supplies wrappers specific to the IBM ecosystem.
• langchain-experimental==0.0.59 contains extra agent utilities.
• mysql-connector-python==8.4.0 is the database driver.

The database the agent queries

An agent is only as accurate as its database. It relies on table names, column descriptions and key relationships to connect a question with the data, so the schema has to be clean.

Chinook makes a good test bed because it models a whole digital media business:

• It has 11 tables, including Artist, Album, Invoice and Track.
• Primary and foreign keys let the agent move through multi-table joins.
• It holds more than 15,000 records, enough to check trend analysis and complex retrieval.

The agent connects through a URI, which has to follow this pattern exactly:

mysql+mysqlconnector://{mysql_username}:{mysql_password}@{mysql_host}:{mysql_port}/{database_name}

Five values are required: username, password, host, port (3306 by default) and database name, here Chinook.

Before any LLM gets involved, confirm the connection and schema from the MySQL CLI:

-- Verify database existence
SHOW DATABASES;
USE Chinook;

-- Confirm data integrity: This should return exactly 347
SELECT COUNT(*) FROM Album;

The album count should come back as exactly 347. A verified database gives the model a sound base and lowers the odds of grounding errors.

Building the agent executor

Next you wrap the model and attach it to a database executor, which determines how the agent sees and works with your data.

Tune the model parameters for determinism. With SQL generation, unpredictable output leads straight to invented syntax, so keep things stable.

The agent comes from the create_sql_agent factory, with ibm/granite-4-h-small as the reasoning engine. It needs these arguments:

• llm takes the Granite model, wrapped in a WatsonxLLM instance.
• db takes your SQLDatabase connection.
• verbose=True lets you watch what it's doing.
• agent_type, set to ZERO_SHOT_REACT_DESCRIPTION for ordinary analytical questions.

Treat verbose=True as more than a debugging switch. In a business setting it's what makes auditing possible. You can inspect the chain of thought, and check that the generated SQL and reasoning steps match internal data logic and compliance standards, before an answer reaches anyone.

Error recovery and safeguards

Ambiguous language and schema mapping will trip up even strong models, so a production setup needs automatic safeguards plus human oversight.

One real strength of this agent is self-correction. When a generated query fails, it:

1. Captures the traceback from the database engine.
2. Works out what went wrong, such as a syntax error or a misspelled column.
3. Retries with a corrected statement, which raises the success rate on complicated queries.

Four practices protect company data:

1. Sandbox every agent-driven query in an isolated environment so nothing gets modified by accident.
2. Keep a human in the loop, with an expert reviewing findings used in high-stakes reports.
3. Refine prompts continuously to cover wording variations and domain-specific quirks.
4. Give the database connector a restricted user profile with strict row-level security and privacy boundaries.

Where this leaves you

Moving from raw SQL to natural language queries opens data up to far more people. Pair a precise model like ibm/granite-4-h-small with LangChain's structured orchestration and you narrow the gap between plain language and usable insight. A system you can trust in production still comes from continuous testing and firm governance.