Quickstart

From zero to first query

Scaffold your config, point AskDB at your database, enrich the schema artifact, and ask your first question. The same packages drop straight into a Node service when you’re ready to embed.

Prerequisites

• Node 20 or newer.
• npm, pnpm, or yarn — tabbed examples adapt to your choice; standalone snippets use npx (substitute pnpm dlx or yarn dlx).
• An API key from a model provider — OpenAI, Anthropic, Google, Azure, or any OpenAI-compatible endpoint (OpenRouter, vLLM, Ollama, …). See Bring your own model.
• A database AskDB can read — Postgres, MySQL, SQLite, or SQL Server — or even a Prisma schema file (no live database required).

The whole flow, in four commands

npm

npx askdb@latest init        # scaffold askdb.config.ts
npx askdb introspect         # read your database into a schema artifact
npx askdb studio             # enrich the schema and test questions in your browser
npx askdb ask --question "Which customers signed up last week?"

pnpm

pnpm dlx askdb@latest init   # scaffold askdb.config.ts
pnpm dlx askdb introspect    # read your database into a schema artifact
pnpm dlx askdb studio        # enrich the schema and test questions in your browser
pnpm dlx askdb ask --question "Which customers signed up last week?"

yarn

yarn dlx askdb@latest init   # scaffold askdb.config.ts
yarn dlx askdb introspect    # read your database into a schema artifact
yarn dlx askdb studio        # enrich the schema and test questions in your browser
yarn dlx askdb ask --question "Which customers signed up last week?"

Each step is explained below. The loop that makes answers good: introspect once, then enrich and re-ask in Studio until the SQL matches how your team thinks about the data.

1. Scaffold your config

npx askdb@latest init

npx (like pnpm dlx and yarn dlx) downloads and runs askdb on the fly — no separate install step needed. In a terminal, askdb init opens a short wizard that asks which database you use, which AI provider you have a key for, and whether you want the Studio query playground. It then writes only the relevant config branches and installs only the packages your setup needs.

In CI or scripts, skip the wizard:

npx askdb@latest init --yes                           # Postgres + OpenAI defaults
npx askdb@latest init --yes --database sqlserver      # SQL Server instead
npx askdb@latest init --yes --database sqlite --sqlite-file SQLITE_FILE

Tip

askdb.config.ts is checked in; .env (your real keys) is not.

Note

Prefer the browser? Skip init and run npx askdb studio directly — with no config present, Studio opens a guided setup wizard that writes the config and runs introspection for you.

The generated config is tailored to what you chose — for example, a SQL Server setup:

import { defineConfig, env, type AskDbConfig } from "@askdb/config";

export default defineConfig({
  ai: {
    provider: "openai",
    providerConfig: { openai: { apiKey: env("OPENAI_API_KEY"), model: env("OPENAI_MODEL") } },
  },
  introspection: {
    provider: "sqlserver",
    providerConfig: { sqlserver: { databaseUrl: env("SQLSERVER_URL") } },
    outputDir: "./askdb",
  },
  rag: { embedder: "mock", embedderConfig: {}, store: "file", storeConfig: { file: {} } },
} satisfies AskDbConfig);

See the Configuration reference for every option. See CLI reference — askdb init for all flags.

Once this is configured, most CLI flags below are optional.

2. Introspect your database

Introspection produces an AskDB schema artifact — a directory on disk that captures your tables, columns, types, and relationships. That artifact is the only thing the model ever sees about your database.

Live database

With your database connection configured in askdb.config.ts under introspection.provider and introspection.providerConfig, one command is enough:

npx askdb introspect

For example, for Postgres:

introspection: {
  provider: "postgres",
  providerConfig: {
    postgres: { databaseUrl: env("DATABASE_URL") },  // env name is yours to pick
  },
},

The database is only used here — for introspection. To target a different database for one run, pass --url:

npx askdb introspect --url "$OTHER_DATABASE_URL"

The engine comes from introspection.provider in your config (or the --engine flag); the introspected artifact records it, and askdb ask later infers the SQL dialect from the artifact. The complete config surface is documented in the Configuration reference. For engine-specific install steps see Switch engines.

Prisma schema file

With your Prisma schema configured in askdb.config.ts under introspection.provider and introspection.providerConfig, one command is enough — no live database required:

npx askdb introspect

For example:

introspection: {
  provider: "prisma",
  providerConfig: {
    prisma: { schemaPath: "./prisma/schema.prisma" },
  },
},

To introspect a different schema file for one run, pass the flags instead:

npx askdb introspect --engine prisma --prisma-schema ./other/schema.prisma

3. Enrich and test in Studio

Raw introspection captures structure. Enrichment adds descriptions, aliases, business concepts, sensitive markers, and example questions — the layer that makes generation good.

Launch Studio — the recommended authoring surface — in a browser:

npx askdb studio

Studio is also the best place to test your questions: ask a question in the same session, review the generated SQL, and keep enriching if the answer isn’t what you expected — all without switching tools. See the Studio tour for what each view does.

Studio reads outputDir from askdb.config.ts, so no flags are needed. The full walkthrough lives in Author your schema.

4. Ask your question

You have two ways to test that your schema is generating good SQL — pick whichever fits the moment.

In Studio (recommended)

If Studio is already open from step 3, ask your question there. You’ll see the generated SQL alongside the schema; if the answer isn’t right, keep enriching descriptions, aliases, or concepts and re-ask in the same session.

Asking in Studio isn’t the destination — it’s how you dial in the enrichment until the SQL satisfies what your users actually need. Once you’re happy with the answers, you embed the same schema artifact into your own app or service (see step 5) — Studio was just the place you tuned it.

From the CLI

For one-off checks and CI smoke tests, ask directly from the terminal:

npx askdb ask --question "Which customers signed up last week?"

You get validated SQL on stdout — for example:

SELECT c.id, c.name, c.signed_up_at
FROM customers AS c
WHERE c.signed_up_at >= NOW() - INTERVAL '7 days'
ORDER BY c.signed_up_at DESC;

In both cases AskDB returns validated SQL. It does not run it against your database — your application owns execution.

5. From here

Now that the CLI works, pick the path that matches what you’re building:

Embed in a Node appDrop @askdb/client into a TypeScript service and run the SQL through your own pool.Deploy as HTTP serviceStand up @askdb/http-api so Python, browsers, or agents can ask questions.Author your schemaGet the most out of Studio: descriptions, concepts, sensitive markers, tenant policy.How AskDB worksThe end-to-end flow, with all the moving parts.

Want to skip the steps above and explore a runnable script? The examples/ask-question package in the repo shows the same createAskDb and direct ask() patterns against a live schema.