Modes and dialects

Adapting to your stack

Two knobs you tune per deployment: the dialect (which SQL flavor AskDB generates and validates) and the mode (what may enter the model’s context beyond the schema artifact and the question).

Dialects

A dialect is a DialectSpec built into @askdb/core — all four ship with the core package. It tells the pipeline how to:

Construct identifiers and quoting for this engine.
Format dialect-specific clauses (LIMIT vs TOP, dollar parameters vs question marks, JSON path syntax).
Validate what counts as a read-only SELECT on this engine.

The per-engine packages add introspection for their engine and re-export its dialect constant; ask() itself needs only the dialect id. The CLI resolves the id automatically: dialect in askdb.config.ts → the provider recorded in the schema artifact (for Prisma artifacts, the datasource.provider from your .prisma file) → postgres.

Engine	Engine package (introspection)	Status
PostgreSQL	`@askdb/postgres`	Reference dialect.
MySQL	`@askdb/mysql`	First-class dialect and introspection.
SQLite	`@askdb/sqlite`	First-class dialect; works with embedded files.
SQL Server	`@askdb/sqlserver`	T-SQL dialect and introspection.

Switching engines is mostly a package swap. The full migration checklist lives in Switch engines.

Modes

A mode declares the trust boundary AskDB enforces for a run: what’s allowed to enter model context beyond the schema artifact and the natural-language question. Today there are two values.

Set the mode three ways, highest precedence first:

--mode <id> on any CLI command.
modes.askdbMode in askdb.config.ts.
The built-in default (schema_only).

`schema_only` (default)

AskDB grounds generation in the schema artifact and returns SQL only. The model never sees rows, credentials, or query results. This is the right mode for almost every production deployment.

askdb ask \
  --question "How many orders this week?" \
  --mode schema_only

`bounded_results`

Today, bounded_results produces the exact same SQL as schema_only — the NL-to-SQL pipeline does not differ, and AskDB surfaces still return SQL only. The mode value is reserved for a forward-looking extension: a post-execute step where a host application may summarize bounded tabular results back through the model. Until that branch ships, picking bounded_results over schema_only changes nothing observable.

askdb ask \
  --question "Show recent signups" \
  --mode bounded_results

The versioned spec — including the contracts an eventual bounded-results implementation must honor — lives in docs/contracts/modes-v1.md on GitHub.

Sensitive fields

Columns marked sensitive: true in the schema artifact can be:

Included with a sensitivity tag in the prompt (default), so the model knows to handle them carefully and your application can decide whether to display them.
Omitted from the prompt entirely with modes.omitSensitiveFromPrompt: true in your config (or the --omit-sensitive-from-prompt flag), so the model never sees them and therefore never proposes them.

The complete behavior table is in the sensitive fields contract on GitHub.

Picking a mode

For most teams:

Start with schema_only. It’s the safest default.
Mark sensitive columns in your schema artifact early. Decide per deployment whether to include them tagged or omit them.
Don’t reach for bounded_results until you have a concrete need — most analytics use cases don’t.