Ramin Mousavi
Show HN: Building a SQL analyst agent from scratch
Last verified:
What is Ramin Mousavi?
Ramin Mousavi project is a small AI agent that answers plain-English questions about a SQL database by checking the schema, writing SQL, running it, and explaining the result in normal language. It is designed to avoid guessing table or column names by inspecting the database step by step before answering.
The implementation is built with Node.js, the Vercel AI SDK, and OpenAI, with gpt-4.1-mini handling the language and tool-selection side of the workflow. The demo database is Chinook, and the article uses SQLite plus better-sqlite3 to keep the setup simple and serverless for a local project.
A core feature is the tool-based agent loop. The agent uses three tools only: listTables, describeTable, and runSql, which pushes it into a safer workflow of exploring first and querying second.
The project is aimed at developers learning how to build useful AI agents, especially people interested in text-to-SQL systems, data assistants, and small practical agent demos. It is also useful for anyone who wants a compact example of schema-aware query generation that can be extended into larger analytics or reporting tools.
Ramin Mousavi pricing
Pricing model: Freemium
The article does not present a paid product or subscription pricing model. It describes a local demo built with open tooling and a downloadable example, with the model choice (gpt-4.1-mini) described as cheap and fast. The post mentions a free live demo and a GitHub download of the full example, but it does not list free tiers, paid plans, usage limits, or bundle pricing.
Ramin Mousavi pros
- Plain-English questions supported
- Checks schema before querying
- Uses only read-only SQL
- Reduces hallucinated table names
- Reduces wrong column names
- Can recover from query mistakes
- Explains results in normal language
- Uses a small, understandable tool set
- Simple main agent loop
- Built with Node.js
- Uses Vercel AI SDK tool calling
- Uses OpenAI for language handling
- Fast and cheap model choice
- Works with a sample Chinook database
- SQLite demo is serverless
- Uses better-sqlite3 for simple local access
- Includes a live demo
- Includes a downloadable full example
- Suitable for learning agent design patterns
- Easy to extend with more queries or datasets
Ramin Mousavi cons
- Limited to the Chinook sample dataset in the article
- Only supports SELECT queries
- No write or update actions
- Small scope by design
- No multi-database support shown
- No query safety checks beyond read-only behavior
- No streaming UI steps described
- No chart or report generation in the current demo
- Requires local setup and seeding
- Not a full production analytics platform
Frequently asked questions about Ramin Mousavi
What does the SQL analyst agent do?
It takes a plain-English question, inspects the database schema, writes a SQL query, runs that query, and then explains the result in normal language. The key idea is that it does not guess blindly; it first looks at the actual database structure and only then answers from real query output.
Why use an agent instead of a one-shot prompt?
The article says agents are better for this task because they can inspect the schema step by step, recover from mistakes, and build answers from actual data. That makes the workflow more reliable than asking a model to guess the SQL in one shot.
What tools does the agent use?
The agent uses exactly three tools: listTables to discover available tables, describeTable to inspect columns and relationships, and runSql to execute the final read-only query. The split is intentional so the model explores first and writes SQL second.
What database does the demo use?
The article uses the Chinook sample database, which is a common dataset for SQL demos and tutorials. For the actual seed database in the example, it uses SQLite because it is embedded, serverless, and easy to run locally.
What technologies power the agent?
The project is built with Node.js, the Vercel AI SDK, and OpenAI. The article specifically says it uses gpt-4.1-mini for the model and better-sqlite3 for SQLite access.
Why is the agent considered safer than a free-form SQL generator?
Because the system prompt tells it to inspect the schema first and only run SELECT queries. That workflow helps reduce hallucinated table names, incorrect columns, and broken queries, while keeping execution read-only.
Can the agent retry after a bad query?
Yes. The article says the model can inspect the schema, choose tools, retry if a query fails, and stop once it has enough information to answer properly. That retry loop is part of the value of the agent design.
Is the example meant to be production-ready?
No, it is intentionally small and educational. The article frames it as a realistic starting point that demonstrates the core agent pattern, with ideas for future improvements like query safety checks, more databases, streaming UI steps, or chart generation.
What can you download from the project?
The post says you can download the complete example from GitHub. That version includes the seed data, tool definitions, system prompt, and the small UI used in the article so you can run and extend it locally.
Who is this project for?
It is aimed at developers learning how to build AI agents, especially people interested in text-to-SQL systems, data assistants, and practical agent demos. It is also useful for anyone who wants a compact example of schema-aware query generation that can be extended into larger analytics tools.