An AI agent that operates your database

Every growing organization runs into the same wall. The database holds the answers — revenue by channel, why a report went slow, which index stopped being used — but extracting them requires someone who can read an execution plan and write correct SQL against a schema with hundreds of tables. There are never enough of those people.

So the expensive failure mode takes over. An engineer is pulled off the roadmap to answer a data question. A slow query degrades quietly until it becomes a 2 a.m. incident. A decision waits a week because the one person who could write the query was busy. The cost isn't only the DBA you didn't hire — it's the roadmap that didn't ship and the incident caught late.

DeepSQL began as an internal tool against a production workload of 13,000+ hotels, where exactly this toil was becoming the bottleneck. It is built to convert "wait for the one person who can" into "ask, and get a governed answer now" — for analysts and engineers alike — without moving a single row off your infrastructure.

DeepSQL is a control plane that sits between the surfaces people work in and the databases they ask about. Everything that holds state — the runtime, the vault, the brain — lives inside a single self-hosted boundary. The model is the only external dependency, and it receives schema and prompts, never rows in bulk or credentials.

Figure 1. The control plane, vault, cache, and vector store run inside one self-hosted boundary. DeepSQL connects out to your databases under role-based access, and calls the model provider you bring with schema and prompts — never bulk rows or credentials.

The planes, briefly

• Surfaces — a web UI; MCP / CLI, which exposes the database as a governed tool to the DeepSQL agent client and to AI coding assistants like Claude, Cursor, and Codex; and a Slack bot. Same engine underneath; different doors.
• Backend — the Spring Boot control plane: connection management with encrypted credentials and SSH-aware tunneling, the provider registry, role-based access control, and the policy guards that everything routes through — read-only by default, admin writes explicitly confirmed.
• DeepSQL Agent — a customized Hermes coding-agent runtime that powers chat, Slack, the CLI, and dashboard generation. It reasons with a small, governed tool surface rather than raw database access.
• The Brain — the retrieval layer that makes grounding possible: an initialization pipeline that learns the schema and a cache that serves the relevant slice on every question.

A statistics engine can tell you a query is slow. It cannot tell you which of 540 tables holds the booking date, or that "active" means a status column two joins away. Answering real questions requires the schema, the relationships, and the rules to be understood first. DeepSQL learns them once, incrementally, in a staged pipeline — then retrieves only what each question needs.

1. Schema scan — enumerate tables, columns, types, and declared keys through the provider for the target engine.
2. Data sampling & key-column analysis — profile distributions, null rates, and cardinality to find the columns that actually matter.
3. Inferred relationships — recover join paths the schema never declared — the foreign keys that live only in application code.
4. Classification & AI description — detect the schema's shape (star, snowflake, OLTP), then describe each table and column in plain language — delta-only, so a schema change documents the new tables and leaves the rest untouched.
5. Embedding & semantic model — vectorize schema, rules, and descriptions for retrieval, and assemble the semantic model the agent grounds on.

At query time, grounding is served by a three-tier cache — in-process, then Redis/Valkey, then vector search — so the common path never touches the model. The agent pulls the relevant slice of schema, relationships, and business rules for the question at hand instead of stuffing the whole catalog into context. Human-authored rules sit alongside the learned metadata: cancelled bookings don't count toward revenue becomes a fact the agent applies without being asked.

DeepSQL's agent doesn't emit a single guess. It works a problem the way a careful engineer does: ground on what it retrieved, write a statement, run it, read the result, and correct. It reaches the database only through a small, governed tool surface — never raw credentials — so every action it can take is one the platform already permits.

• Grounding tools — retrieve brain context, schema, business rules, and inferred relationships for the question, scoped to what the caller may see.
• Execution tools — run SQL and analyze query plans, always through the same policy guard and access checks as a human request; the agent's own path is read-only, and any write stays an explicit admin action.
• Verification — the loop that separates this from prompt-and-hope: after writing SQL, the agent executes it and inspects the returned rows. Wrong window, a text value where a number belongs, an implausible total — it fixes the query and re-runs until the data checks out, then answers.

The same runtime backs every surface. A question in Slack, a request from an AI IDE over MCP, and a dashboard build in the web app are the same agent with the same tools and the same guards — not three separate integrations drifting apart.

A plain-English question becomes a governed, checked result along a fixed path. Grounding narrows the search space; the guard makes the query safe; verification makes the answer trustworthy. The loop back from verification is the point — the agent is allowed to be wrong, briefly, in private.

fix & re-run until the data checks out → Verified answer

Figure 2. Every step — grounding, drafting, guarding, executing, verifying — runs under the same access scope as the caller. Steps 02, 04, 06 (accented) are the ones a bare text-to-SQL tool skips.

The agent is powerful, so the platform is conservative. Safety is enforced at the layer the agent cannot route around — the execution path itself — not by asking the model to behave.

• Read-only by default, enforced at the execution layer. On the paths the agent uses, a SQL guard parses every statement and rejects anything but SELECT, WITH, and EXPLAIN, and a read-only execution context enforces it again — so a prompt injection or a model mistake cannot become a write.
• Writes are explicit and role-gated. Where a workflow genuinely needs to write, an admin runs the statement through a separate, two-step confirmation flow. Write privilege is a role, not a default — the agent never mutates data on its own.
• Identity-scoped, always. Access control runs with the caller's identity on every request, agent-initiated or not. The agent can only read what the person behind it can read; there is no privileged back channel.
• Generated dashboards are contained. A dashboard is agent-written HTML, so it runs in a sandboxed iframe with an opaque origin and a strict content-security policy — no external network. It fetches data only through a read-only broker, so the agent's creative freedom never widens the blast radius.
• Sharing is opt-in and revocable. Public dashboard links are off by default; when enabled they are read-only, connection-scoped, individually revocable, and can be password-protected. Revoking flips a single flag and every link stops resolving.

Most BI generators fill a template: pick a chart type, bind a column, hope. DeepSQL's agent instead codes a self-contained dashboard — layout, controls, charts — and, crucially, verifies each query against your data before it renders. A date filter is checked to fall inside its window; a hero metric that should be a name is confirmed to be text, not coerced to zero; totals are spot-checked for plausibility. Only a dashboard whose numbers hold up gets shown.

Because the output is real code running in a sandbox rather than a rigid spec, the ceiling is the agent's craft, not a fixed set of widgets — while every query underneath stays governed by the same read-only broker as everything else.

DeepSQL ships as a self-hosted stack — backend, agent runtime, vault, cache, vector store — brought up with Docker on your own infrastructure. Connection credentials are encrypted at rest and reached over SSH-aware tunnels; they never leave the boundary. The only outbound dependency is the model provider you choose — bring your own key, whether Azure OpenAI, OpenAI, a Bedrock model, or one you host yourself — and what crosses that line is schema text and prompts, not bulk rows and not secrets. For teams with hard data-residency requirements, the entire path — from question to grounded retrieval to governed execution — stays inside the perimeter you already control.

Honesty is part of the design. On an internal accuracy suite, DeepSQL answers correctly end-to-end roughly four times in five, against 100% for hand-written SQL on a schema the author already knows. That gap is the point: the suite measures cold schema discovery at scale — navigating a 540-table database with no prior familiarity — which is the job a new DBA faces too, not a query you've already tuned.

The corollary is a clear division of labor. For a bounded, known problem — tune this one query, recommend this index — a deterministic rule-and-statistics engine is more predictable and carries no hallucination surface, and DeepSQL is happy to call those same primitives. Its edge is the ambiguous, semantic, discovery-shaped work those tools were never built for. Verification narrows the gap on the agent's side; it does not close it, which is exactly why the agent's own path stays read-only and every write remains an explicit, admin-authorized decision.

More applications are being built by people who have never written a migration, read an execution plan, or tuned an index — and every one of those applications has a database. The distance between how fast a team can ship an app and how well it can operate the database underneath is widening. DeepSQL is built to close that distance: to give a growing organization the leverage of a senior DBA — grounded, governed, and verified — without the headcount, and without the data ever leaving home.