SQL Query Bench

SQL Query Bench turns plain English into safe, executable SQL with OpenAI Codex. Connect any database, add business context, and watch grounded answers and query progress stream live.

Comment

SQL Query Bench

Inspiration

Databases contain valuable answers, but accessing them still requires knowledge of schemas, relationships, SQL syntax, and database-specific conventions. General-purpose AI assistants can generate SQL, but they may guess table names, overlook business rules, or return a query without checking it against the real database.

We built SQL Query Bench to make database exploration conversational, grounded, and transparent. A user can connect a database, sign in securely with their OpenAI account, ask a question in plain English, and watch OpenAI Codex discover the schema, select tools, generate SQL, execute the query, and return the result.

Our goal was simple: let anyone ask questions of their database without hiding how the answer was produced.

What it does

SQL Query Bench is an AI-powered workspace for querying databases with natural language.

Users can:

  • Sign in with OpenAI through Codex OAuth—no API key entry required.
  • Configure and connect their own database.
  • Ask questions such as “Show me the devices with the most alarms.”
  • Discover tables, columns, and relationships from the live schema.
  • Generate, validate, and execute read-only SQL through controlled tools.
  • Watch the agent's progress live through Server-Sent Events.
  • Inspect generated SQL, tool activity, results, response time, and token usage.
  • Upload database-specific context files containing schema notes, business rules, metric definitions, example SQL, or data dictionaries.
  • Maintain separate conversations with persistent chat history.
  • Explore the schema and review query analytics in the same interface.
  • Select from the OpenAI Codex models available to their account.

How we built it

The frontend is an Angular and TypeScript application. It provides the Codex chat experience, database configuration, schema explorer, context-file manager, query results, analytics, model selection, dark mode, and conversation history.

The backend is built with Python and FastAPI. It manages:

  • OpenAI Codex OAuth device authorization
  • Dynamic Codex model discovery
  • Agent conversation state
  • Database connection management
  • Live schema introspection
  • Read-only SQL validation and execution
  • Database context-file ingestion
  • Query logging and analytics
  • Real-time SSE progress delivery

The agent uses an MCP-style tool architecture. Instead of asking the model to guess the schema or answer from memory, SQL Query Bench provides focused tools for:

  1. Discovering available tables
  2. Searching columns
  3. Inspecting relationships
  4. Generating SQL
  5. Validating SQL
  6. Executing read-only queries
  7. Returning structured results

Uploaded context files are scoped to the connected database and automatically included in future Codex turns. This gives the model organization-specific knowledge while keeping the live schema and actual query results authoritative.

The streaming pipeline sends progress events throughout the agent run:

thinking
tool_start
tool_result
done
error

This allows users to see the agent search, reason, and use database tools instead of waiting for an unexplained final response.

Challenges we faced

Grounding generated SQL

The first major challenge was making generated SQL dependable across databases with unfamiliar naming conventions. We addressed this by grounding Codex in the connected database's live schema and supplementing it with user-provided business context.

Delivering real-time progress

Network chunks do not always align with complete SSE events, and response compression can accidentally buffer a stream. We implemented a persistent SSE parser, multiline event handling, explicit proxy-buffering controls, and a compression bypass for text/event-stream responses.

Authentication without API keys

We wanted users to connect their OpenAI account without copying API keys into the application. We integrated OpenAI Codex OAuth, protected persisted credentials, dynamically discovered account models, and created a straightforward sign-in and sign-out experience.

Safe database access

An AI database assistant must not execute destructive operations. We designed the query workflow around read-only SQL, validation, controlled tool calls, scoped database sessions, and limited result payloads.

We also worked through challenges involving conversation persistence, large result sets, database-specific context isolation, responsive progress updates, and consistent light and dark themes.

What we learned

We learned that a successful text-to-SQL product needs more than a capable model. Schema discovery, context management, tool design, validation, streaming, and result presentation are equally important.

We also learned that transparency changes the experience. Showing each tool as it runs makes longer database tasks easier to understand and gives users confidence that answers come from real database operations.

Finally, user-provided context makes the product adaptable. The same application can support very different databases without hardcoding organization-specific knowledge into the source code.

Accomplishments that we're proud of

  • Implementing OpenAI Codex OAuth without requiring user-supplied API keys
  • Dynamically displaying the Codex models available to the authenticated account
  • Building a complete tool-using SQL agent rather than a one-shot prompt
  • Streaming reasoning status and tool progress in real time
  • Grounding answers in both the live schema and database-specific context files
  • Keeping SQL execution read-only and observable
  • Combining chat, schema exploration, context management, and analytics in one workspace

What's next for SQL Query Bench

Next, we plan to:

  • Support additional database engines
  • Add reusable database-context templates
  • Improve automatic relationship discovery
  • Generate charts directly from natural-language requests
  • Support shared context for teams
  • Expand governance, audit, and access-control capabilities
  • Package the project for simple hosted deployment

SQL Query Bench demonstrates how OpenAI Codex can become more than a code generator: it can operate as a transparent, tool-using data assistant grounded in each user's real database.

Built With

Share this project:

Updates