How AskDB works

The pipeline

AskDB is a function that turns a question and a schema artifact into checked SQL. Everything else — execution, approval, audit — happens in your application, not in AskDB.

The five steps

When you call ask() (or the equivalent CLI / HTTP surface), AskDB runs these steps in order:

1. Load the schema artifact. A directory, a bundle file, or a parsed schema.json — whichever you supply.
2. Retrieve relevant chunks (optional). For large schemas, AskDB pulls only the slice of the artifact that’s relevant to the question, using @askdb/rag. Smaller schemas skip this step.
3. Build the prompt. Physical metadata, any table descriptions you authored, and the selected SQL dialect get assembled into the context the model sees.
4. Generate. AskDB calls the model you supplied — any provider compatible with the Vercel AI SDK — and the model returns SQL. AskDB does not host inference; your key, your billing.
5. Check. The returned SQL goes through AskDB’s heuristic guardrails: single statement (with a SQL Server caveat), must start with SELECT or WITH, no comments, no DDL/DML keywords, no calls to known side-effecting functions. SQL that fails these is rejected. When your artifact declares a tenant policy or sensitive markers, the tenant and sensitive-column checks also run. Depending on their mode, they either reject the SQL or return it with warnings. These checks catch common model mistakes but aren’t a security boundary. The exact checks, and what they miss, are in Safety boundaries.

The return value is a string of checked SQL and a parameter list. What happens next is your call.

The runtime boundary

AskDB stops at checked SQL. Your application — the code that imports @askdb/core or calls the HTTP API — owns everything past that:

• The database driver and connection pool.
• Read-only roles and any further row-level security.
• Query timeouts, row limits, and result pagination.
• Whether to show the SQL to the user, log it, queue it for review, or run it immediately.
• Audit logging and observability.

This split is intentional. AskDB is a code-generation step, not a runtime, so it slots into existing services and your existing security model: the database role you already trust to run queries is the one that bounds what generated SQL can do.

Where the model lives

You bring the model. AskDB calls whatever provider you wire in — typically through the Vercel AI SDK — using your API key. Requests go straight from your environment to the provider. AskDB does not proxy, log, or cache them.

The same model never sees your database connection, your credentials, or the rows your application returns. See Privacy model for the precise list of what crosses the boundary.

Read next

The schema artifactThe file the model reads — what’s in it, who owns it, how it evolves.Safety boundariesEvery check AskDB runs before returning SQL.Privacy modelWhat crosses the boundary to the model, and what doesn’t.Embed in a Node appPut the pipeline behind your own HTTP handler in twenty lines.