<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Yahya Gilany</title>
    <description>The latest articles on DEV Community by Yahya Gilany (@ygilany).</description>
    <link>https://dev.to/ygilany</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F40833%2F0cffe7e4-415b-4246-b92e-32a24bffbe60.png</url>
      <title>DEV Community: Yahya Gilany</title>
      <link>https://dev.to/ygilany</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/ygilany"/>
    <language>en</language>
    <item>
      <title>AskDB: AI-written SQL and charts, without AI seeing your data</title>
      <dc:creator>Yahya Gilany</dc:creator>
      <pubDate>Wed, 18 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/ygilany/askdb-ai-written-sql-and-charts-without-ai-seeing-your-data-2jdm</link>
      <guid>https://dev.to/ygilany/askdb-ai-written-sql-and-charts-without-ai-seeing-your-data-2jdm</guid>
      <description>&lt;p&gt;People want to use AI to run reports on their databases. They also don't want to give AI access to their database. It's a Catch-22.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AskDB&lt;/strong&gt; is an open-source TypeScript text-to-SQL toolkit: it turns a question into checked SQL for your app to run. The model sees your schema and the notes you write, never your data.&lt;/p&gt;

&lt;p&gt;Today I'm announcing the release candidate for AskDB 1.0. The current build is 1.0.0-rc.3.&lt;/p&gt;

&lt;p&gt;The whole flow in 41 seconds: &lt;a href="https://yahyagilany.io/videos/askdb-demo.mp4" rel="noopener noreferrer"&gt;watch the demo&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where NL-to-SQL goes wrong
&lt;/h2&gt;

&lt;p&gt;NL-to-SQL is an old problem. Systems that answer English questions from a database go back to BASEBALL (1961)&lt;sup id="fnref1"&gt;1&lt;/sup&gt; and LUNAR (1971)&lt;sup id="fnref2"&gt;2&lt;/sup&gt;. Studies of large language models such as OpenAI's Codex writing SQL go back to early 2022&lt;sup id="fnref3"&gt;3&lt;/sup&gt;. So the problem is not new.&lt;/p&gt;

&lt;p&gt;The problem now isn't generating plausible SQL. It's conveying all the business context, terms and lingo consistently, so the AI generates SQL that's correct, not just plausible. It's in what the schema doesn't say, and in what the LLM assumes or hallucinates.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;For example:&lt;/strong&gt; a model that sees &lt;code&gt;orders.total_amount integer&lt;/code&gt; doesn't know the amount is stored in cents. It doesn't know that when your finance team says "sales" they mean paid orders, not every order. Those facts live in people's heads, or have to be explained to the model every time someone asks a question.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;What you want is to write those nuances down once, as notes on the schema, keep them in version control where you can keep improving them, and have them reach the model the same way on every question. That's what &lt;strong&gt;AskDB&lt;/strong&gt; does.&lt;/p&gt;

&lt;h2&gt;
  
  
  What that looks like
&lt;/h2&gt;

&lt;p&gt;Here's a snippet of a schema from the repo's test fixtures. The &lt;code&gt;orders&lt;/code&gt; table has no &lt;code&gt;sales&lt;/code&gt; column. "Sales" is a business word, defined in the schema's Markdown. Here's part of &lt;code&gt;tables/orders.md&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;---
id: table:public.orders
name: orders
...
columns:
  &lt;span class="k"&gt;- &lt;/span&gt;id: table:public.orders#total_amount
    aliases: [revenue, sale_amount]
    description: Stored in cents. Use &lt;span class="sb"&gt;`total_amount / 100.0`&lt;/span&gt; for dollar values.
  ...
---

&lt;span class="gu"&gt;## Common query language
&lt;/span&gt;
&lt;span class="k"&gt;- &lt;/span&gt;"sales" usually means paid orders (&lt;span class="sb"&gt;`status = 'paid'`&lt;/span&gt;)
&lt;span class="k"&gt;- &lt;/span&gt;"revenue" usually means &lt;span class="sb"&gt;`sum(total_amount)`&lt;/span&gt; where &lt;span class="sb"&gt;`status = 'paid'`&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The question is "How much did we make in sales, in dollars?" This is the schema part of the prompt AskDB built for it:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdc048baln0ccy07lg6pu.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdc048baln0ccy07lg6pu.png" alt="The prompt AskDB built for the question, with its parts colour-coded: the physical schema of the orders table, its aliases, the notes from tables/orders.md (including &amp;quot;Stored in cents. Use total_amount / 100.0&amp;quot; and &amp;quot;sales usually means paid orders&amp;quot;), the Revenue concept from concepts.md, and the question at the end. No rows." width="800" height="639"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;
  The prompt as text
  &lt;br&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Database schema:
TABLE public.users -- aliases: accounts, members
-- Registered user accounts. One row per signed-up user.
  - id uuid (PK NOT NULL) -- aliases: user_id
  - email text (NOT NULL) (sensitive)
  - created_at timestamptz (NOT NULL) -- aliases: signup_date, registered_at; When the user account was created.
-- common query language --
-- - "users" and "members" refer to this table
-- - "new users" usually means accounts created in the selected date range
-- - "active users" typically means users who placed at least one order
-- business context --
-- Each user has a unique email address used for login. The `email` column is sensitive — filter on it only when necessary and never display it in group-by reports.

TABLE public.orders -- aliases: purchases, sales, transactions
-- Customer purchase orders. One row per submitted order.
  - id uuid (PK NOT NULL) -- aliases: order_id
  - user_id uuid (NOT NULL)
  - status text (NOT NULL) -- aliases: order_status; values: pending|paid|shipped|cancelled; Order lifecycle state. Most reporting filters on `paid`.
  - total_amount integer (NOT NULL) -- aliases: revenue, sale_amount; Stored in cents. Use `total_amount / 100.0` for dollar values.
  FK (user_id) -&amp;gt; public.users (id)
-- common query language --
-- - "sales" usually means paid orders (`status = 'paid'`)
-- - "revenue" usually means `sum(total_amount)` where `status = 'paid'`
-- - "new orders" usually means orders created in the selected date range
-- business context --
-- Orders move through `pending → paid → shipped` and may end in `cancelled`. The `total_amount` column is stored in cents.

-- concepts --
-- Customer; synonyms: user, client, buyer, account holder; links: public.users; A person who has signed up and placed at least one order.
-- Revenue; synonyms: sales, gross sales, top line; links: public.orders.total_amount; Sum of `orders.total_amount` where `status = 'paid'`, expressed in cents.

Question: How much did we make in sales, in dollars?
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;




&lt;p&gt;&lt;/p&gt;

&lt;p&gt;It isn't DDL or SQL. It's a condensed format of the tables and the notes written about them.&lt;/p&gt;

&lt;p&gt;Everything the model needs is in that text: "sales" means &lt;code&gt;paid&lt;/code&gt;, and amounts are in cents. Concepts that span more than one table, like the Revenue concept at the bottom, come from a second file, &lt;code&gt;concepts.md&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The call is one function in &lt;code&gt;@askdb/core&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;ask&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;loadSchema&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@askdb/core"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;openai&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@ai-sdk/openai"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;ask&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;question&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"How much did we make in sales, in dollars?"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;schema&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;loadSchema&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"./schema"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// the schema artifact directory&lt;/span&gt;
  &lt;span class="n"&gt;dialect&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"postgres"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;openai&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"gpt-4o-mini"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// any Vercel AI SDK model object&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;code&gt;@askdb/core&lt;/code&gt; 1.0.0-rc.3 and OpenAI's &lt;code&gt;gpt-4o-mini&lt;/code&gt;, it returned this (trimmed):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"sql"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"SELECT SUM(total_amount) / 100.0 AS sales_in_dollars\nFROM public.orders\nWHERE status = 'paid';"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"verdict"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"outcome"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"allow"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"findings"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"sensitiveGuardrail"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"passed"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"references"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"unboundSql"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"SELECT SUM(total_amount) / 100.0 AS sales_in_dollars\nFROM public.orders\nWHERE status = $1;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"params"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"paid"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The model divided by 100 and filtered on &lt;code&gt;paid&lt;/code&gt; because the notes told it to. &lt;code&gt;unboundSql&lt;/code&gt; and &lt;code&gt;params&lt;/code&gt; are the same query with its values pulled out, ready for your driver to bind.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F83uv0v6u24gid3ov7cwc.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F83uv0v6u24gid3ov7cwc.png" alt="Two notes in the schema and the SQL they produced: the note &amp;quot;Stored in cents. Use / 100.0&amp;quot; points to the / 100.0 in the SELECT, and &amp;quot;sales usually means paid orders&amp;quot; points to WHERE status = 'paid'." width="800" height="376"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;verdict&lt;/code&gt; comes from AskDB's checks, which run on every SQL string before your code sees it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The schema artifact
&lt;/h2&gt;

&lt;p&gt;AskDB keeps what it knows about your database in one directory, the schema artifact. It has two layers.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2xo0gscv61gjwz3mmoze.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2xo0gscv61gjwz3mmoze.png" alt="The two layers of the schema artifact. The physical layer, schema.json, is written by askdb introspect from the database catalogs: tables, columns, types, keys and relationships, with no sample values. The enrichment layer is Markdown that people write: descriptions, aliases, common query language, business context and concepts. Both go into the prompt with the question." width="800" height="488"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The physical layer&lt;/strong&gt; (&lt;code&gt;schema.json&lt;/code&gt;): the tables, columns, types, keys and relationships. &lt;code&gt;askdb introspect&lt;/code&gt; writes it by reading the database catalogs (&lt;code&gt;information_schema&lt;/code&gt;, &lt;code&gt;pg_catalog&lt;/code&gt;, &lt;code&gt;sys.*&lt;/code&gt;, &lt;code&gt;sqlite_master&lt;/code&gt;). Introspection collects no sample values.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The enrichment layer&lt;/strong&gt; (the Markdown files): one file per table or concept you choose to describe, written by people. You can write those files by hand or in Studio (more on that below). Because it's all files, your data team reviews a change to "what sales means" in a pull request, and you can see line by line what the model will receive.&lt;/p&gt;

&lt;p&gt;The physical layer is enough for SQL that runs. The enrichment layer is what makes it right for the business. Without the two notes above, the model could just as well have summed every order and reported cents as dollars: valid SQL, wrong answer.&lt;/p&gt;

&lt;p&gt;When you ask a question, AskDB folds the two layers into the compact text you saw above and sends it to the model with your question. It holds back the notes on any sensitive table or column, and the example questions, which are there for retrieval.&lt;/p&gt;

&lt;p&gt;A large schema is too big to send whole on every question. Past about 22 tables, or when the rendered schema routinely passes 8K tokens, turn on retrieval with &lt;code&gt;@askdb/rag&lt;/code&gt;. It indexes the same artifact in a vector store and puts only the relevant slice into each prompt. &lt;code&gt;@askdb/rag&lt;/code&gt; stays on 0.x at 1.0, so its API may still move.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;ask()&lt;/code&gt; takes no database connection, so it never sees your rows or query results and can't send them. Introspection connects only at build time to read the catalogs. It sends nothing to a model. A value reaches the prompt only as text you wrote into the artifact, such as an &lt;code&gt;enum&lt;/code&gt; list, or text the user typed in the question. Two caveats. Anything you write in the Markdown goes to the model verbatim. A label you pass in &lt;code&gt;tenantScope.context&lt;/code&gt;, such as a customer's name, goes into the prompt as written too. And as you'd expect, retrieval adds a second provider: your embedding model receives every schema chunk when you build the index, and the question on each call.&lt;/p&gt;

&lt;h3&gt;
  
  
  Studio: enrich and test before you ship
&lt;/h3&gt;

&lt;p&gt;You don't have to write the Markdown by hand. &lt;code&gt;npx askdb studio&lt;/code&gt; opens AskDB Studio, a local web app on your machine that reads and writes the schema artifact directly. It's where I'd start: describe a table, add its aliases and common query language, then ask a question in the Playground and read the SQL and its check results. If the SQL isn't what you expected, tighten the notes and ask again, without leaving the tab. That loop (enrich, ask, re-enrich) is how you get reliable SQL for the words your team uses, before any of it touches your application.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fln9zl25b4437fmv15zpc.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fln9zl25b4437fmv15zpc.png" alt="AskDB Studio's Tables view: the list of tables on the left, and the Enrichment tab for one table on the right, with fields for its description, aliases, common query language and example questions, each with a Suggest button that drafts it with your model." width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Studio can also draft descriptions and aliases with your model for you to confirm. For a draft, it sends the model the table's column definitions and the names of up to four linked tables. Running the Playground's SQL against your database is off by default; turning it on means giving Studio a read-only role. Studio is still on 0.x at 1.0, so its UI may change. The &lt;a href="https://askdb.tools/studio/" rel="noopener noreferrer"&gt;Studio tour&lt;/a&gt; walks through every view.&lt;/p&gt;

&lt;h2&gt;
  
  
  When retrieval leaves out a table
&lt;/h2&gt;

&lt;p&gt;Retrieval puts a table in the prompt only when one of the chunks it returns points to that table. Writing this blog, I hit the failure that follows from that.&lt;/p&gt;

&lt;p&gt;On a made-up 63-table SaaS schema, I asked "What's our monthly recurring revenue from active subscriptions?" Only &lt;code&gt;subscriptions&lt;/code&gt; was described, with the rule for an active subscription. Retrieval returned chunks from &lt;code&gt;subscriptions&lt;/code&gt;, &lt;code&gt;usage_records&lt;/code&gt; and &lt;code&gt;subscription_events&lt;/code&gt;. It didn't return &lt;code&gt;plans&lt;/code&gt;, where the prices live. The model never saw a price, so it counted the active subscriptions and multiplied by 10. The answer was $20. The right answer was $38. The SQL was a valid read-only query, so every check passed.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ferqyqqcer48krqmuuk2u.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ferqyqqcer48krqmuuk2u.png" alt="Bar charts of retrieval similarity scores, before and after. Before, the top 8 chunks are all subscription and usage tables, no plans table, and the model answered $20. After adding plans.md and an MRR concept, concept:mrr (0.593) and plans#biz (0.576) rank first, plans is in the prompt, and the answer is $38." width="800" height="874"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The fix was two files:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;code&gt;tables/plans.md&lt;/code&gt; gave the table a description, aliases such as "subscription plans" and a business-context line saying MRR is built from &lt;code&gt;plans.monthly_price&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;concepts.md&lt;/code&gt; got a monthly recurring revenue concept that links &lt;code&gt;subscriptions&lt;/code&gt; and &lt;code&gt;plans&lt;/code&gt;; when retrieval returns a concept, AskDB puts every table it links into the prompt. After re-indexing, the concept and the &lt;code&gt;plans&lt;/code&gt; notes ranked first, and three runs out of three joined &lt;code&gt;plans&lt;/code&gt; and returned 38.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The lesson is the same one the checks teach: they test the query's shape, not its numbers. Test the questions your users ask. The tutorial &lt;a href="https://askdb.tools/find-the-right-tables/" rel="noopener noreferrer"&gt;Find the right tables in a large schema&lt;/a&gt; walks through this case with the real output.&lt;/p&gt;

&lt;h2&gt;
  
  
  Your app runs the SQL
&lt;/h2&gt;

&lt;p&gt;The library, the CLI and the HTTP API return SQL and never execute it. Your application runs it under its own database role. The one exception is Studio's Playground Execute button, a local development tool that's off by default.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F8uiutalt2vhsts5jweat.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F8uiutalt2vhsts5jweat.png" alt="A sequence diagram of one question: your app sends the question to AskDB, AskDB sends the question and schema text to your model, the model returns SQL, AskDB checks it and returns it to your app, and your app runs it read-only against your database and gets the rows. Rows, credentials and results never go to the model." width="800" height="528"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;I made this choice because the database role you already trust to run queries should be what bounds generated SQL. AskDB doesn't host inference either: you bring the model and the key, and it doesn't proxy, log or cache the requests. Use one of &lt;code&gt;@askdb/ai&lt;/code&gt;'s built-in providers (OpenAI, Anthropic, Google, Azure, Vercel AI Gateway) or pass any Vercel AI SDK model object to &lt;code&gt;ask()&lt;/code&gt;. &lt;code&gt;@askdb/ai&lt;/code&gt; uses the Vercel AI SDK under the hood, so the choice is between passing in the model your app already uses and letting &lt;code&gt;@askdb/ai&lt;/code&gt; build one from your AskDB config.&lt;/p&gt;

&lt;h2&gt;
  
  
  The three checks
&lt;/h2&gt;

&lt;p&gt;AskDB runs three checks on the returned SQL before passing it back to you:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The &lt;a href="https://askdb.tools/reference/sql-checks/#the-read-only-check" rel="noopener noreferrer"&gt;read-only check&lt;/a&gt;, on for every built-in dialect. It makes sure no data-changing statement (&lt;code&gt;UPDATE&lt;/code&gt;, &lt;code&gt;INSERT&lt;/code&gt;, &lt;code&gt;DELETE&lt;/code&gt; and the like) comes back.&lt;/li&gt;
&lt;li&gt;The &lt;a href="https://askdb.tools/reference/sql-checks/#the-tenant-check" rel="noopener noreferrer"&gt;tenant check&lt;/a&gt;, on when the schema has a &lt;code&gt;tenant-policy.md&lt;/code&gt; and the caller's scope isn't global.&lt;/li&gt;
&lt;li&gt;The &lt;a href="https://askdb.tools/reference/sql-checks/#the-sensitive-check" rel="noopener noreferrer"&gt;sensitive check&lt;/a&gt;, on when something is marked sensitive.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;To show refusals, I stubbed the model to return SQL I wrote. The errors below are AskDB's real output on rc.3.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;DELETE FROM orders WHERE status = 'cancelled';&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"SqlValidationError"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"SQL must start with SELECT or WITH (got 'delete')."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"verdict"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"outcome"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"deny"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"findings"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nl"&gt;"check"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"read-only"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"form"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"sql"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"rule"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"SQL_NOT_SELECT_OR_WITH"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"SQL must start with SELECT or WITH (got 'delete')."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"hint"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Regenerate as a read-only SELECT (optionally with WITH). INSERT/UPDATE/DELETE and procedural calls are blocked in dev guardrails."&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;SELECT COUNT(*) FROM orders; DROP TABLE users;&lt;/code&gt; is refused with rule &lt;code&gt;SQL_MULTI_STATEMENT&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;With a tenant policy that scopes &lt;code&gt;orders&lt;/code&gt; by &lt;code&gt;agency_id&lt;/code&gt;, &lt;code&gt;SELECT COUNT(*) FROM orders;&lt;/code&gt; throws &lt;code&gt;TenantGuardrailError&lt;/code&gt; with rule &lt;code&gt;MISSING_TENANT_PREDICATE&lt;/code&gt;: "Tenant-scoped table 'orders' is missing required tenant predicate. Expected one of: agency_id, …" Adding &lt;code&gt;OR 1 = 1&lt;/code&gt; next to a correct predicate gets the same refusal. When the predicate is there, AskDB binds the tenant ID as a driver parameter (&lt;code&gt;$1&lt;/code&gt;) and returns it in &lt;code&gt;tenantParams&lt;/code&gt; for your driver.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;SELECT id, email FROM users;&lt;/code&gt; comes back with &lt;code&gt;"outcome": "warn"&lt;/code&gt; and a &lt;code&gt;SENSITIVE_COLUMN_REFERENCED&lt;/code&gt; finding. In strict mode it throws &lt;code&gt;SensitiveReferenceError&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  The database is the boundary
&lt;/h2&gt;

&lt;p&gt;AskDB doesn't parse SQL. The checks are token- and pattern-based. They catch the common ways a model gets it wrong, and unusual or adversarial SQL can get past them. The database role your application uses is the boundary. The CLI's own &lt;code&gt;--explain&lt;/code&gt; output says so:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;"remediationNote": "Heuristic, lexer-based defense-in-depth checks only—not a SQL parser and not a security boundary. Execute generated SQL under a read-only database role, and review it before trusted execution."
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run generated SQL under a read-only, least-privilege role. Enforce tenant isolation in the database, for example with Postgres row-level security. Set statement timeouts and cap the rows you read. AskDB never adds a tenant filter, a row limit or a timeout to the SQL.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fud0vku9mhybpme3m4xqe.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fud0vku9mhybpme3m4xqe.png" alt="Three gates between a model's SQL and your data: AskDB's checks (pattern matching, which can miss), your app's review, and your database role (read-only, row-level security, timeouts, row cap), which is the boundary." width="800" height="392"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  An experimental chart planner
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;@askdb/client/charts&lt;/code&gt; asks your model to plan a chart from the question, the query with its literal values masked, and the result's column names, column kinds (date, currency, category, measure…), row count and truncated flag. The model never sees the rows. If you keep sensitive columns out of prompts, pass that setting and the schema artifact to &lt;code&gt;planChart()&lt;/code&gt;, and the model gets no SQL or column name that touches a sensitive column. It returns a chart spec, and your app draws the chart from its own data. A minor release of &lt;code&gt;@askdb/client&lt;/code&gt; may change it; it's outside the 1.0 API freeze. The tutorial &lt;a href="https://askdb.tools/chart-your-first-answer/" rel="noopener noreferrer"&gt;Chart your first answer&lt;/a&gt; adds a chart to the Quickstart's project.&lt;/p&gt;

&lt;h2&gt;
  
  
  Known limits
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Little system-schema filtering. With a tenant policy, rc.3's tenant check refuses Postgres's planner-statistics relations (&lt;code&gt;pg_stats&lt;/code&gt; and its relatives). Other queries against &lt;code&gt;pg_catalog&lt;/code&gt;, &lt;code&gt;information_schema&lt;/code&gt; or SQL Server's &lt;code&gt;sys&lt;/code&gt; aren't rejected. - A call to one of your own functions that writes passes the checks, and so does an expensive join.&lt;/li&gt;
&lt;li&gt;No protection from prompt injection. Anyone who can write the question or the schema Markdown can influence the SQL.&lt;/li&gt;
&lt;li&gt;No protection from untrusted schema files. Whoever can write the schema directory changes what AskDB loads and what the model sees. Load schema files only from sources you trust.&lt;/li&gt;
&lt;li&gt;MySQL's &lt;code&gt;ANSI_QUOTES&lt;/code&gt; mode isn't supported. MySQL and MariaDB have no row-level security policies, and SQLite has no users or grants, so use a database per tenant there.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The 1.0 support claim covers five engine families: PostgreSQL, MySQL, MariaDB, SQLite and SQL Server. CockroachDB has a built-in dialect that reuses the Postgres spec, but it's outside the 1.0 claim: the end-to-end tests don't cover it.&lt;/p&gt;

&lt;p&gt;AskDB is for engineers who embed it in a Node app, a CLI workflow or an HTTP service and own the schema, the keys and execution. Analysts use it through an app someone built on it. It doesn't guarantee business correctness: a person still reviews critical queries.&lt;/p&gt;

&lt;p&gt;At 1.0, AskDB stops at the SQL behind a report. Reports and a first-party MCP server are planned for after 1.0. Until then, agents use the CLI and the HTTP API.&lt;/p&gt;

&lt;h2&gt;
  
  
  Try it
&lt;/h2&gt;

&lt;p&gt;You need Node.js 22.23.4 or newer.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install --save-dev askdb
npx askdb init --yes --database sqlite --sqlite-file ./shop.db
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The RC is on npm's &lt;code&gt;latest&lt;/code&gt; tag, so a plain install gets it. If you're coming from a &lt;code&gt;0.x&lt;/code&gt; version, update the range in your &lt;code&gt;package.json&lt;/code&gt;: a &lt;code&gt;0.x&lt;/code&gt; range won't match &lt;code&gt;1.0.0-rc.3&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://askdb.tools/quickstart/" rel="noopener noreferrer"&gt;Quickstart&lt;/a&gt; goes from install to running the returned SQL on a small SQLite shop database. The code is at &lt;a href="https://github.com/Ygilany/AskDB" rel="noopener noreferrer"&gt;github.com/Ygilany/AskDB&lt;/a&gt;, Apache-2.0.&lt;/p&gt;

&lt;p&gt;This is a release candidate, and I need people to try it before 1.0.0. Point it at your own schema, ask it the questions your team asks, and tell me what breaks. Issues, ideas and pull requests are all welcome; &lt;a href="https://github.com/Ygilany/AskDB/blob/main/CONTRIBUTING.md" rel="noopener noreferrer"&gt;CONTRIBUTING.md&lt;/a&gt; has the setup.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Something broke, the Quickstart tripped you up, or a docs page doesn't match the code: open an issue.&lt;/li&gt;
&lt;li&gt;A business term you couldn't express in the schema artifact: start a thread in Discussions → Ideas.&lt;/li&gt;
&lt;li&gt;SQL that gets past a check it should fail: report it privately at &lt;a href="https://github.com/Ygilany/AskDB/security/advisories/new" rel="noopener noreferrer"&gt;github.com/Ygilany/AskDB/security/advisories/new&lt;/a&gt; (see the &lt;a href="https://github.com/Ygilany/AskDB/blob/main/SECURITY.md" rel="noopener noreferrer"&gt;security policy&lt;/a&gt;); when the policy treats it as a vulnerability, I publish an advisory for it.&lt;/li&gt;
&lt;/ul&gt;




&lt;ol&gt;

&lt;li id="fn1"&gt;
&lt;p&gt;Bert F. Green, Alice K. Wolf, Carol Chomsky and Kenneth Laughery, "&lt;a href="https://doi.org/10.1145/1460690.1460714" rel="noopener noreferrer"&gt;Baseball: an automatic question-answerer&lt;/a&gt;," Western Joint IRE-AIEE-ACM Computer Conference, 1961.&amp;nbsp;↩&lt;/p&gt;
&lt;/li&gt;

&lt;li id="fn2"&gt;
&lt;p&gt;William A. Woods, "&lt;a href="https://doi.org/10.1145/1499586.1499695" rel="noopener noreferrer"&gt;Progress in natural language understanding: an application to lunar geology&lt;/a&gt;," AFIPS National Computer Conference, 1973. LUNAR was first shown at the Second Lunar Science Conference in 1971.&amp;nbsp;↩&lt;/p&gt;
&lt;/li&gt;

&lt;li id="fn3"&gt;
&lt;p&gt;Nitarshan Rajkumar, Raymond Li and Dzmitry Bahdanau, "&lt;a href="https://arxiv.org/abs/2204.00498" rel="noopener noreferrer"&gt;Evaluating the Text-to-SQL Capabilities of Large Language Models&lt;/a&gt;," arXiv, March 2022.&amp;nbsp;↩&lt;/p&gt;
&lt;/li&gt;

&lt;/ol&gt;

</description>
      <category>typescript</category>
      <category>sql</category>
      <category>ai</category>
      <category>opensource</category>
    </item>
  </channel>
</rss>
