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 (examples use npx).
• 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

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?"

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 downloads and runs askdb on the fly — no separate install step needed. askdb init creates askdb.config.ts in your project root. The config file is TypeScript-checked and reads values from your environment using the env() helper — it loads from a .env file at your project root or from the system environment, whichever is set. You choose your own variable names and pass them to env().

Tip

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

Open askdb.config.ts and fill in your settings:

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

export default defineConfig({
  ai: {
    provider: "openai",   // "openai" | "azure" | "foundry" | "google" | "anthropic" — or a custom string
    providerConfig: {
      openai: {
        apiKey: env("OPENAI_API_KEY"),
        model: env("OPENAI_MODEL"),   // optional — defaults to gpt-4o-mini
      },
    },
  },
  introspection: {
    provider: "postgres",            // "postgres" | "prisma" | "mysql" | "sqlite" | "sqlserver"
    providerConfig: {
      postgres: { databaseUrl: env("DATABASE_URL") },
    },
    outputDir: "./my-app.schema",    // optional — defaults to ./askdb/
  },
  // ... the scaffolded file also includes `rag`, `logging`, `studio`, and
  // `httpApi` sections — keep them as generated. Every option is documented
  // in the Configuration reference.
});

The snippet above is the part you’ll actually edit; the scaffolded template contains the full config. See the Configuration reference for every option.

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. Those artifacts’ content are 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.

Prefer the terminal? The TUI covers the same workflow:

npx askdb enrich

Both commands read outputDir from askdb.config.ts. 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/core 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.