Interface preview
╭─── sqlbuddy v1.0 · connected: school.db · 4 tables ───╮
❯ ask> show me all students in math class
# routing → AI Engine · schema-aware context
SELECT s.name, s.grade
FROM students s
JOIN classes c ON s.class_id = c.id
WHERE c.subject = 'math';
✓ 14 rows · 32ms · preview shown ↓
╰───────────────────────────────────────────────────────╯
The challenge
Most "chat with your database" tools assume you have a stable, high-speed connection to an LLM. In real-world environments like remote labs or offline offices, connectivity is often brittle. I wanted to build a tool that treated natural-language-to-SQL as a resilient capability, not a fragile one.
The goal: translate English to SQL with 100% reliability. Use sophisticated generative models when available, and a fast, local rule engine for everything else.
Core value
- Instant data access — removes the SQL syntax barrier for non-technical users and analysts.
- Hybrid intelligence — blends the flexibility of modern AI with the deterministic speed of regex-based rules.
- Resilience — offline fallback mode plus a tiered "waterfall" model system to handle API failures.
- Developer ergonomics — built-in preview mode to verify AI-generated queries before execution.
Architecture
SQLBuddy uses a three-layer pipeline: normalize input → route to engine → verify. The router intelligently assigns complex joins and ambiguous phrasing to the AI engine, while predictable patterns (like "list top 5 [thing]") are handled by the local rule engine.
# router.py logic (simplified)
def translate(query: str, schema: dict) -> Translation:
# fast path: local & offline-safe
if rule_engine.matches(query):
return rule_engine.build(query, schema)
# tiered fallback: cycle through multiple AI models
for model in AI_MODEL_TIERS:
try:
return ai_engine.translate(model, query, schema)
except (RateLimitError, ConnectionError):
continue
# last resort: rule-based best effort
return rule_engine.best_effort(query, schema)
→ Design principle
Never leave the user staring at an error. Always degrade to something useful.
Key features
- AI Mode — leverages state-of-the-art inference models for complex queries and natural phrasing.
- Rules Mode — a custom-built regex engine for lightning-fast, offline SQL generation.
- Tiered model logic — automatically cycles through multiple backup models to bypass rate limits.
- Schema-aware — dynamically reads database metadata to provide high-accuracy context to the translator.
Impact
~32ms
avg. cached query response
100%
query uptime via local fallback
Multi-tier
redundant AI model waterfall
Tech stack
Python
LLM orchestration
Multi-model AI engine
SQLite
Rich (CLI)
Regex / Pattern Matching
Dynamic Schema Parsing
What I learned
The biggest win wasn't the AI integration — it was the robustness of the rule engine. Building a regex fallback forced me to map the "80%" of queries users actually send. This made the AI prompts tighter, the system faster, and proved that "hybrid" is a feature, not a compromise.