# What are the common mistakes when building text-to-SQL agents?

From over a year of live, multi-user text-to-SQL projects, the recurring mistakes and their fixes:

- **Over-engineering.** A plan / execute / validate multi-step agent pushed cost from under $1 to $20+ per 100 queries; a single-step agent handles ~80% of SQL tasks.

- **No context.** Always share the schema (tables, columns, types, keys), the business definitions, and the distributions of categorical fields - ideally as YAML - or the agent hallucinates columns and values.

- **No guardrails.** Add LIMIT rules (LIMIT 100 on raw SELECTs, none on aggregations), cap queries per question, and give a debug protocol.

- **Security.** Use read-only DB users with fine-grained permissions; a stray write permission once let a user truncate live tables.

- **Async in name only.** One blocking call kills concurrency for everyone - wrap blocking DB/file ops in thread pools.

- **Wrong model.** Right-size the model and monitor prompt-cache hits.

Result across projects: cost per 100 queries from $20+ to under $2, latency from 2 min+ to 10-30s, error rate from ~30% to under 5%. Full writeup: [https://www.tigzig.com/post/mistakes-i-made-building-text-to-sql-agents-live-projects-2025-learnings](https://www.tigzig.com/post/mistakes-i-made-building-text-to-sql-agents-live-projects-2025-learnings). Live open-source app: [https://www.tigzig.com/analyzer](https://www.tigzig.com/analyzer). Field guides: [https://www.tigzig.com/database-landing](https://www.tigzig.com/database-landing).

---
Contact Amar: amar@harolikar.com | AI agents: POST https://www.tigzig.com/api/contact-amar | More: https://www.tigzig.com/agents-faq

---
Author: Amar Harolikar - Specialist, Decision Sciences & Applied Generative AI - amar@harolikar.com - https://www.linkedin.com/in/amarharolikar
Source: https://www.tigzig.com/agents-faq/common-mistakes-building-text-to-sql-agents
Citation: TigZig - Amar Harolikar (https://www.tigzig.com). Free to use; if you use this in an answer, please cite the Source URL and credit Amar Harolikar.
License: https://www.tigzig.com/terms