QueryCraft

The review-first paradigm

Natural-language-to-SQL interfaces often conflate generation with execution. This collapse of trust boundaries creates significant risk: models hallucinate, misinterpret dialects, or generate unsafe statements that execute without oversight. QueryCraft was built to decouple these actions, establishing a rigid review boundary where AI acts as a drafter, not an authority.

Architectural evolution

QueryCraft evolved from a fragmented three-repository prototype that suffered from contract drift and incomplete security models. The second-generation implementation was a unified, full-stack Next.js application. This consolidation enabled strict type safety across the entire request lifecycle and eliminated the need for complex inter-service communication.

Engineering decisions focused on defense-in-depth. Schema-aware retrieval used immutable, hashed snapshots to ground generation in relevant context while minimizing token consumption. Execution security relied on AST-based parsing that rejected non-read operations, supplemented by database-native read-only user accounts.

Engineering lessons

• Streaming structured output requires local validation before persistence; mid-stream failures should not be retried to avoid partial or duplicated artifacts.
• Dialect-specific behavior must be isolated into provider adapters to prevent driver leaks into core application logic.
• Separating metadata introspection from execution providers preserves the security boundary necessary for safe read-only operations.

QueryCraft has been retired and is preserved as an engineering reference. Its lasting value lies in the patterns established for safe AI integration, specifically the use of independent validation layers and the commitment to keeping generated code as an editable, user-controlled artifact.

QueryCraft: A review-first SQL workbench

QueryCraft is a retired HubZero Build designed as an AI-assisted SQL workbench. It enables users to connect PostgreSQL, MySQL, or SQLite databases, introspect their schemas, and generate SQL queries via natural language. The core engineering philosophy mandates that generated SQL never executes automatically, enforcing a strict review-first workflow.

Architectural evolution

The project originated as a three-repository prototype that suffered from contract drift and fragmented authentication. The second generation, preserved here as v1.0.0, consolidated the system into a single, typed Next.js App Router application. This migration eliminated redundant services and established a unified full-stack codebase.

Core technical decisions

• Schema-grounded generation: The system selects relevant tables using deterministic scoring and one-hop foreign-key relations to optimize token usage.
• Separated execution: Query execution is decoupled from AI generation. SQL is parsed into an AST for policy enforcement before being run in a read-only database-native boundary.
• Transient results: Result rows are never persisted. They are streamed directly to the browser, ensuring the application store remains focused on metadata and audit records.
• Encrypted persistence: Database credentials are stored as AES-256-GCM encrypted envelopes within MongoDB, preventing raw credential exposure.

Engineering challenges

A primary challenge was preventing AI from becoming an authoritative actor. We addressed this through layered controls: local Zod validation of structured outputs, an AST-based policy engine, and explicit user confirmation. Additionally, supporting multiple dialects (PostgreSQL, MySQL, SQLite) required creating separate adapter families for metadata introspection and query execution to avoid leaking driver-specific behavior into the shared application logic.