Text To Sql Agent

Text-to-SQL Agent

Ask a database questions in plain English and get real answers back. You type something like *"which employee generated the most revenue?"* and the agent pokes around the schema, writes the SQL, sanity-checks it, runs it, and tells you what it found. It's built on LangChain's `create_agent` with Gemini (3.6 Flash by default) doing the thinking.

What it does

• Turns plain-English questions into working SQL
• Figures out the schema itself before writing anything
• Checks each query for syntax and safety, and rewrites it when the database complains — up to three tries by default, then it stops and reports the error instead of looping forever
• Handles the awkward stuff: JOINs, aggregations, subqueries
• Won't run anything destructive — no INSERT, UPDATE, DELETE, or DROP
• Traces every run in LangSmith if you've set that up
• Comes with a notebook that walks through the whole build

The database

I test against the [Chinook database](https://github.com/lerocha/chinook-database) — a fake digital music store with the usual artists, albums, tracks, customers, and invoices. Any SQLite file works, though; just point the connection string somewhere else.

Getting started

You'll need

• Python 3.11 or newer
• A Google AI Studio API key — grab one free at aistudio.google.com/apikey (no card needed)
• Optionally, a LangSmith key if you want tracing (sign up)

Setup

Clone it:

git clone https://github.com/axololtos/text-to-sql-agent.git
cd text-to-sql-agent

Pull down the Chinook database:

curl -L -o chinook.db https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite

Set up an environment and install. I use uv:

uv venv --python 3.11
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

Plain pip is fine too:

python3.11 -m venv .venv
source .venv/