QueryForge v0.0.4 — let your users ask your database anything, safely

[awsaman-ai]

Every text-to-SQL tool has the same hole in it: you cannot check what comes back.

You ask a model for SQL, and it hands you a statement that is only probably right. It may have invented a column. It may have quietly widened a filter. It may have dropped the one condition that kept a user inside their own tenant. Short of reading every query by hand — or running it and finding out — you have no way to know which.

QueryForge closes that hole by never letting the model near a query string.

How

The model fills in a form. Not prose, not SQL — a typed Query AST, constrained to a vocabulary your JSON config registers. Everything after that is ordinary deterministic Go you can test offline:

Natural language  →  [ AI planner ]  →  Query AST  →  [ generators ]  →  SQL / Mongo
   (unbounded)        model + config     (typed)       pure code, no AI, no network

Everything that has to be guaranteed lives on the right-hand side, where it can be proven rather than prompted.

res, err := engine.Translate(ctx, "cancelled orders over 200 dollars", "sql", nil)

res.Query.SQL   // SELECT … WHERE (status = $1 AND amount > $2) …
res.Query.Args  // [CANCELLED 200]
res.Explain     // a plain-English readback of what it understood

What that actually buys you

Invented a column?	Validation error with a "did you mean", before anything compiles.
SQL injection?	Not mitigated — unrepresentable. The model emits structure; values are bound, and only config-supplied identifiers ever reach the statement.
Asked to delete something?	There is no mutation node in the AST. The guarantee holds by construction, not by prompt.
Asked about a hidden field?	returnable: false is enforced on the default projection too, not only on an explicit select.
Asked for another tenant's rows?	Scope filters are AND-ed onto the root of the filter tree after validation, so A OR B becomes scope AND (A OR B) — and the model is never told the column exists.
Asked something impossible?	A typed refusal, not a plausible query built on a lookalike field.

Try it without installing anything

The config builder runs entirely in your browser — every option the loader knows, as a form, validated live against the same rules, with the finished JSON a click away. No server, no upload, no analytics, and it works offline once loaded.

Then:

go get github.com/awsaman-ai/queryforge

Core is standard library only. Apache-2.0. Read-only by design: every output is a SELECT or a find, and the library never connects to your database — it hands you the query, running it stays yours.

📖 Docs · 🧩 Configuration reference · 📦 pkg.go.dev

Where it is today

v0.0.4. Postgres SQL and MongoDB ship now. A backend is a generator over the AST, so adding one touches neither the planner, nor the validator, nor the prompt — that seam is the whole point of the design.

Models are a config change, never a code change: any OpenAI-compatible endpoint (Gemini, Groq, local Ollama) or the native Anthropic Messages API, with an ordered fallback chain so a rate limit on one provider transparently falls through to the next.

129 tests, all offline — the engine is exercised through a stub provider, so the suite needs no API key and burns no quota. CI runs them on Go 1.25 and 1.26 with the race detector, plus golangci-lint.

What I'd rather say out loud

It only answers what your config anticipated. This is not a replacement for a data analyst, and it will not explore a schema it was never told about. It is a way to put a natural-language filter box in front of your users and still be able to sleep.

And the bugs are public. bugs.csv is in the repo with every defect found during adversarial QA and how it was fixed — including a returnable: false leak on the default projection, and a genuinely nasty one where enabling JSON mode on a provider made its output less parseable, not more.

What would help most

I'd rather hear about the awkward cases than the easy ones.

• Which backend should come next? MySQL, SQLite, Elasticsearch, BigQuery, DynamoDB — or something I haven't thought of. If you have a real use for one, say which and why; that beats a guess.
• What would you want your users to be able to ask your own database? Concrete sentences are the most useful thing you can give me — they turn into test cases.
• Where does the config model break down for your schema? Joins, computed fields, polymorphic tables — I want to know where it stops fitting.

Questions of any size are welcome in Q&A; nothing is too basic. If you'd rather open an issue, that works too.