KaizenSQL

Inspiration

I often see AI tools that immediately rewrite SQL queries, acting as a black box that bypasses critical thinking. I wanted to build a tool that doesn't just "fix" code, but helps me understand database optimization principles deeply. For me, the true value of this project wasn't just getting to a finished binary, but enjoying the process of engineering a clean solution from scratch. Inspired by the Japanese philosophy of continuous improvement (Kaizen), I created KaizenSQL (kzql) to bridge AI inference with Socratic mentorship, delivering an ultra-fast, minimalist CLI that acts as a senior database mentor right in the terminal.

What it does

KaizenSQL is a lightweight, zero-dependency AI CLI I built in Go for SQL query analysis, performance profiling, and security review. Instead of returning raw rewritten queries, its primary Mentor Mode uses a Socratic approach to highlight performance bottlenecks (such as non-SARGable predicates, implicit type conversions, and missing index patterns) and guide developers toward understanding why a query is inefficient. It features an interactive TUI file picker, smooth ASCII branding, and standard Unix exit behaviors.

How I built it

• Language & TUI: I chose Go to keep execution instantaneous and the binary footprint minimal. I crafted the interactive file picker, terminal layout, and ASCII branding using the Charm ecosystem (bubbletea, bubbles, lipgloss).
• Inference Pipeline: I integrated Groq’s high-throughput API to run open-weight models (Qwen/Llama) with zero third-party SDK bloat.

Challenges I ran into

• Strict OTPM Rate Limits (HTTP 429): Working within free-tier API constraints, I ran into instant 429 rate limit errors. I discovered that the root cause wasn't input volume (TPM), but the default SDK reservation for Output Tokens Per Minute (OTPM). I solved this by enforcing explicit MaxTokens caps at the request level.
• CLI UX Synchronization: Implementing an animated ASCII banner without locking the terminal required managing custom tick cycles (tea.Tick) and state machines in Bubble Tea before gracefully transitioning into the file selection model.

Accomplishments that I'm proud of

• Embracing the Process: Turning every friction point—from rate limits to state management—into a deliberate learning experience rather than rushing to a quick fix.
• Zero-Dependency Core: Building a fully self-contained Go binary with embedded rule sets that runs out-of-the-box on Linux and macOS without needing external asset directories.
• Token Efficiency: Reducing System Prompt token footprint by up to 80% through dynamic heuristic injection.
• Craftsmanship-Driven DX: Creating an intuitive "first contact" experience with smooth keyboard navigation, clear error output on os.Stderr, and standard Unix exit codes.

What I learned

• The Joy of Craftsmanship: Focusing on the journey of building taught me that wrestling with low-level details—like state machines or SDK behaviors—is where real growth happens as a software craftsman.
• API Constraints Drive Architecture: Understanding the subtle distinction between input TPM and output OTPM was essential for designing low-latency, free-tier-friendly LLM tools.
• State Machines in TUIs: Mastering the Elm architecture (Model-Update-View) through bubbletea showed me how to orchestrate terminal animations, keypresses, and program exits deterministically.

What's next for KaizenSQL

• AST SQL Parser: Adding a true SQL AST parser (such as pingcap/parser) for deeper structural analysis.
• Custom Local Rules (.kzqlrules): Allowing developers to define custom project-level Markdown rules for specific database standards.
• Documenting the Journey: Writing in-depth technical write-ups on Dev.to and sharing tactical posts on LinkedIn to break down everything I learned while building this project.

Built With

• ai
• cli
• go